驗證和授權機制分別用於驗證身分和資源存取權。本文將概述 Chat 應用程式和 Chat API 要求的驗證和授權作業運作方式。
流程總覽
下圖概略說明 Google Chat 的驗證和授權步驟：
設定 Google Cloud 專案、啟用 Chat API 並設定 Chat 應用程式：在開發期間，您需要建立 Google Cloud 專案。在 Google Cloud 專案中，您可以啟用 Chat API、設定 Chat 應用程式，以及設定驗證機制。詳情請參閱「在 Google Workspace 上開發」和「建構 Chat 應用程式」。
呼叫 Chat API：當應用程式呼叫 Chat API 時，會將驗證憑證傳送至 Chat API。如果應用程式使用服務帳戶進行驗證，憑證會隨應用程式程式碼一併傳送。如果您的應用程式需要使用尚未授予的使用者驗證資訊呼叫 Chat API，系統會提示使用者登入。
要求資源：應用程式要求存取您在設定驗證時指定的範圍。
詢問是否同意：如果應用程式是以使用者的身分進行驗證，Google 會顯示 OAuth 同意畫面，讓使用者決定是否授予應用程式要求資料的存取權。使用服務帳戶進行驗證不需要取得使用者同意。
傳送核准的資源要求：如果使用者同意授權範圍，應用程式會將憑證和使用者核准的範圍合併至要求中。要求會傳送至 Google 授權伺服器，以便取得存取權杖。
Google 傳回存取權憑證：存取權憑證包含已授予的範圍清單。如果傳回的範圍清單比要求的範圍更嚴格，應用程式會關閉任何受憑證限制的功能。
存取要求的資源：您的應用程式會使用 Google 提供的存取權杖，叫用 Chat API 並存取 Chat API 資源。
取得更新權杖 (選用)：如果應用程式必須在單一存取權杖的有效期限過後存取 Google Chat API，則可取得更新權杖。詳情請參閱「使用 OAuth 2.0 存取 Google API」的說明。
要求更多資源：如果應用程式需要更多存取權，就會要求使用者授予新的範圍，進而產生新的要求，以便取得存取權表示符 (步驟 3 至 6)。
即時通訊應用程式需要驗證的情況
聊天應用程式可以根據使用者互動或非同步傳送訊息。使用者也可以代表使用者完成工作，例如建立 Chat 聊天室，或取得 Chat 聊天室中的使用者清單。
除非 Chat 應用程式在處理回應時呼叫 Chat API 或其他 Google API，否則即時通訊應用程式不需要驗證即可回應使用者互動。
如要傳送非同步訊息或代使用戶執行工作，Chat 應用程式會向 Chat API 提出 RESTful 要求，而這項操作需要驗證和授權。
對使用者互動回應不需驗證
Google Chat 應用程式不需要以使用者或 Chat 應用程式的身分進行驗證，就能同步接收及回應互動事件。
使用者與 Chat 應用程式互動或叫用 Chat 應用程式時，Google Chat 應用程式會收到互動事件，包括：
- 使用者傳送訊息至 Chat 應用程式。
- 使用者 @提及 Chat 應用程式。
- 使用者叫用其中一個 Chat 應用程式的斜線指令。
下圖顯示 Chat 使用者和 Chat 應用程式之間的要求/回應序列：
- 使用者在 Google Chat 中傳送訊息給 Chat 應用程式。
- Google Chat 會將訊息轉寄至應用程式。
- 應用程式會收到、處理訊息，然後傳回 Google Chat 回覆。
- Google Chat 會為使用者或聊天室呈現回應。
每個 Chat 應用程式互動事件都會重複這個程序。
非同步郵件需要驗證
當 Chat 應用程式向 Chat API 發出需要驗證和授權的要求時，就會發生非同步訊息。
只要呼叫 Chat API，Chat 應用程式就能將訊息發布至 Google Chat，或代表使用者完成工作及存取資料。舉例來說，在偵測到伺服器中斷服務後，Chat 應用程式可以呼叫 Chat API 來執行以下操作：
- 建立專門用於調查及修正服務中斷問題的 Chat 聊天室。
- 將使用者加入 Chat 聊天室。
- 在 Chat 聊天室中張貼訊息，說明服務中斷的詳細資訊。
下圖顯示 Chat 應用程式和 Chat 聊天室之間的非同步訊息序列：
- Chat 應用程式會使用
spaces.messages.create方法呼叫 Chat API，並在 HTTP 要求中加入使用者憑證，藉此建立訊息。 - Google Chat 會使用服務帳戶或使用者憑證來驗證 Chat 應用程式。
- Google Chat 會將應用程式的訊息轉譯至指定的 Chat 聊天室。
Chat API 範圍
設定 OAuth 同意畫面並選擇範圍，即可定義要向使用者和應用程式審查人員顯示哪些資訊，並註冊應用程式，以便日後發布。
如要定義授予應用程式的存取權層級，您必須識別並宣告授權範圍。授權範圍是 OAuth 2.0 URI 字串，內含 Google Workspace 應用程式名稱、它存取的資料類型，以及存取層級。
非機密範圍
| 範圍代碼 | 說明 |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
讓 Chat 應用程式查看聊天內容並傳送訊息。 |
機密範圍
| 範圍代碼 | 說明 |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
在 Chat 中建立對話和聊天室，以及查看或編輯中繼資料 (包括記錄設定和存取設定)。 |
https://www.googleapis.com/auth/chat.spaces.create
|
在 Chat 中建立新對話。 |
https://www.googleapis.com/auth/chat.spaces.readonly
|
在 Chat 中查看即時通訊和聊天室。 |
https://www.googleapis.com/auth/chat.memberships
|
在 Chat 對話中查看、新增、更新及移除成員。 |
https://www.googleapis.com/auth/chat.memberships.app
|
在 Google Chat 對話中加入及移除應用程式本身。 |
https://www.googleapis.com/auth/chat.memberships.readonly
|
查看 Chat 對話中的成員。 |
https://www.googleapis.com/auth/chat.messages.create
|
在 Chat 中撰寫及傳送訊息。 |
https://www.googleapis.com/auth/chat.messages.reactions
|
在 Chat 中查看、新增和刪除訊息回應。 |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
在 Chat 中回應訊息。 |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
在 Chat 中查看訊息回應。 |
https://www.googleapis.com/auth/chat.users.readstate
|
查看及修改 Chat 對話的上次讀取時間。 |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
查看 Chat 對話的上次讀取時間。 |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
在 Chat 中查看管理員網域所擁有的即時通訊和聊天室。 |
https://www.googleapis.com/auth/chat.admin.spaces
|
在 Chat 中查看或編輯管理員的網域所擁有的即時通訊和聊天室。 |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
在 Chat 中查看管理員網域所擁有對話的成員和管理員。 |
https://www.googleapis.com/auth/chat.admin.memberships
|
查看、新增、更新及移除 Chat 中管理員網域所擁有對話的成員和管理員。 |
https://www.googleapis.com/auth/chat.app.spaces
|
在 Chat 中建立對話和聊天室，以及查看或更新中繼資料 (包括記錄設定和存取權設定)。必須取得管理員核准。 |
https://www.googleapis.com/auth/chat.app.spaces.create
|
在 Chat 中建立新的對話和聊天室。需要管理員核准。 |
https://www.googleapis.com/auth/chat.app.memberships
|
查看、新增、更新及移除 Chat 對話和聊天室的成員。 需要管理員核准。 |
https://www.googleapis.com/auth/chat.customemojis
|
在 Chat 中查看、建立及刪除自訂表情符號。 |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
在 Chat 中查看自訂表情符號。 |
https://www.googleapis.com/auth/chat.users.spacesettings
|
查看及更新 Chat 使用者聊天室設定。
請參閱空間使用者設定 API：getSpaceNotificationSetting、updateSpaceNotificationSetting |
受限制範圍
| 範圍代碼 | 說明 |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
刪除對話和聊天室，並移除對 Chat 相關檔案的存取權。 |
https://www.googleapis.com/auth/chat.import
|
將聊天室、訊息和成員資格匯入 Chat。詳情請參閱「授權 Chat 應用程式匯入資料」 |
https://www.googleapis.com/auth/chat.messages
|
查看、撰寫、傳送、更新及刪除訊息，以及新增、查看和刪除訊息的回應。 |
https://www.googleapis.com/auth/chat.messages.readonly
|
在 Chat 中查看訊息和回應。 |
https://www.googleapis.com/auth/chat.admin.delete
|
刪除管理員網域擁有的對話和聊天室，並移除對 Chat 相關檔案的存取權。 |
https://www.googleapis.com/auth/chat.app.delete
|
刪除對話和聊天室，以及移除 Chat 中相關檔案的存取權。須經過管理員核准。 |
上表中的範圍會根據以下定義指出其敏感度：
非敏感資料：這些範圍提供最小範圍的授權存取權，且只需要基本應用程式驗證。如要瞭解這項規定的相關資訊，請參閱「驗證前準備步驟」。
機密：這些範圍可讓應用程式在獲得使用者授權後，存取特定使用者的 Google 資料。您必須完成額外的應用程式驗證程序。如要瞭解這項規定，請參閱「要求敏感範圍的應用程式步驟」。
受限制：這些範圍可提供廣泛的 Google 使用者資料存取權，且需要您完成受限制範圍驗證程序。如要瞭解這項規定，請參閱「Google API 服務：使用者資料政策」和「特定 API 範圍附加規定」。另請參閱要求受限權限範圍的應用程式步驟。
如果應用程式需要存取其他 Google API，您也可以新增這些範圍。如要進一步瞭解 Google API 範圍，請參閱「使用 OAuth 2.0 存取 Google API」。
如要進一步瞭解 Google Workspace API 的範圍，請參閱「設定 OAuth 同意畫面並選擇範圍」。
必要驗證類型
Chat 應用程式可以透過 Chat API 驗證及授權，方法如下：
- 使用者驗證
- 使用者驗證功能可讓 Chat 應用程式存取使用者資料，並代表使用者完成動作。OAuth 範圍會指定授權資料和動作。除非 Chat 應用程式是由管理員安裝或已獲得全網域委派，否則 Chat 應用程式第一次代表使用者執行動作時，使用者必須透過 OAuth 同意畫面授權 Chat 應用程式。
- 應用程式驗證
應用程式驗證可讓 Chat 應用程式使用服務帳戶憑證和存取資料，並像本身一樣完成動作。由於 Chat 應用程式會使用自己的憑證存取及使用資源，因此使用者不必核准 Chat 應用程式的 API 呼叫，您也無法在 OAuth 同意聲明畫面中新增支援應用程式授權的 OAuth 授權範圍。
兩種 OAuth 授權範圍支援應用程式驗證：
https://www.googleapis.com/auth/chat.bot：Chat 應用程式可以呼叫支援此授權範圍的 Google Chat API 方法，藉此建立、更新、取得、列出或刪除其可存取的資源，例如使用者將 Chat 應用程式加入聊天室時的訊息。Chat 應用程式可以自行授予這項授權範圍，無須經過管理員或使用者授權。https://www.googleapis.com/auth/chat.app.*(開發人員預覽版)：使用這些權限範圍需要一次性管理員核准。如要取得管理員核准，您必須建立與 Google Workspace Marketplace 相容的 OAuth 用戶端，並在 Google Workspace Marketplace SDK 中設定應用程式，備妥接收管理員核准的 Chat 應用程式服務帳戶。這些範圍可讓 Chat 應用程式呼叫特定的 Google Chat API 方法。舉例來說，chat.app.spaces.create可讓應用程式建立 Chat 聊天室。
如果方法同時支援使用者或應用程式驗證，Chat API 會根據您使用的驗證類型傳回不同的結果：
- 如果採用應用程式驗證功能，這些方法只會傳回 Chat 應用程式可存取的資源。
- 如果採用使用者驗證機制，這些方法只會傳回 user 可存取的資源。
舉例來說，呼叫具有應用程式授權的 spaces.list() 方法，會傳回 Chat 應用程式所屬的聊天室清單。透過使用者授權呼叫 spaces.list() 會傳回使用者所屬的聊天室清單。實際上，您可能會在呼叫 Chat API 時使用這兩種驗證方式，具體取決於 Chat 應用程式的設計和功能。
針對非同步 Chat API 呼叫
下表列出 Chat API 方法及其支援的授權範圍：
| 方法 | 支援使用者驗證 | 支援應用程式驗證 | 支援的授權範圍 | |
|---|---|---|---|---|
| 聊天室 | ||||
| 建立聊天室 |
透過使用者驗證機制：
|
|||
| 設定聊天室 | — |
使用使用者驗證：
|
||
| 取得聊天室 |
使用使用者驗證：
|
|||
| 列出聊天室 |
使用使用者驗證：
|
|||
| 搜尋空間 | — |
使用管理員權限進行使用者驗證：
|
||
| 更新聊天室 |
使用使用者驗證：
|
|||
| 刪除聊天室 |
使用使用者驗證：
|
|||
| 完成聊天室的匯入程序 | — |
使用使用者驗證：
|
||
| 尋找即時訊息 |
使用使用者驗證：
|
|||
| 成員 | ||||
| 建立成員 |
使用使用者驗證：
|
|||
| 取得會員 |
使用使用者驗證：
|
|||
| 名單成員 |
使用使用者驗證：
|
|||
| 刪除成員 |
使用使用者驗證：
|
|||
| 更新成員 |
使用使用者驗證：
|
|||
| 訊息 | ||||
| 建立訊息 |
使用使用者驗證：
|
|||
| 接收訊息 |
使用使用者驗證：
|
|||
| 列出訊息 | — |
使用使用者驗證：
|
||
| 更新訊息 |
使用使用者驗證：
|
|||
| 刪除訊息 |
透過使用者驗證機制：
|
|||
| 反應 | ||||
| 建立回應 | — |
透過使用者驗證機制：
|
||
| 列出回應 | — |
使用使用者驗證：
|
||
| 刪除回應 | — |
使用使用者驗證：
|
||
| 自訂表情符號 | ||||
| 建立自訂表情符號 | — |
透過使用者驗證機制：
|
||
| 刪除自訂表情符號 | — |
使用使用者驗證：
|
||
| 取得自訂表情符號 | — |
使用使用者驗證：
|
||
| 列出自訂表情符號 | — |
使用使用者驗證：
|
||
| 媒體和附件 | ||||
| 上傳媒體檔案做為附件 | — |
使用使用者驗證：
|
||
| 下載媒體 |
使用使用者驗證：
|
|||
| 取得訊息附件 | — |
使用應用程式驗證：
|
||
| 使用者已讀狀態 | ||||
| 取得使用者的空間讀取狀態 | — |
使用使用者驗證：
|
||
| 更新使用者的聊天室讀取狀態 | — |
使用使用者驗證：
|
||
| 取得使用者的會話讀取狀態 | — |
使用使用者驗證：
|
||
| 使用者聊天室設定 | ||||
| 取得使用者的聊天室通知設定 | — |
使用使用者驗證：
|
||
| 更新使用者的儲存空間通知設定 | — |
使用使用者驗證：
|
||
| 空間事件 | ||||
| 取得聊天室事件 | — |
使用使用者驗證時，您必須根據
事件類型使用範圍：
|
||
| 列出空間事件 | — |
使用使用者驗證時，您必須為要求中包含的每個事件類型使用範圍：
|
||
適用於 Chat 應用程式互動事件
下表列出使用者與 Chat 擴充應用程式的常見互動方式，以及是否需要或支援驗證：
| 情境 | 不需要驗證 | 支援使用者驗證 | 支援應用程式驗證 | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 接收來自以下內容的訊息： |
|
|||||||||||||||
| 回覆訊息： |
|
|||||||||||||||
| 傳送新訊息： |
|
|||||||||||||||
相關主題
- 如要瞭解 Google Workspace 中的驗證和授權，請參閱驗證與授權簡介。
- 如要瞭解 Google Cloud 中的驗證和授權總覽，請參閱「驗證總覽」。
- 如要進一步瞭解服務帳戶，請參閱「服務帳戶」。
- 如要進一步瞭解 Google API 如何使用 OAuth 2.0，請參閱「使用 OAuth 2.0 存取 Google API」。
- 使用使用者憑證或服務帳戶設定驗證和授權。