این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

پیش نیازها

یک برنامه Apps Script Google Chat که در صفحه پیکربندی Chat API در کنسول Google Cloud پیکربندی شده است. پروژه Apps Script برنامه باید به جای پروژه پیش‌فرض که به‌طور خودکار برای پروژه‌های Apps Script ایجاد می‌شود، از یک پروژه استاندارد Google Cloud استفاده کند. برای ایجاد یک برنامه Google Chat سازگار، به ساخت برنامه Google Chat با برنامه‌های اسکریپت مراجعه کنید.
احراز هویت برای برنامه چت پیکربندی شده است. انجام یک عمل از طرف یک کاربر نیاز به احراز هویت کاربر دارد. انجام یک عمل به عنوان برنامه گپ نیاز به احراز هویت برنامه با یک حساب سرویس دارد. برای بررسی اینکه یک روش Chat API از کدام شکل احراز هویت پشتیبانی می‌کند، به انواع احراز هویت مورد نیاز برای تماس‌های Google Chat API مراجعه کنید.

مرجع

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

کد نمونه

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

یک پیام با مشخصات کاربری ارسال کنید

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

دامنه مجوز chat.messages.create را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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

در GitHub مشاهده کنید

/**
 * 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);
  }
}

فضا بگیر

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

دامنه مجوز chat.spaces.readonly را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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);
  }
}
```

یک فضا ایجاد کنید

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

محدوده مجوز chat.spaces.create را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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);
  }
}
```

لیست عضویت ها

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

دامنه مجوز chat.memberships.readonly را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]
```

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

پیشرفته/chat.gs

در GitHub مشاهده کنید

/**
 * 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);
  }
}

عیب یابی

اگر Error 400: invalid_scope appsscript.json پیام 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"
]

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

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

روش Chat API media.download .
روش‌های Chat API موجود در پیش‌نمایش برنامه‌نویس

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

پیش نیازها

یک برنامه Apps Script Google Chat که در صفحه پیکربندی Chat API در کنسول Google Cloud پیکربندی شده است. پروژه Apps Script برنامه باید به جای پروژه پیش‌فرض که به‌طور خودکار برای پروژه‌های Apps Script ایجاد می‌شود، از یک پروژه استاندارد Google Cloud استفاده کند. برای ایجاد یک برنامه Google Chat سازگار، به ساخت برنامه Google Chat با برنامه‌های اسکریپت مراجعه کنید.
احراز هویت برای برنامه چت پیکربندی شده است. انجام یک عمل از طرف یک کاربر نیاز به احراز هویت کاربر دارد. انجام یک عمل به عنوان برنامه گپ نیاز به احراز هویت برنامه با یک حساب سرویس دارد. برای بررسی اینکه یک روش Chat API از کدام شکل احراز هویت پشتیبانی می‌کند، به انواع احراز هویت مورد نیاز برای تماس‌های Google Chat API مراجعه کنید.

مرجع

کد نمونه

یک پیام با مشخصات کاربری ارسال کنید

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

دامنه مجوز chat.messages.create را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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);
  }
}
```

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

پیشرفته/chat.gs

در GitHub مشاهده کنید

/**
 * 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);
  }
}

فضا بگیر

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

دامنه مجوز chat.spaces.readonly را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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);
  }
}
```

یک فضا ایجاد کنید

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

محدوده مجوز chat.spaces.create را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]
```
تابعی مانند این را به کد پروژه Apps Script اضافه کنید:
پیشرفته/chat.gs
در GitHub مشاهده کنید
```
/**
 * 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);
  }
}
```

لیست عضویت ها

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

دامنه مجوز chat.memberships.readonly را به فایل appsscript.json پروژه Apps Script اضافه کنید:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]
```

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

پیشرفته/chat.gs

در GitHub مشاهده کنید

/**
 * 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);
  }
}

عیب یابی

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

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

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

روش Chat API media.download .
روش‌های Chat API موجود در پیش‌نمایش برنامه‌نویس

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