將互動式 Google Chat 擴充應用程式轉換為 Google Workspace 外掛程式

如果您已建構並發布使用 Google Chat API 互動事件的 Google Chat 擴充應用程式 (例如以 Google Chat 擴充應用程式快速入門為基礎的應用程式)，本頁面將說明如何將其轉換為可擴充 Google Chat 的 Google Workspace 外掛程式。

轉換後，Google Chat 應用程式就能使用 Google Workspace 外掛程式架構，在 Google Chat 和 Google Workspace 中整合及提供新功能。舉例來說，您不必分別發布 Google Chat 應用程式和 Google Workspace 外掛程式，而是透過 Google Workspace Marketplace 發布單一 Google Workspace 外掛程式，即可擴充 Chat 應用程式，以及 Gmail、日曆和文件等其他 Google Workspace 主機應用程式。

限制

開始轉換前，請先詳閱擴充 Google Chat 的 Google Workspace 外掛程式限制，確保 Google Chat 應用程式轉換後仍可正常運作，不會失去重要功能。

步驟 1：複製現有的 Google Chat 應用程式程式碼

轉換程序需要變更程式碼。為避免影響 Google Chat 應用程式的運作，請建立並使用程式碼副本。

Apps Script

  1. 開啟現有的 Google Chat 應用程式 Google Apps Script 專案。
  2. 按一下左側的「總覽」。
  3. 按一下右側的「建立副本」圖示 。
  4. 按一下左側的「專案設定」圖示 。
  5. 點選「Google Cloud 專案」下方的「變更專案」。
  6. 輸入與現有 Google Chat 應用程式專案相關聯的專案編號。
  7. 點選「設定專案」。

HTTP

建立現有程式碼集的副本或分叉，並部署為與 Google Chat 應用程式不同的新服務。

如果應用程式部署在 Google Cloud 上，且依賴與 Google Cloud 專案相關聯的功能 (例如預設的 App Engine 身分)，則應將新程式碼部署在與現有 Google Chat 應用程式專案相關聯的服務上。

步驟 2：修改複製的程式碼

與使用 Chat API 互動事件建構的 Google Chat 應用程式相比，擴充 Google Chat 的 Google Workspace 外掛程式會使用不同的要求和回應結構。您需要更新程式碼，改用 Google Workspace 外掛程式 EventObject，而非 Google Chat API 的 Event 處理要求和回應。請參閱程式碼轉換指南，修改程式碼。

步驟 3：為測試使用者啟用 Google Workspace 外掛程式設定

使用 Google Cloud 控制台，為 Google Chat 應用程式設定 Google Workspace 外掛程式：

  1. 前往 Google Cloud 控制台的 Google Chat API 設定頁面。

    前往 Google Chat API 設定頁面

  2. 在「互動式功能」下方，按一下「轉換為外掛程式」。

  3. 啟用「開啟外掛程式設定」。

  4. 在「瀏覽權限」部分，新增測試使用者的電子郵件地址。

  5. 如有需要，請使用在步驟 2 中複製及修改的 Google Chat 應用程式程式碼，更新「連線設定」，並提供部署作業端點網址或 Apps Script 部署作業 ID。

  6. 按一下「儲存並測試」。

步驟 4：測試轉換後的應用程式

使用步驟 3 中設定的測試使用者帳戶，徹底測試 Google Workspace 外掛程式功能。確認所有功能和互動。

步驟 5：為所有使用者完成轉換

確認轉換後的 Google Workspace 外掛程式運作正常後，即可開放所有使用者使用。

  1. 前往 Google Cloud 控制台的 Google Chat API 設定頁面。

    前往 Google Chat API 設定頁面

  2. 在「互動式功能」下方，按一下「轉換為外掛程式」。側邊面板隨即開啟。

  3. 按一下側邊面板中的「轉換為外掛程式」。

  4. 輸入專案 ID，然後按一下「轉換」。

