將 Chat 應用程式與其他服務和工具連結

本頁面說明如何將 Google Chat 應用程式連結至 Google Chat 以外的服務或工具。Chat 應用程式本身功能強大，但通常會與其他系統協同運作，並需要搭配應用程式來連結帳戶、授權資料存取權、顯示其他資料或設定使用者偏好設定。

如要透過第三方服務或 OAuth 流程驗證使用者，Chat 應用程式會執行下列步驟：

  1. 偵測何時需要授權或設定。
  2. 傳回基本授權資訊卡，提示使用者登入或設定服務。
  3. 重新導向至完成 URI，讓 Google Chat 在使用者完成授權後，自動重試原始互動。

Google Chat 應用程式如何向第三方服務驗證身分的架構。

必要條件

HTTP

接收及回應使用者互動的 Google Chat 應用程式。如要建構一個，請完成 HTTP 快速入門。

Apps Script

接收及回應使用者互動的 Google Chat 應用程式。如要建構一個，請完成 Apps Script 快速入門導覽課程。

偵測是否需要授權

與 Chat 應用程式互動時，使用者可能因各種原因而無法存取受保護的資源，例如：

  • 存取權杖尚未產生或已過期，因此無法連線至第三方服務。
  • 存取權杖未涵蓋要求的資源。
  • 存取權杖未涵蓋要求所需的範圍。

Chat 應用程式應偵測這些情況，讓使用者登入並授權存取您的服務。

如果您使用 Apps Script 建構應用程式，可以運用 OAuth2 for Google Apps Script 程式庫 (或 OAuth1 版本)，其中的 hasAccess 函式會檢查使用者是否已授權存取服務。或者，使用 UrlFetchApp.fetch 請求時，您可以將 muteHttpExceptions 參數設為 true，檢查傳回的 HttpResponse 物件中的回應代碼和內容。

向使用者顯示基本授權資訊卡

當 Chat 應用程式偵測到需要授權或設定時，請傳回 AuthorizationError 回應，向使用者顯示私人基本授權資訊卡。

下圖顯示 Google 的基本授權卡片範例：

範例帳戶的基本授權提示。
圖 1：Example Account 的基本授權提示。 提示訊息指出，Chat 應用程式想顯示更多資訊，但需要使用者授權才能存取帳戶。

如要向使用者顯示基本授權資訊卡，請傳回 AuthorizationError 物件：

HTTP

傳回下列 JSON 回應：

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

更改下列內容：

  • AUTHORIZATION_URL：處理驗證、授權或設定的網頁應用程式 HTTPS 網址。
  • RESOURCE_DISPLAY_NAME：受保護資源或服務的顯示名稱。授權提示會向使用者顯示這個名稱。舉例來說，如果 RESOURCE_DISPLAY_NAME 是 Example Account，提示會指出應用程式需要核准才能存取您的 Example Account。

完成設定要求

在 Chat 中，使用者可以完成授權程序，Chat 會自動重試原始互動，無須手動重新整理。如果觸發條件為「訊息」、「已加入聊天室」或「應用程式指令」，Chat 支援自動重試。

對於這些觸發條件，Chat 應用程式會在事件酬載中收到完成重新導向 URI (configCompleteRedirectUri / completeRedirectUri)：

  • 訊息：chat.messagePayload.configCompleteRedirectUri
  • 已加入聊天室：chat.addedToSpacePayload.configCompleteRedirectUri
  • 應用程式指令：chat.appCommandPayload.configCompleteRedirectUri

您必須在 <var>AUTHORIZATION_URL</var> 中編碼這個重新導向 URI，並在授權流程完成後，將使用者的瀏覽器重新導向至該 URI。重新導向至這個網址，表示 Google Chat 已完成授權或設定要求。

使用者成功重新導向至原始事件酬載中提供的完成重新導向 URI 時，Google Chat 會執行下列步驟：

  1. 清除顯示給發起使用者的私人授權提示。
  2. 將原始訊息轉換為公開訊息，讓其他聊天室成員都能看到。
  3. 將原始事件物件第二次傳送至 Chat 應用程式。

如果沒有重新導向至完成重新導向 URI，使用者仍可完成授權流程，但 Google Chat 不會自動重試先前的執行作業，使用者必須手動再次叫用您的 Chat 應用程式。

造訪完成重新導向 URI 只會影響單一使用者互動。如果使用者多次傳送訊息給 Chat 應用程式，並收到多個提示，則完成其中一個提示的驗證和設定程序後，系統只會重試該特定互動。

在 Chat 以外驗證 Chat 使用者

連結至 Chat 以外的網址 (例如 OAuth 網頁回呼) 時，您通常需要將外部網頁工作階段與 Chat 中的使用者身分建立關聯。建議您使用 Google 登入保護目標網頁應用程式。

使用登入時核發的ID 權杖取得使用者 ID。sub 聲明包含使用者專屬的 Google ID，可與 Google Chat 中的使用者資源名稱 (chat.user.name) 相互關聯。

如要將 sub 聲明與 Google Chat users/{user} 資源名稱建立關聯，請在 sub 聲明值前面加上 users/。舉例來說，sub 聲明值 123 對應至傳送至 Chat 應用程式的事件物件中的 users/123。

程式碼範例

下列程式碼範例示範 Chat 應用程式如何使用基本授權資訊卡要求離線 OAuth2 憑證、將憑證儲存在資料庫中、重新導向至完成 URI，以及使用使用者驗證發出 API 呼叫：

非外掛程式的 Chat 擴充應用程式：將 Chat 擴充應用程式連結至其他服務和工具

如果您維護的 Chat 應用程式不是 Google Workspace 外掛程式，Chat 應用程式會使用 actionResponse (類型為 REQUEST_CONFIG) 要求設定，並從頂層 Event 物件讀取 configCompleteRedirectUrl。

如要將非外掛程式的 Chat 應用程式升級至 Google Workspace 外掛程式架構，請參閱「將 Google Chat 應用程式轉換為 Google Workspace 外掛程式」。

在非外掛程式的 Chat 應用程式中要求設定

在非外掛程式的 Chat 應用程式中，以以下形式將設定網址傳回給使用者：

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

這會指示 Google Chat 向使用者顯示私人提示，其中 CONFIGURATION_URL 是使用者可造訪的連結，用於進行額外的驗證、授權或設定。REQUEST_CONFIG 回覆與一般回覆訊息互斥，系統會忽略任何文字、資訊卡或其他屬性。

在非外掛程式的 Chat 應用程式中完成設定要求

Chat 應用程式 (非外掛程式) 收到的每項 MESSAGE、ADDED_TO_SPACE 和 APP_COMMAND 互動 Event 都包含頂層欄位 configCompleteRedirectUrl。在設定網址中編碼這個網址，並在完成後將使用者重新導向至該網址，讓 Google Chat 刪除提示、將原始訊息轉換為公開訊息，並將原始互動事件重新傳送至您的 Chat 應用程式。

如需實作範例，請參閱 GitHub 上的 Node.js 連線應用程式範例和 Python MyProfile 驗證應用程式範例。