خدمة المحادثة المتقدّمة

تتيح لك خدمة Advanced Chat استخدام Google Chat API في Apps Script. تتيح واجهة برمجة التطبيقات هذه للبرامج النصية العثور على مساحات Chat وإنشائها وتعديلها، وإضافة أعضاء إلى المساحات أو إزالتهم منها، وقراءة الرسائل أو نشرها مع النصوص والبطاقات والمرفقات والتفاعلات.

المتطلبات الأساسية

مراجع

لمزيد من المعلومات حول هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية لواجهة برمجة التطبيقات Chat API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة Chat الكائنات والطُرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة.

نموذج التعليمات البرمجية

توضّح لك هذه النماذج كيفية تنفيذ الإجراءات الشائعة في Google Chat API باستخدام الخدمة المتقدّمة.

نشر رسالة باستخدام بيانات اعتماد المستخدم

يوضّح المثال التالي كيفية نشر رسالة في مساحة Chat نيابةً عن المستخدم.

  1. أضِف نطاق التفويض chat.messages.create إلى ملف appsscript.json في مشروع "برمجة التطبيقات":

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

  2. أضِف دالة مثل هذه إلى رمز مشروع "برمجة التطبيقات":

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

نشر رسالة تتضمّن بيانات اعتماد التطبيق

يوضّح المثال التالي كيفية نشر رسالة في مساحة Chat نيابةً عن التطبيق. لا يتطلّب استخدام خدمة Chat المتقدّمة مع حساب خدمة تحديد نطاقات التفويض في appsscript.json. لمعرفة تفاصيل حول المصادقة باستخدام حسابات الخدمة، يُرجى الاطّلاع على المصادقة كتطبيق Google Chat.

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

الحصول على مساحة

يوضّح المثال التالي كيفية الحصول على معلومات حول مساحة Chat.

  1. أضِف نطاق التفويض chat.spaces.readonly إلى ملف appsscript.json في مشروع "برمجة التطبيقات":

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

  2. أضِف دالة مثل هذه إلى رمز مشروع "برمجة التطبيقات":

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

إنشاء مساحة

يوضّح المثال التالي كيفية إنشاء مساحة في Chat.

  1. أضِف نطاق التفويض chat.spaces.create إلى ملف appsscript.json في مشروع "برمجة التطبيقات":

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

  2. أضِف دالة مثل هذه إلى رمز مشروع "برمجة التطبيقات":

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

عضويات القائمة

يوضّح المثال التالي كيفية إدراج جميع أعضاء مساحة Chat.

  1. أضِف نطاق التفويض chat.memberships.readonly إلى ملف appsscript.json في مشروع "برمجة التطبيقات":

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

  2. أضِف دالة مثل هذه إلى رمز مشروع "برمجة التطبيقات":

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

تحديد المشاكل وحلّها

إذا واجهت الخطأ Error 400: invalid_scope مع رسالة الخطأ Some requested scopes cannot be shown، يعني ذلك أنّك لم تحدّد أي نطاقات تفويض في ملف appsscript.json في مشروع Apps Script. في معظم الحالات، يحدّد Apps Script تلقائيًا النطاقات التي يحتاجها البرنامج النصي، ولكن عند استخدام خدمة Chat المتقدّمة، عليك إضافة نطاقات التفويض التي يستخدمها البرنامج النصي يدويًا إلى ملف البيان الخاص بمشروع Apps Script. راجِع مقالة ضبط النطاقات الواضحة.

لحلّ الخطأ، أضِف نطاقات الأذونات المناسبة إلى ملف appsscript.json في مشروع Apps Script كجزء من مصفوفة oauthScopes. على سبيل المثال، لاستدعاء طريقة spaces.messages.create، أضِف ما يلي:

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

الحدود والاعتبارات

لا تتوافق خدمة "المحادثة المتقدّمة" مع ما يلي:

لتنزيل مرفق رسالة أو استدعاء طريقة معاينة مطوّر البرامج، استخدِم UrlFetchApp بدلاً من ذلك.