您的 Google Chat 擴充應用程式現在是 Google Workspace 外掛程式，可擴充 Google Chat。

選用：清除或釋出未使用的 Google Cloud 資源

(選用) 將 Google Chat 應用程式轉換為 Google Workspace 外掛程式後，如要避免系統向您的 Google Cloud 帳戶收取不再使用的 Google Chat 應用程式資源費用，請考慮將這些資源關閉。

程式碼轉換指南

本節詳細說明 Google Chat API 互動Event格式與 Google Workspace 外掛程式EventObject格式之間的對應關係。

要求對應

下表顯示 Google Chat API Event 中的欄位如何對應至 Google Workspace 外掛程式 EventObject 中的對應欄位。

Google Chat API 互動 Event 欄位 Google Workspace 外掛程式 EventObject 欄位 附註
action.actionMethodName 不適用 如為卡片互動，方法名稱可做為 commonEventObject.parameters 中的參數傳遞。請參閱「開啟初始對話方塊」。
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 視事件類型而定，可透過不同酬載取得。
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 視事件類型而定，可透過不同酬載取得。
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 視事件類型而定，可透過不同酬載取得。
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 視事件類型而定，可透過不同酬載取得。
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 視事件類型而定，可透過不同酬載取得。
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 視事件類型而定，可透過不同酬載取得。
token 不適用 驗證方式不同，請參閱「要求 HTTP 應用程式驗證」。
type 不適用 事件類型可從觸發條件推斷。
user chat.user

依用途對應要求

下表列出常見用途的請求酬載差異，包括使用 Chat API 互動事件建構的 Google Chat 應用程式，以及擴充 Google Chat 的 Google Workspace 外掛程式。

用途 Chat API 互動 Event 酬載 Google Workspace 外掛程式 EventObject 酬載
已將應用程式新增至聊天室 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
從聊天室中移除應用程式 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
使用者 @ 提及應用程式 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
使用者 @ 提及應用程式，將其新增至聊天室 您需要處理 Google Chat 的一項要求：
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 您必須處理 Google Chat 的兩項要求。

第一項要求：
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

第二個要求：
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
斜線指令 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
將應用程式加入聊天室的斜線指令 您需要處理 Google Chat 的一項要求：
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 您必須處理 Google Chat 的兩項要求。

第一項要求：
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

第二個要求：
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
使用者點選資訊卡或對話方塊上的按鈕 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

如果是對話方塊事件，common.formInputs 則包含小工具值。Google Apps Script 範例：

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

如果是對話方塊事件，commonEventObject.formInputs 則包含小工具值。Google Apps Script 範例：

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
使用者在應用程式主畫面資訊卡中提交資訊 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
使用者透過快速指令叫用應用程式指令 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
連結預覽 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
使用者更新訊息或對話方塊中的小工具 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

依用途對應回應

擴充 Google Chat 的 Google Workspace 外掛程式會傳回動作，而非 Message 物件。下表列出 Google Chat API Message 回應類型與 Google Workspace 外掛程式動作的對應關係。

用途 Google Chat API Message 回應 Google Workspace 外掛程式 Chat 動作回應
在叫用的聊天室中建立訊息 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse 為選填欄位。詳情請參閱「回覆斜線指令」。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

詳情請參閱「傳送訊息」一文。
更新訊息 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

詳情請參閱「更新訊息 (Chat)」。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

詳情請參閱「更新訊息 (外掛程式)」。
連結預覽 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

詳情請參閱「預覽連結 (Chat)」。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

詳情請參閱「預覽連結(外掛程式)」。
開啟初始對話方塊 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

詳情請參閱「開啟對話方塊 (Chat)」。

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
推送的資訊卡可以包含具有 onClick 動作的小工具。如果是 HTTP Google Workspace 外掛程式，請設定這些動作來呼叫函式端點：
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

詳情請參閱「開啟對話方塊 (外掛程式)」。
關閉對話方塊 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

詳情請參閱「關閉對話方塊 (Chat)」。

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

