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

سرویس گفتگوی پیشرفته به شما امکان می دهد از Google Chat 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 اضافه کنید:

    پیشرفته/chat.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 ندارد. برای جزئیات بیشتر درباره احراز هویت با حساب‌های سرویس، به تأیید اعتبار به‌عنوان برنامه گپ Google مراجعه کنید.

پیشرفته/chat.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 اضافه کنید:

    پیشرفته/chat.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 اضافه کنید:

    پیشرفته/chat.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 اضافه کنید:

    پیشرفته/chat.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;
      }
      response.memberships.forEach((membership) => console.log(
          'Member resource name: %s (type: %s)',
          membership.name,
          membership.member.type));
      pageToken = response.nextPageToken;
    } while (pageToken);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

عیب یابی

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

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

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

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

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

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