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

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

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

مراجع

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

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

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

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

يوضّح المثال التالي كيفية نشر رسالة في مساحة 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 بدلاً من ذلك.