驗證及授權 Chat 專用應用程式和 Google Chat API 要求

驗證和授權是分別用於驗證身分和資源存取權的機制。本文件概述 Chat 應用程式和 Chat API 要求的驗證和授權如何運作。

流程總覽

下圖說明 Google Chat 的高階驗證和授權步驟:

Google Chat 驗證與授權的概略步驟
圖 1. Google Chat 驗證與授權的高階步驟。

  1. 設定 Google Cloud 專案、啟用 Chat API,並設定 Chat 應用程式:在開發期間,您可以建立 Google Cloud 專案。在 Google Cloud 專案中,您可以啟用 Chat API、設定 Chat 應用程式,並設定驗證方法。詳情請參閱「在 Google Workspace 中開發」和「建構即時通訊應用程式」。

  2. 呼叫 Chat API:應用程式呼叫 Chat API 時,會將驗證憑證傳送至 Chat API。如果應用程式使用服務帳戶進行驗證,憑證就會做為應用程式程式碼的一部分傳送。如果您的應用程式需要利用尚未獲授予的使用者驗證來呼叫 Chat API,系統會提示使用者登入。

  3. 要求資源:應用程式會根據您在設定驗證時指定的範圍要求存取權。

  4. 要求同意:如果您的應用程式是以使用者的身分進行驗證,Google 會顯示 OAuth 同意畫面,讓使用者可以決定是否要授予應用程式存取要求資料的權限。使用服務帳戶進行驗證不需要使用者同意。

  5. 傳送核准的資源要求:如果使用者同意授權範圍,應用程式會將憑證和使用者核准的範圍納入要求。該要求會傳送至 Google 授權伺服器,以取得存取權杖。

  6. Google 傳回存取權杖:存取權杖包含已授予範圍的清單。如果傳回的範圍清單比要求的範圍嚴格,則應用程式會關閉所有受權杖限制的功能。

  7. 存取要求的資源:應用程式會使用 Google 的存取權杖來叫用 Chat API 及存取 Chat API 資源。

  8. 取得更新權杖 (選擇性):如果應用程式必須在單一存取權杖的生命週期過後,才能存取 Google Chat API,就能取得更新權杖。詳情請參閱使用 OAuth 2.0 存取 Google API

  9. 要求更多資源:如果應用程式需要更多存取權,會要求使用者授予新的範圍,進而產生新的要求取得存取權杖 (步驟 3-6)。

即時通訊應用程式需要驗證時

Chat 應用程式可以傳送回應使用者互動的訊息,或以非同步方式傳送訊息。也可以代表使用者完成工作,例如建立 Chat 聊天室或取得 Chat 聊天室中的使用者清單。

除非 Chat 應用程式在處理回應時呼叫 Chat API 或其他 Google API,否則不必進行驗證即可回應使用者互動。

如要傳送非同步訊息或代表使用者執行工作,Chat 應用程式會向 Chat API 發出符合 REST 樣式的要求,以便進行驗證和授權。

回應使用者互動時不需要驗證

Google Chat 應用程式不需要在使用者或 Chat 應用程式中進行驗證,即可同步接收及回應互動事件

使用者每次與 Chat 應用程式互動或叫用 Chat 應用程式時,Google Chat 應用程式都會接收互動事件,包括下列項目:

  • 使用者傳送訊息給 Chat 應用程式。
  • 使用者使用 @號提及 Chat 應用程式。
  • 使用者叫用 Chat 應用程式的其中一個斜線指令

下圖顯示 Chat 使用者和 Chat 應用程式之間的要求/回應順序:

Chat 應用程式互動事件不需要授權
圖 2.Chat 應用程式互動事件不需要驗證。

  1. 使用者傳送訊息給 Google Chat 中的 Chat 應用程式。
  2. Google Chat 會將訊息轉寄到應用程式。
  3. 應用程式接收及處理訊息,並傳回 Google Chat 回應。
  4. Google Chat 會為使用者或聊天室顯示回應。

每個 Chat 應用程式互動事件都會重複此序列。

非同步訊息需要驗證

當 Chat 應用程式向 Chat API 發出要求 (需要驗證及授權) 時,就會發生非同步訊息。

藉由呼叫 Chat API,Chat 應用程式即可將訊息張貼到 Google Chat,或是代表使用者完成工作並存取資料。舉例來說,在偵測到伺服器服務中斷情形後,Chat 應用程式可以呼叫 Chat API 來執行下列操作:

  • 建立一個專門調查及修正服務中斷問題的 Chat 聊天室。
  • 將使用者加入 Chat 聊天室。
  • 請在 Chat 聊天室中張貼訊息,提供有關服務中斷的詳細資料。

下圖顯示 Chat 應用程式與 Chat 聊天室之間的非同步訊息序列:

非同步訊息需要驗證
圖 3. 非同步訊息需要驗證。

  1. Chat 應用程式使用 spaces.messages.create 方法呼叫 Chat API 來建立訊息,並在 HTTP 要求中加入使用者憑證。
  2. Google Chat 會使用服務帳戶或使用者憑證來驗證 Chat 應用程式。
  3. 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.delete 刪除 Chat 中的對話和聊天室,以及移除 Chat 中相關檔案的存取權。
