允許 Google Workspace 機構中的特定使用者搜尋 Google Chat 聊天室

本文說明如何使用 Google Chat API，與 Google Workspace 機構中的特定使用者共用 Google Chat 聊天室，讓他們可以探索、加入及查看聊天室成員。

如要指定貴機構中可探索、加入及查看聊天室成員的使用者，請建立目標對象。目標對象是一群使用者 (例如特定部門或整個機構)，您可以與這群使用者共用 Google Chat 聊天室，進一步控管哪些人可以存取聊天室和相關資訊。您也可以透過目標對象管理及自訂聊天室成員，不必邀請個別使用者加入聊天室。詳情請參閱「關於目標對象」。

您只能讓目標對象探索具名聊天室。您無法與目標對象分享其他類型的聊天室，例如即時訊息或群組對話。

必要條件

取得目標對象 ID

如要取得目標對象的 ID，請按照下列步驟操作：

  1. 在 Google 管理控制台中，依序點選「選單」圖示 「目錄」>「目標對象」。

    前往「目標對象」

  2. 在「目標對象」表格中，按一下目標對象的「名稱」欄位。

  3. 在網頁網址中找出目標對象 ID。網址格式為 https://admin.google.com/ac/targetaudiences/TARGET_AUDIENCE_ID， 其中 TARGET_AUDIENCE_ID 是目標對象的英數字元 ID。

在下一節中，您將使用目標對象 ID 建立可自由加入的聊天室，或更新現有聊天室，讓目標對象可以搜尋到該聊天室。

指定目標對象和精細權限

如要建立具備特定存取權的空間，請使用 Space 資源的 create 或 setup 方法。如要更新現有聊天室的權限，請使用 update 方法。只有具名聊天室可與目標對象共用，因此聊天室類型 (以 spaceType 欄位表示) 必須為 SPACE。

如要指定哪些使用者可以探索、加入聊天室或查看成員，請在 Space 資源中加入 AccessSettings 物件。在物件中，使用 accessPermissionSettings 欄位指定一或多個下列權限：

  • 可供搜尋：使用 discoverSpaceSetting 定義可搜尋聊天室名稱和說明，並在 Google Chat 中瀏覽聊天室的使用者。您可以為探索指定多個目標對象。
  • 可加入：使用 joinSpaceSetting 定義哪些使用者可以加入聊天室，不必明確邀請，並預覽聊天室訊息。使用者必須能夠找到聊天室，才能加入。Google Chat 支援這項權限的單一目標對象。
  • 查看成員：使用 viewSpaceMembershipSetting 定義哪些使用者可以查看聊天室的成員清單。更新可查看聊天室成員資格的使用者時，必須在 updateMask 和要求內文中，一併指定 accessSettings.accessPermissionSettings.viewSpaceMembershipSetting 和 permissionSettings.viewSpaceMembership。在 viewSpaceMembershipSetting 中設定目標對象時，必須將 viewSpaceMembership 授予所有成員 (managersAllowed、assistantManagersAllowed 和 membersAllowed 設為 true)。

以下範例說明如何將聊天室設為可供兩組目標對象探索，但僅限其中一方加入，並確保所有成員和指定目標對象都能查看成員名單：

{
  "accessSettings": {
    "accessPermissionSettings": {
      "discoverSpaceSetting": {
        "principals": [
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } },
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_2" } }
        ]
      },
      "joinSpaceSetting": {
        "principals": [
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } }
        ]
      },
      "viewSpaceMembershipSetting": {
        "principals": [
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } },
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_2" } }
        ]
      }
    }
  },
  "permissionSettings": {
    "viewSpaceMembership": {
      "managersAllowed": true,
      "assistantManagersAllowed": true,
      "membersAllowed": true
    }
  }
}

將 TARGET_AUDIENCE_ID_1 和 TARGET_AUDIENCE_ID_2 替換為您在「取得目標對象 ID」中取得的目標對象 ID。如要為 Google Workspace 機構使用預設的 Chat 聊天室共用設定，請替換為 default。

如要回溯相容，請使用 audience 欄位

為確保回溯相容性，您仍可使用 audience 欄位指定可加入聊天室的單一目標對象，但建議改為指定目標對象和精細權限。

設定 audience 欄位等同於在 joinSpaceSetting 中指定目標對象：

  "accessSettings": {
    "audience": "audiences/TARGET_AUDIENCE_ID"
  }

將 TARGET_AUDIENCE_ID 替換為您在「取得目標對象 ID」中取得的目標對象 ID。如要為 Google Workspace 機構使用預設的 Chat 聊天室共用設定，請替換為 default。

瞭解 API 回應中的存取權設定

取得或列出聊天室時，回應中的 AccessSettings 物件會反映為聊天室設定的精細權限。

AccessSettings 中的下列欄位會指出空間的可搜尋性和加入權限：

  • accessState：衍生自探索權限 (discoverSpaceSetting)。如果授予一或多個目標對象探索權限，這個欄位會是 DISCOVERABLE。否則為 PRIVATE。
  • audience：專門對應至加入權限 (joinSpaceSetting)。如果單一目標對象獲得加入權限，這個欄位會包含該目標對象的資源名稱。

可自由加入的聊天室，但沒有加入目標對象

目標對象可以查看聊天室，但無法直接加入 (例如，使用者必須受到明確邀請才能加入)。

在此情況下，AccessSettings 物件具有下列值：

  • accessState：DISCOVERABLE
  • audience：省略或 null

如果看到 accessState 設為 DISCOVERABLE，但沒有 audience，表示目標對象可以在 discoverSpaceSetting 中找到聊天室，但只能透過邀請加入。如要查看哪些目標對象可以找到聊天室，請查看「accessPermissionSettings.discoverSpaceSetting」欄位。

如要進一步瞭解目標對象，請參閱下列指南：

如要瞭解如何使用 Chat API 建立或更新聊天室，請參閱下列指南：