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

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

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

مَراجع

لمزيد من المعلومات حول هذه الخدمة، يمكنك الاطّلاع على المستندات المرجعية الخاصة بـ Chat API. مثل جميع الخدمات المتقدّمة في لغة "برمجة تطبيقات Google"، تستخدم خدمة Chat العناصر والطرق والمعلَمات نفسها المستخدَمة في واجهة برمجة التطبيقات العامة.

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

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

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

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

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

    "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 لمشروع "برمجة تطبيقات Google":

    "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 لمشروع "برمجة تطبيقات Google":

    "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 لمشروع "برمجة تطبيقات Google":

    "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 الخاص بمشروع "برمجة تطبيقات". في معظم الحالات، تحدِّد لغة "برمجة تطبيقات Google" تلقائيًا النطاقات التي يحتاجها النص البرمجي، ولكن عند استخدام خدمة Chat المتقدّمة، عليك إضافة نطاقات التفويض التي يستخدمها النص البرمجي يدويًا إلى ملف بيان مشروع "برمجة تطبيقات Google". راجِع إعداد نطاقات صريحة.

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

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

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

لا توفِّر خدمة المحادثة المتقدّمة ما يلي:

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