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

באמצעות השירות 'צ'אט מתקדם' תוכלו להשתמש ב-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 קובע באופן אוטומטי אילו היקפים צריכים להיות לסקריפט, אבל כשמשתמשים בשירות המתקדם של Chat, צריך להוסיף באופן ידני את היקפי ההרשאות שהסקריפט משתמש בהם לקובץ המניפסט של פרויקט Apps Script. למידע נוסף, ראו הגדרת היקפים מפורשים.

כדי לפתור את השגיאה, צריך להוסיף את היקפי ההרשאות המתאימים לקובץ appsscript.json של פרויקט Apps Script כחלק מהמערך oauthScopes. לדוגמה, כדי לקרוא לשיטה spaces.messages.create, מוסיפים את הקוד הבא:

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

מגבלות ושיקולים

השירות 'צ'אט מתקדם' לא תומך בפריטים הבאים:

כדי להוריד קובץ מצורף של הודעה או להתקשר לשיטת תצוגה מקדימה למפתחים, יש להשתמש במקום זאת ב-UrlFetchApp.