進階即時通訊服務

Advanced Chat 服務可讓您在 Apps Script 中使用 Google Chat API。這個 API 可讓指令碼尋找、建立及修改 Chat 聊天室、新增或移除聊天室成員，以及讀取或發布含文字、資訊卡、附件和回應的訊息。

必要條件

參考資料

如要進一步瞭解這項服務，請參閱 Chat API 參考說明文件。與 Apps Script 中的所有進階服務一樣，Chat 服務會使用與公用 API 相同的物件、方法和參數。

程式碼範例

這些範例會說明如何使用進階服務執行常見的 Google Chat API 動作。

使用使用者憑證發布訊息

以下範例說明如何代表使用者在 Chat 空間中發布訊息。

  1. 將 chat.messages.create 授權範圍新增至 Apps Script 專案的 appsscript.json 檔案：

    "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 授權範圍新增至 Apps Script 專案的 appsscript.json 檔案：

    "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 授權範圍新增至 Apps Script 專案的 appsscript.json 檔案：

    "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 授權範圍新增至 Apps Script 專案的 appsscript.json 檔案：

    "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，表示您尚未在 Apps Script 專案的 appsscript.json 檔案中指定任何授權範圍。在大多數情況下，Apps Script 會自動判斷指令碼需要哪些權限範圍，但如果您使用 Chat 進階服務，則必須手動將指令碼使用的授權範圍加進 Apps Script 專案的資訊清單檔案。請參閱「設定明確的範圍」。

如要解決這個錯誤，請將適當的授權範圍加入 Apps Script 專案的 appsscript.json 檔案，做為 oauthScopes 陣列的一部分。舉例來說，如要呼叫 spaces.messages.create 方法，請新增下列程式碼：

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

限制和注意事項

Chat 進階服務不支援以下功能：

如要下載訊息附件或呼叫開發人員預覽版方法，請改用 UrlFetchApp。