שירות צ'אט מתקדם

שירות Advanced Chat מאפשר לכם להשתמש ב-Google Chat API ב-Apps Script. ה-API הזה מאפשר לסקריפטים למצוא, ליצור ולשנות מרחבים ב-Chat, לצרף אנשים למרחבים או להסיר אותם מהם, ולקרוא או לפרסם הודעות עם טקסט, כרטיסים, קבצים מצורפים ותגובות.

דרישות מוקדמות

חומרי עזר

מידע נוסף על השירות הזה זמין במאמרי העזרה של Chat API. בדומה לכל השירותים המתקדמים ב-Apps Script, שירות Chat משתמש באותם אובייקטים, שיטות ופרמטרים כמו ה-API הציבורי.

קוד לדוגמה

בדוגמאות האלה מוצגות דרכים לביצוע פעולות נפוצות ב-Google Chat API באמצעות השירות המתקדם.

פרסום הודעה עם פרטי כניסה של משתמש

בדוגמה הבאה אפשר לראות איך מפרסמים הודעה במרחב ב-Chat בשם המשתמש.

  1. מוסיפים את היקף ההרשאות chat.messages.create לקובץ appsscript.json של פרויקט Apps Script:

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

  2. מוסיפים פונקציה כמו זו לקוד של פרויקט Apps Script:

    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 של פרויקט Apps Script:

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

  2. מוסיפים פונקציה כמו זו לקוד של פרויקט Apps Script:

    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 של פרויקט Apps Script:

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

  2. מוסיפים פונקציה כמו זו לקוד של פרויקט Apps Script:

    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 של פרויקט Apps Script:

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

  2. מוסיפים פונקציה כמו זו לקוד של פרויקט Apps Script:

    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.