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

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

「驗證」和「授權」是分別用於驗證身分及資源存取權的機制。本文件將概述即時通訊和 Chat API 要求的運作方式。

流程總覽

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

Google Chat 驗證與授權的概要步驟
圖 1. Google Chat 驗證和授權的概要步驟

  1. 設定 Google Cloud 專案、啟用 Chat API,以及設定 Chat 應用程式:開發期間,您會建立 Google Cloud 專案。請在 Google Cloud 專案中啟用 Chat API、設定 Chat 應用程式,並設定驗證方法。

  2. 呼叫 Chat API:當應用程式呼叫 Chat REST API 時 (通常是在 Google Chat 中以發送訊息、點選卡片上的按鈕,或發出斜線指令) 來叫用應用程式時,系統會將驗證憑證傳送至 Chat API。如果您的應用程式使用服務帳戶進行驗證,憑證就在應用程式程式碼中傳送。如果您的應用程式將以使用者身分進行驗證,使用者可能會收到登入提示。

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

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

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

  6. Google 傳回存取權杖:存取權杖內含已授予範圍的清單。如果傳回的範圍清單超過要求範圍的限制,您的應用程式會關閉受權杖限制的功能。

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

  8. 取得更新憑證 (選用):如果應用程式需要在單一存取權杖的生命週期內存取 Google Chat API,則可取得更新憑證。

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

Chat 應用程式需要驗證時

即時通訊應用程式可透過同步或非同步方式傳送 Google Chat 訊息。也可以代替使用者完成建立 Chat 聊天室等工作。

同步訊息不需要驗證,除非 Chat 應用程式在處理回應時呼叫 Chat REST API 或其他 Google API。

如要傳送非同步訊息或代表使用者處理工作,Chat 應用程式向 Chat REST API 發出符合 REST 樣式的要求,藉此要求驗證和授權。

同步訊息不需要驗證

同步訊息是對 Chat 事件的回覆。在即時通訊應用程式設定頁面完成設定並發布後,Google Chat 應用程式就能接收及回應活動,而不需進行驗證或授權。

同步 Chat 事件的範例包括:

  • 使用者在 Google Chat 中傳送訊息至 Chat 應用程式。
  • 使用者提及即時通訊應用程式。
  • 使用者叫用 Chat 應用程式其中一個斜線指令

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

同步訊息不需要授權
圖 2. 同步訊息不需要驗證

  1. 使用者傳送訊息至 Google Chat 中的 Chat 應用程式。
  2. Google Chat 會將訊息轉寄至應用程式。
  3. 應用程式會收到訊息、進行處理,然後向 Google Chat 傳回回應。
  4. Google Chat 會為使用者或聊天室顯示回覆。

系統會針對每個 Chat 事件重複此序列。

非同步訊息需要驗證

即時通訊應用程式向 Chat REST API 傳送要求且需要驗證和授權時,會發生非同步訊息。

透過呼叫 REST API,Chat 應用程式可代表 Google Chat 傳送訊息,或代表使用者完成工作及存取資料。舉例來說,Chat 應用程式在偵測到伺服器服務中斷情形時,可以呼叫 Chat API 來執行下列作業:

  • 建立 Chat 聊天室,以調查及修正服務中斷情形。
  • 將使用者加入 Chat 聊天室。
  • 請在 Chat 聊天室中張貼訊息,提供有關服務中斷的詳細資訊。

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

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

  1. 即時通訊應用程式會使用 spaces.messages.create 方法呼叫 Chat REST API,並在 HTTP 要求中加入服務帳戶憑證,藉此建立訊息。
  2. Google Chat 會使用服務帳戶或使用者憑證來驗證 Chat 應用程式。
  3. Google Chat 會將應用程式的訊息轉譯成指定的 Chat 聊天室。

Chat API 範圍

如要定義授予應用程式的存取權層級,您必須識別並宣告授權範圍。授權範圍是一個 OAuth 2.0 URI 字串,其中包含 Google Workspace 應用程式名稱、存取的資料類型以及存取層級。

