驗證和授權是分別用來驗證身分和資源存取權的機制。本文件概述了 Chat 應用程式和 Chat API 要求的驗證和授權運作方式。
流程總覽
下圖顯示 Google Chat 驗證和授權的詳細步驟：
設定 Google Cloud 專案、啟用 Chat API 並設定 Chat 應用程式：在開發期間，您會建立 Google Cloud 專案。在 Google Cloud 專案中，啟用 Chat API、設定 Chat 應用程式及設定驗證機制。詳情請參閱「在 Google Workspace 上開發」和「建構即時通訊應用程式」。
Call 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 發出符合 REST 樣式的要求，此時需要驗證及授權。
針對使用者互動的回應不需要驗證
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 應用程式查看即時通訊及傳送訊息。授予 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.delete
|
刪除 Chat 和聊天室，以及移除 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 中查看訊息和回應。 |
上表中的範圍根據下列定義，指出這些範圍的機密程度：
非機密：這些範圍提供最低的授權存取權，且只需要基本應用程式驗證。如要進一步瞭解這項規定，請參閱「為驗證做好準備的步驟」。
敏感：這些範圍可讓您在獲得使用者的授權後，讓應用程式存取特定使用者的 Google 資料。而必須完成額外的應用程式驗證。如要進一步瞭解這項規定，請參閱「要求敏感範圍的應用程式適用步驟」。
受限制：這些範圍可廣泛存取 Google 使用者資料，需要您完成受限制範圍的驗證程序。如要瞭解這項規定，請參閱 Google API 服務：使用者資料政策和特定 API 範圍的其他規定。另請參閱「應用程式要求受限制範圍的步驟」。
如果您的應用程式需要存取任何其他 Google API，也可以新增這些範圍。如要進一步瞭解 Google API 範圍，請參閱使用 OAuth 2.0 存取 Google API。
如要進一步瞭解 Google Workspace API 的範圍，請參閱「設定 OAuth 同意畫面並選擇範圍」。
必要驗證類型
即時通訊應用程式可透過 Chat API 驗證及授權的方式有兩種：使用者憑證或服務帳戶。
有了使用者憑證授權，Chat 應用程式就能代表使用者存取使用者資料並完成動作。OAuth 範圍會指定已授權的資料和動作。
透過應用程式授權，Chat 應用程式會使用服務帳戶憑證，以應用程式的形式存取 API。應用程式授權一律會使用 chat.bot 授權範圍。
決定要針對特定 API 要求使用哪一種憑證時，請注意部分 API 方法僅支援特定類型的憑證。如果 API 方法同時支援這兩種憑證，則呼叫中使用的憑證類型會影響傳回的結果：
- 有了應用程式授權，這些方法只會傳回「應用程式」可存取的資源。
- 在使用者授權的情況下，這些方法只會傳回使用者在 Chat UI 中可以存取的資源。
舉例來說，透過應用程式授權呼叫 ListSpaces 方法，會傳回應用程式所屬的聊天室清單。透過使用者授權呼叫 ListSpaces 會傳回使用者所屬的聊天室清單。實際上，應用程式可能會在呼叫 Chat API 時使用這兩種授權，視所需的功能而定。
非同步 Chat API 呼叫
下表列出 Chat API 方法及其支援的授權範圍：
| 方法 | 支援使用者驗證 | 支援應用程式驗證 | 支援的授權範圍 | |
|---|---|---|---|---|
| 聊天室 | ||||
| 建立聊天室 | — |
透過使用者驗證功能：
|
||
| 設定聊天室 | — |
透過使用者驗證功能：
|
||
| 取得聊天室 |
透過使用者驗證功能：
|
|||
| 列出聊天室 |
透過使用者驗證功能：
|
|||
| 更新聊天室 | — |
透過使用者驗證功能：
|
||
| 刪除聊天室 | — |
透過使用者驗證功能：
|
||
| 完成聊天室的匯入程序 | — |
透過使用者驗證功能：
|
||
| 尋找即時訊息 |
透過使用者驗證功能：
|
|||
| 成員 | ||||
| 建立成員 | — |
透過使用者驗證功能：
|
||
| 加入會員 |
透過使用者驗證功能：
|
|||
| 名單成員 |
透過使用者驗證功能：
|
|||
| 刪除成員 | — |
透過使用者驗證功能：
|
||
| 訊息 | ||||
| 建立訊息 |
透過使用者驗證功能：
|
|||
| 接收訊息 |
透過使用者驗證功能：
|
|||
| 列出訊息 | — |
透過使用者驗證功能：
|
||
| 更新訊息 |
透過使用者驗證功能：
|
|||
| 刪除訊息 |
透過使用者驗證功能：
|
|||
| 反應 | ||||
| 建立回應 | — |
透過使用者驗證功能：
|
||
| 清單回應 | — |
透過使用者驗證功能：
|
||
| 刪除回應 | — |
透過使用者驗證功能：
|
||
| 媒體與附件 | ||||
| 以檔案附件上傳媒體 | — |
透過使用者驗證功能：
|
||
| 下載媒體 |
透過使用者驗證功能：
|
|||
| 取得郵件附件 | — |
使用應用程式驗證時：
|
||
| 使用者讀取狀態 | ||||
| 取得使用者的空間讀取狀態 | — |
透過使用者驗證功能：
|
||
| 更新使用者的聊天室讀取狀態 | — |
透過使用者驗證功能：
|
||
| 取得使用者的執行緒讀取狀態 | — |
透過使用者驗證功能：
|
||
| 聊天室活動 | ||||
| 取得聊天室活動 | — |
透過使用者驗證功能：
|
||
| 列出聊天室事件 | — |
透過使用者驗證功能：
|
||
適用於 Chat 應用程式互動事件
下表列出使用者與 Chat 應用程式互動的常見方式，以及是否需要進行驗證：
| 情境 | 不需要驗證 | 支援使用者驗證 | 支援應用程式驗證 | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 接收訊息來源： |
|
|||||||||||||||
| 回覆訊息： |
|
|||||||||||||||
| 傳送新訊息： |
|
|||||||||||||||
相關主題
- 如需 Google Workspace 中的驗證和授權總覽，請參閱瞭解驗證和授權一文。
- 如需 Google Cloud 中驗證和授權的總覽，請參閱「驗證總覽」一文。
- 如要進一步瞭解服務帳戶，請參閱服務帳戶一文。
- 如要進一步瞭解 Google API 如何使用 OAuth 2.0，請參閱使用 OAuth 2.0 存取 Google API。
- 使用使用者憑證或服務帳戶設定驗證和授權。