詳情請參閱「關閉對話方塊 (外掛程式)」。
連線至外部系統 (要求設定) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

詳情請參閱「連結至外部系統」。

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

詳情請參閱「將 Google Workspace 外掛程式連結至第三方服務」。
互動式小工具的自動完成項目 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

詳情請參閱「新增多選選單」。

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

詳情請參閱「收集及處理 Google Chat 使用者的資訊」。

處理轉換前建立的訊息中的互動式資訊方塊

將 HTTP Google Chat 應用程式轉換為 Google Workspace 外掛程式時，轉換前建立的郵件卡片互動需要特別處理。Google Workspace 外掛程式會使用資訊卡的完整 HTTP 網址做為 action.function，而使用 Google Chat API 互動事件建構的 Google Chat 應用程式則會使用函式名稱。下表摘要說明這些差異。

使用 Google Chat API 互動事件建構的 Google Chat 應用程式 擴充 Google Chat 的 Google Workspace 外掛程式
設定 您可以在 Google Cloud 控制台中，為所有事件設定單一端點。實作卡片互動時，卡片的 action 只會包含要執行的函式名稱。系統會針對卡片點擊事件叫用常見的 HTTP 端點。

詳情請參閱「開啟對話方塊 (Chat)」。



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 您可以在 Google Cloud 控制台中設定每個事件的端點，但這不包括資訊卡點擊事件。實作資訊卡互動時，資訊卡的 action 必須包含要叫用的 HTTP 端點完整網址。您可以為每個按鈕設定專屬的 HTTP 端點，也可以使用通用端點，並在 action.parameters 中將動作做為參數傳遞。

詳情請參閱「開啟對話方塊 (外掛程式)」。



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

如要確保轉換前建立的訊息能正常互動，請在 Google Chat API 設定頁面設定「資訊卡互動網址」。

這個網址僅適用於應用程式轉換前建立的訊息互動。使用者與其中一則訊息互動時，系統會將原始 action.function 值做為名為 __action_method_name__ 的參數傳遞。

範例：點選卡片

如果您將資訊卡互動網址設為 https://.../card-interaction-handler，且使用者對含有資訊卡的舊訊息執行下列動作：

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

系統會以以下格式，將事件傳送至您設定的資訊卡互動網址：

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

範例：多重選取選單

如果使用者與外部資料來源的多選單互動：

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

系統會以以下格式，將事件傳送至您設定的資訊卡互動網址：

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

如果為 HTTP 觸發條件啟用「為所有觸發條件使用通用的 HTTP 端點網址」，系統也會將通用網址用於「已點選按鈕」事件。

驗證擴充 Chat 的 HTTP Google Workspace 外掛程式要求

如果是以 HTTP 為基礎的 Google Chat 應用程式，轉換為 Google Workspace 外掛程式時，必須更新驗證要求是否來自 Google 的邏輯。

要求驗證的主要差異如下：

應用程式類型 適用的目標對象 服務帳戶電子郵件
使用 Google Chat API 互動事件建構的 Google Chat 應用程式 專案編號 chat@system.gserviceaccount.com
擴充 Google Chat 的 Google Workspace 外掛程式 僅限 HTTP 端點 每項專案專屬的服務帳戶電子郵件地址

您可以在 Google Cloud 控制台的 Google Chat API 設定頁面，找到 Google Workspace 外掛程式的專屬服務帳戶電子郵件地址，位置在「Convert to Google Workspace add-ons」部分。

如要驗證升級後的 Google Workspace 外掛程式中的要求，請按照下列步驟操作：

  1. 如果使用 Cloud Run 函式，請將 roles/cloudfunctions.invoker 角色授予每個外掛程式的服務帳戶。請參閱「使用 IAM 授權存取權」。
  2. 請更新權杖驗證碼，使用 Google Workspace 外掛程式服務帳戶電子郵件驗證 Bearer 權杖的簽章。請參閱「驗證 Google 的要求」。