سرویس چت پیشرفته

سرویس چت پیشرفته به شما امکان می‌دهد از API چت گوگل در Apps Script استفاده کنید. این API به اسکریپت‌ها اجازه می‌دهد فضاهای چت را پیدا، ایجاد و تغییر دهند، اعضا را به فضاها اضافه یا حذف کنند و پیام‌های حاوی متن، کارت، پیوست و واکنش را بخوانند یا ارسال کنند.

پیش‌نیازها

مرجع

برای اطلاعات بیشتر در مورد این سرویس، به مستندات مرجع Chat API مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس Chat از همان اشیاء، متدها و پارامترهای API عمومی استفاده می‌کند.

کد نمونه

این نمونه‌ها به شما نشان می‌دهند که چگونه می‌توانید اقدامات رایج Google Chat API را با استفاده از سرویس پیشرفته انجام دهید.

ارسال پیام با اطلاعات کاربری

مثال زیر نحوه ارسال پیام به فضای چت از طرف کاربر را نشان می‌دهد.

  1. دامنه‌ی مجوز chat.messages.create را به فایل appsscript.json پروژه‌ی Apps Script اضافه کنید:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

  2. تابعی مانند این را به کد پروژه Apps Script اضافه کنید:

    پیشرفته/چت.gs
    /**
 * Posts a new message to the specified space on behalf of the user.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithUserCredentials(spaceName) {
  try {
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(message, spaceName);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

ارسال پیام با اطلاعات برنامه

مثال زیر نحوه ارسال پیام به فضای چت از طرف برنامه را نشان می‌دهد. استفاده از سرویس چت پیشرفته با یک حساب سرویس نیازی به تعیین محدوده مجوز در appsscript.json ندارد. برای جزئیات بیشتر در مورد احراز هویت با حساب‌های سرویس، به بخش احراز هویت به عنوان یک برنامه چت گوگل مراجعه کنید.

پیشرفته/چت.gs
/**
 * Posts a new message to the specified space on behalf of the app.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithAppCredentials(spaceName) {
  try {
    // See https://developers.google.com/chat/api/guides/auth/service-accounts
    // for details on how to obtain a service account OAuth token.
    const appToken = getToken_();
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(
      message,
      spaceName,
      {},
      // Authenticate with the service account token.
      { Authorization: `Bearer ${appToken}` },
    );
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

فضایی بدست آورید

مثال زیر نحوه دریافت اطلاعات در مورد یک فضای چت را نشان می‌دهد.

  1. دامنه‌ی مجوز chat.spaces.readonly را به فایل appsscript.json پروژه‌ی Apps Script اضافه کنید:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]

  2. تابعی مانند این را به کد پروژه Apps Script اضافه کنید:

    پیشرفته/چت.gs
    /**
 * Gets information about a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function getSpace(spaceName) {
  try {
    const space = Chat.Spaces.get(spaceName);
    console.log("Space display name: %s", space.displayName);
    console.log("Space type: %s", space.spaceType);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to get space with error %s", err.message);
  }
}

ایجاد یک فضا

مثال زیر نحوه ایجاد یک فضای چت را نشان می‌دهد.

  1. دامنه‌ی مجوز chat.spaces.create را به فایل appsscript.json پروژه‌ی Apps Script اضافه کنید:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]

  2. تابعی مانند این را به کد پروژه Apps Script اضافه کنید:

    پیشرفته/چت.gs
    /**
 * Creates a new Chat space.
 */
function createSpace() {
  try {
    const space = { displayName: "New Space", spaceType: "SPACE" };
    Chat.Spaces.create(space);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create space with error %s", err.message);
  }
}

فهرست عضویت‌ها

مثال زیر نحوه فهرست کردن تمام اعضای یک فضای چت را نشان می‌دهد.

  1. دامنه‌ی مجوز chat.memberships.readonly را به فایل appsscript.json پروژه‌ی Apps Script اضافه کنید:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]

  2. تابعی مانند این را به کد پروژه Apps Script اضافه کنید:

    پیشرفته/چت.gs
    /**
 * Lists all the members of a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function listMemberships(spaceName) {
  let response;
  let pageToken = null;
  try {
    do {
      response = Chat.Spaces.Members.list(spaceName, {
        pageSize: 10,
        pageToken: pageToken,
      });
      if (!response.memberships || response.memberships.length === 0) {
        pageToken = response.nextPageToken;
        continue;
      }
      for (const membership of response.memberships) {
        console.log(
          "Member: %s, Role: %s",
          membership.member.displayName,
          membership.role,
        );
      }
      pageToken = response.nextPageToken;
    } while (pageToken);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
}

عیب‌یابی

اگر با Error 400: invalid_scope به همراه پیام خطای « Some requested scopes cannot be shown مواجه شدید، به این معنی است که شما هیچ حوزه مجوزی را در فایل appsscript.json پروژه Apps Script مشخص نکرده‌اید. در بیشتر موارد، Apps Script به طور خودکار تعیین می‌کند که یک اسکریپت به چه حوزه‌هایی نیاز دارد، اما وقتی از سرویس پیشرفته Chat استفاده می‌کنید، باید حوزه‌های مجوزی را که اسکریپت شما استفاده می‌کند، به صورت دستی به فایل مانیفست پروژه Apps Script خود اضافه کنید. به بخش «تنظیم حوزه‌های صریح» مراجعه کنید.

برای رفع خطا، محدوده‌های مجوزدهی مناسب را به عنوان بخشی از آرایه oauthScopes به فایل appsscript.json پروژه Apps Script اضافه کنید. برای مثال، برای فراخوانی متد spaces.messages.create ، کد زیر را اضافه کنید: 

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

محدودیت‌ها و ملاحظات

سرویس چت پیشرفته از موارد زیر پشتیبانی نمی‌کند:

برای دانلود پیوست پیام یا فراخوانی متد پیش‌نمایش توسعه‌دهنده، به جای آن از UrlFetchApp استفاده کنید.