Google Chat 支援以下範圍:

Google Chat API 範圍 說明
https://www.googleapis.com/auth/chat.bot 允許 Chat 應用程式查看即時通訊和傳送訊息。
https://www.googleapis.com/auth/chat.delete 刪除 Google Chat 的對話和聊天室,並移除相關聯的檔案存取權。
頻道會員  
https://www.googleapis.com/auth/chat.memberships 查看、新增及移除 Google Chat 對話的成員。
https://www.googleapis.com/auth/chat.memberships.app 允許 Chat 應用程式在 Google Chat 的對話中新增及移除應用程式 (但不包括其他應用程式)。
訊息  
https://www.googleapis.com/auth/chat.messages 建立、取得、更新、刪除及列出 Google Chat 訊息。
https://www.googleapis.com/auth/chat.messages.reactions 在 Google Chat 中查看、新增和刪除訊息的回應。
https://www.googleapis.com/auth/chat.messages.reactions.create 在 Google Chat 中針對訊息新增回應。
https://www.googleapis.com/auth/chat.messages.reactions.readonly 在 Google Chat 中查看訊息的回應。
https://www.googleapis.com/auth/chat.messages.readonly 在 Google Chat 中取得並列出訊息。
聊天室  
https://www.googleapis.com/auth/chat.spaces 在 Google Chat 中建立對話和聊天室,以及查看或更新中繼資料 (包括記錄設定)。
https://www.googleapis.com/auth/chat.spaces.create 在 Google Chat 中建立對話。
https://www.googleapis.com/auth/chat.spaces.readonly 在 Google Chat 中查看即時通訊和聊天室。

如要進一步瞭解 Google Workspace API 的範圍,請參閱如何為應用程式選擇範圍

如需可用範圍的清單,請參閱適用於 Google API 的 OAuth 2.0 範圍一文。

必要驗證類型

Chat 應用程式可透過以下兩種方式使用 Chat API 驗證及授權:使用者憑證或服務帳戶。

透過使用者憑證授權,Chat 應用程式可以存取指定使用者資料,並代表使用者完成指定動作。授權資料和動作是由範圍指定。

透過服務帳戶授權,Chat 應用程式會使用服務帳戶憑證存取該 API 的應用程式。

如果您是網域管理員,可授予全網域授權委派,授權應用程式服務帳戶存取使用者資料,而無需向每個使用者提供同意聲明。設定全網域委派設定後,即可使用服務帳戶呼叫 API 以模擬使用者帳戶。儘管服務帳戶使用進行驗證,但全網域委派代表的是模擬使用者,因此屬於使用者驗證。凡是需要使用者驗證的功能,皆可使用全網域委派。

下表列出 Chat 應用程式遇到的常見情況、是否需要進行驗證,以及這類情境為何:

情境 不需驗證 支援使用者驗證 支援服務帳戶
接收他人傳送的訊息:
即時通訊事件
Apps Script 回呼
Google Cloud Pub/Sub
回應訊息:
透過 Chat 事件
透過 Apps Script 回呼傳回值,
透過 Chat REST API 以非同步方式
傳送新訊息:
使用連入 Webhook
使用 Chat REST API
建立 Chat 聊天室:
使用 Chat REST API
將使用者和應用程式加入 Chat 聊天室:
使用 Chat REST API
  • 如要瞭解 Google Workspace 的驗證和授權總覽,請參閱 Google Workspace for Developers 的瞭解驗證與授權
  • 如需 Google Cloud 驗證和授權總覽,請參閱 Google Cloud 說明文件的驗證總覽
  • 如要進一步瞭解服務帳戶,請參閱 Google Cloud Identity and Access Management (IAM) 說明文件中的服務帳戶一節。
  • 如要進一步瞭解 Google API 如何使用 OAuth 2.0,請參閱 Google Identity 說明文件中的使用 OAuth 2.0 存取 Google API

後續步驟

使用使用者憑證服務帳戶來設定驗證和授權。