https://www.googleapis.com/auth/chat.messages 查看、撰寫、傳送、更新及刪除訊息,以及新增、查看及刪除訊息的回應。
https://www.googleapis.com/auth/chat.messages.readonly 在 Chat 中查看訊息和回應。

上表中的範圍是根據下列定義表示其機密性:

如果您的應用程式需要存取任何其他 Google API,您也可以新增這些範圍。如要進一步瞭解 Google API 範圍,請參閱「使用 OAuth 2.0 存取 Google API」。

如要進一步瞭解 Google Workspace API 的範圍,請參閱「設定 OAuth 同意畫面和選擇範圍」。

必要驗證的類型

Chat 應用程式透過 Chat API 進行驗證和授權的方法有兩種:使用者憑證或服務帳戶。

透過使用者憑證授權,Chat 應用程式就能存取使用者資料,並代表使用者完成動作。OAuth 範圍會指定已授權的資料和動作。但這些 Chat 專用應用程式無法公開發布。詳情請參閱「發布 Google Chat 應用程式」。

透過應用程式授權,即時通訊應用程式會使用服務帳戶憑證,以應用程式的形式存取 API。應用程式授權一律會使用 chat.bot 授權範圍。

如果您是網域管理員,可以授予全網域授權委派權限,授權應用程式服務帳戶存取您使用者的資料,不必要求每位使用者都提供同意。設定全網域委派後,您可以使用服務帳戶發出 API 呼叫來模擬使用者帳戶。雖然服務帳戶會用於驗證,但全網域委派會模擬使用者,因此會將使用者視為使用者驗證。任何需要使用者驗證的功能都可以使用全網域委派。

決定要針對特定 API 要求使用的憑證類型時,請注意,部分 API 方法僅支援特定類型的憑證。如果 API 方法支援這兩種憑證,則呼叫中使用的憑證類型會影響傳回的結果:

  • 透過應用程式授權,這些方法只會傳回應用程式可存取的資源。
  • 透過使用者授權,方法只會傳回使用者能夠在 Chat UI 中存取的資源。

舉例來說,使用應用程式授權呼叫 ListSpaces 方法會傳回應用程式所屬的聊天室清單。透過使用者授權呼叫 ListSpaces 會傳回使用者所屬的聊天室清單。實務上,應用程式在呼叫 Chat API 時可能會同時使用這兩種授權 (視所需功能而定)。

非同步 Chat API 呼叫

下表列出 Chat API 方法及其支援的授權範圍:

方法 支援使用者驗證 支援應用程式驗證 支援的授權範圍
聊天室  
建立聊天室
  • chat.spaces.create
  • chat.spaces
設定聊天室
  • chat.spaces.create
  • chat.spaces
取得聊天室 使用「使用者驗證」時:
  • chat.spaces.readonly
  • chat.spaces
若使用應用程式驗證
  • chat.bot
列出聊天室 使用「使用者驗證」時:
  • chat.spaces.readonly
  • chat.spaces
若使用應用程式驗證
  • chat.bot
更新聊天室
  • chat.spaces
刪除聊天室
  • chat.delete
尋找即時訊息 使用「使用者驗證」時:
  • chat.spaces.readonly
  • chat.spaces
若使用應用程式驗證
  • chat.bot
成員  
建立成員
  • chat.memberships
  • chat.memberships.app
加入會員 使用「使用者驗證」時:
  • chat.memberships.readonly
  • chat.memberships
若使用應用程式驗證
  • chat.bot
名單成員 使用「使用者驗證」時:
  • chat.memberships.readonly
  • chat.memberships
若使用應用程式驗證
  • chat.bot
刪除成員
  • chat.memberships
  • chat.memberships.app
訊息  
建立訊息 使用「使用者驗證」時:
  • chat.messages.create
  • chat.messages
若使用應用程式驗證
  • chat.bot
取得訊息 使用「使用者驗證」時:
  • chat.messages.readonly
  • chat.messages
若使用應用程式驗證
  • chat.bot
清單訊息
  • chat.messages.readonly
  • chat.messages
更新訊息 使用「使用者驗證」時:
  • chat.messages
若使用應用程式驗證
  • chat.bot
刪除訊息 使用「使用者驗證」時:
  • chat.messages
若使用應用程式驗證
  • chat.bot
反應  
建立回應
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
清單回應
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
刪除回應
  • chat.messages.reactions
  • chat.messages
媒體與附件  
以檔案附件的形式上傳媒體
  • chat.messages.create
  • chat.messages
下載媒體 使用「使用者驗證」時:
  • chat.messages.readonly
  • chat.messages
若使用應用程式驗證
  • chat.bot
取得郵件附件
  • chat.bot

針對 Chat 應用程式互動事件

下表列出使用者與 Chat 應用程式互動的常見方式,以及他們是否需要驗證:

情境 不需驗證 支援使用者驗證 支援應用程式驗證
接收來自:
Chat 應用程式互動事件
Apps Script 回呼
Google Cloud Pub/Sub
回覆訊息:
使用 Chat 應用程式互動事件進行同步
使用 Apps Script 回呼傳回值同步,
傳送新訊息:
使用連入 Webhook