辨識及指定 Google Chat 使用者

本頁說明 Google Chat 應用程式和開發人員如何識別及指定 Chat 使用者。

如要執行下列任何操作，Chat 擴充應用程式或開發人員必須指定使用者：

Chat 如何識別使用者

Google Chat API 會為使用 Chat 的每位使用者和應用程式產生User資源。User 資源包含下列欄位：

  • name：資源名稱，格式為 users/{user}，其中 {user} 代表穩定且不重複的 ID。您可以將 users/app 設為 Chat 應用程式的別名。
  • displayName：僅限輸出。使用者的顯示名稱。
  • avatarUrl：僅限輸出。使用者的顯示圖片網址。
  • email：僅限輸出。使用者的電子郵件地址。
  • domainId：使用者 Google Workspace 網域的專屬 ID。
  • type：使用者類型。指出使用者是 Chat 應用程式 (BOT) 還是真人 (HUMAN)。
  • isAnonymous：僅限輸出。如果為 true，則表示使用者已遭刪除或無法查看個人資料。

使用者個人資料詳細資料和瀏覽權限規則

使用使用者驗證呼叫 Messages 和 Memberships API 時，Google Chat API 會在 User 資源中填入個人資料詳細資訊。API 會為內部使用者 (Google Workspace 機構中的使用者) 和外部使用者 (外部機構或個人 Google 帳戶中的使用者) 填入 displayName、email 和 avatarUrl。

API 填入使用者設定檔的範例包括下列位置：

隱私權和顯示規則

為保護使用者隱私，Google Chat API 會套用特定顯示規則，判斷是否要填入使用者個人資料詳細資訊：

  • 已填寫的個人資料：如果使用者已接受空間邀請 (是空間成員)，或與呼叫使用者有先前的親和性 (例如直接訊息互動記錄)，API 就會填寫個人資料詳細資料 (displayName、email 和 avatarUrl 存在，且 isAnonymous 為 false)。
  • 匿名設定檔：如果使用者在空間中遭到提及，但並非成員，且與呼叫使用者沒有先前的親和力，系統會維持匿名設定檔。如果是匿名使用者，isAnonymous 會是 true，且會省略 displayName、email 和 avatarUrl 等詳細資料。不過，如果是透過應用程式驗證發出的 API 要求，displayName 欄位一律會填入資料。

以下 JSON 範例顯示 User 資源，其中包含 API 回應或互動事件中傳回的已填入個人資料詳細資料：

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

以下 JSON 範例顯示匿名 User 資源，其中使用者設定檔詳細資料不會顯示給呼叫端：

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

在 Google Chat API 的呼叫中指定使用者

如要指定使用者，請為 {user} 值使用下列值：

  • 如果使用者屬於 Google Workspace 機構，請採取下列其中一種做法：

    • Chat API 中的 name User 資源，例如 users/123456789。
    • {person_id}People API 中Person資源的名稱，其中 resourceName 為 people/{person_id}，例如 Chat API 中的 users/123456789 代表與 People API 中的 people/123456789 相同的人。
    • Directory API 中 User 資源的 id (例如 Chat API 中的 users/123456789) 代表與 Directory API 中 users/123456789 相同的人。
    • 如果是透過使用者驗證發出的 API 要求，則為使用者的電子郵件地址 (別名)，例如 users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com。

  • 如果是外部 Google Workspace 機構的使用者，或是使用 Google 帳戶的使用者，請採取下列任一做法：

    • 電子郵件別名，例如 users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com 或 users/EMAIL_USERNAME@gmail.com。
    • 從先前的 API 呼叫或互動事件取得的 User 資源標準 name (例如 users/12345678901234567890)。

從 API 回應或互動事件中識別使用者

您可以透過幾種方式，找出 API 呼叫傳回的使用者或傳入事件：

由於 Google Chat API 會在使用使用者驗證時，填入內部和外部使用者的設定檔，因此開發人員不需要呼叫 Directory API，即可解析成員和訊息寄件者的名稱或電子郵件地址。