使用 Cloud Functions 建構 HTTP Google Chat 應用程式

本頁面說明如何建立 HTTP Chat 應用程式。 實作這個架構的方法有很多種。在 Google Cloud 上 可以使用 Cloud Functions、Cloud Run 和 App Engine在本快速入門導覽課程中 編寫及部署 Cloud 函式 Chat 應用程式用來回覆使用者訊息的方式。

根據這個架構，您要將 Chat 設為整合 使用 HTTP 建立 Google Cloud 或地端部署伺服器，如 下圖：

在上圖中，使用者與 HTTP Chat 應用程式提供以下資訊流：

1. 使用者在 Chat 中傳送訊息給 透過即時訊息或 Chat 聊天室。
2. HTTP 要求會傳送到 含有 Chat 應用程式的地端部署系統 邏輯。
3. 您也可以選擇與 Chat 應用程式邏輯整合 Google Workspace 服務 (例如 Google 日曆和 試算表)、其他 Google 服務 (地圖、YouTube 和 Vertex AI) 或其他網路服務 (例如專案) 管理系統或售票工具)。
4. 網路伺服器將 HTTP 回應傳回給 Chat 中的即時通訊應用程式服務。
5. 回應會傳送給使用者。
6. Chat 應用程式也可以視需要呼叫 透過 Chat API 以非同步方式發布訊息或執行其他 operations.

這個架構讓您可以靈活運用現有程式庫， 系統中現有的元件 即時通訊應用程式可以使用不同的程式設計語言設計。

目標

• 設定環境。
• 建立及部署 Cloud 函式。
• 將應用程式發布到 Chat。
• 測試應用程式。

先備知識

• A 罩杯 Google Workspace 擁有存取權的帳戶 Google Chat 和 Google Cloud Functions。
• Google Cloud 專案。
• 請確認您已啟用 Cloud 專案的計費功能。學習新知 說明 驗證專案的帳單狀態。

設定環境

您必須先在 Google Cloud 專案中啟用這些 Google API，才能使用這些 API。 您可以在單一 Google Cloud 專案中啟用一或多個 API。

• 在 Google Cloud 控制台中，啟用 Google Chat API、Cloud Build API、Cloud Functions API。 Cloud Pub/Sub API、Cloud Logging API、Artifact Registry API 和 Cloud Run API。

  啟用 API

建立及部署 Cloud 函式

建立及部署可產生 Chat 資訊卡的 Cloud 函式 與傳送者的顯示名稱和顯示圖片。當 Chat 應用程式收到訊息後，會執行函式 回覆資訊卡

如要為 Chat 應用程式建立及部署函式， 請完成下列步驟：

Node.js

1. 前往 Google Cloud 控制台中的「Cloud Functions」頁面。

   前往 Cloud Functions 頁面

   請確認 Chat 應用程式的專案是 已選取。

2. 按一下 「Create Function」。

3. 在「建立函式」頁面中設定函式：

   1. 在「環境」中，選取「第 2 代」。
   2. 在「Function name」(函式名稱) 中輸入 QuickStartChatApp。
   3. 在「Region」(區域) 中，選取區域。
   4. 選取「驗證」下方的「需要驗證」。
   5. 點選「下一步」。

4. 在「執行階段」中，選取最新版本的 Node.js。

5. 在「原始碼」中，選取「內嵌編輯器」。

6. 在「進入點」中刪除預設文字並輸入 helloChat。

7. 將 index.js 的內容替換為以下程式碼：

   node/avatar-app/index.js

   前往 GitHub 查看

   /**
    * Google Cloud Function that responds to messages sent from a
    * Google Chat room.
    *
    * @param {Object} req Request sent from Google Chat room
    * @param {Object} res Response to send back
    */
   exports.helloChat = function helloChat(req, res) {
     if (req.method === 'GET' || !req.body.message) {
       res.send('Hello! This function is meant to be used in a Google Chat ' +
         'Room.');
     }
   
     const sender = req.body.message.sender.displayName;
     const image = req.body.message.sender.avatarUrl;
   
     const data = createMessage(sender, image);
   
     res.send(data);
   };
   
   /**
    * Creates a card with two widgets.
    * @param {string} displayName the sender's display name
    * @param {string} imageUrl the URL for the sender's avatar
    * @return {Object} a card with the user's avatar.
    */
   function createMessage(displayName, imageUrl) {
     const cardHeader = {
       title: `Hello ${displayName}!`,
     };
   
     const avatarWidget = {
       textParagraph: {text: 'Your avatar picture: '},
     };
   
     const avatarImageWidget = {
       image: {imageUrl},
     };
   
     const avatarSection = {
       widgets: [
         avatarWidget,
         avatarImageWidget,
       ],
     };
   
     return {
       text: 'Here\'s your avatar',
       cardsV2: [{
         cardId: 'avatarCard',
         card: {
           name: 'Avatar Card',
           header: cardHeader,
           sections: [avatarSection],
         }
       }],
     };
   }

8. 點選「Deploy」。

Python

1. 前往 Google Cloud 控制台中的「Cloud Functions」頁面。

   前往 Cloud Functions 頁面

   請確認 Chat 應用程式的專案是 已選取。

2. 按一下 「Create Function」。

3. 在「建立函式」頁面中設定函式：

   1. 在「環境」中，選取「第 2 代」。
   2. 在「Function name」(函式名稱) 中輸入 QuickStartChatApp。
   3. 在「Region」(區域) 中，選取區域。
   4. 選取「驗證」下方的「需要驗證」。
   5. 點選「下一步」。

4. 在「Runtime」(執行階段) 中，選取最新版本的 Python。

5. 在「原始碼」中，選取「內嵌編輯器」。

6. 在「進入點」中刪除預設文字並輸入 hello_chat。

7. 將 main.py 的內容替換為以下程式碼：

   python/avatar-app/main.py

   前往 GitHub 查看

   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   
   # Google Cloud Function that responds to messages sent in
   # Google Chat.
   #
   # @param {Object} req Request sent from Google Chat.
   # @param {Object} res Response to send back.
   @functions_framework.http
   def hello_chat(req: flask.Request) -> Mapping[str, Any]:
     if req.method == "GET":
       return "Hello! This function must be called from Google Chat."
   
     request_json = req.get_json(silent=True)
   
     display_name = request_json["message"]["sender"]["displayName"]
     avatar = request_json["message"]["sender"]["avatarUrl"]
   
     response = create_message(name=display_name, image_url=avatar)
   
     return response
   
   
   # Creates a card with two widgets.
   # @param {string} name the sender's display name.
   # @param {string} image_url the URL for the sender's avatar.
   # @return {Object} a card with the user's avatar.
   def create_message(name: str, image_url: str) -> Mapping[str, Any]:
     avatar_image_widget = {"image": {"imageUrl": image_url}}
     avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
     avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}
   
     header = {"title": f"Hello {name}!"}
   
     cards = {
         "text": "Here's your avatar",
         "cardsV2": [
             {
                 "cardId": "avatarCard",
                 "card": {
                     "name": "Avatar Card",
                     "header": header,
                     "sections": [avatar_section],
                 },
             }
         ]
     }
   
     return cards

8. 點選「Deploy」。

Java

1. 前往 Google Cloud 控制台中的「Cloud Functions」頁面。

   前往 Cloud Functions 頁面

   請確認 Chat 應用程式的專案是 已選取。

2. 按一下 「Create Function」。

3. 在「建立函式」頁面中設定函式：

   1. 在「環境」中，選取「第 2 代」。
   2. 在「Function name」(函式名稱) 中輸入 QuickStartChatApp。
   3. 在「Region」(區域) 中，選取區域。
   4. 選取「驗證」下方的「需要驗證」。
   5. 點選「下一步」。

4. 在「Runtime」(執行階段) 中，選取最新版本的 Java。

5. 在「原始碼」中，選取「內嵌編輯器」。

6. 在「進入點」中刪除預設文字並輸入 HelloChat。

7. 將「src/main/java/com/example/Example.java」重新命名為 src/main/java/HelloChat.java。

8. 將 HelloChat.java 的內容替換為以下程式碼：

   java/avatar-app/src/main/java/HelloChat.java

   前往 GitHub 查看

   import com.google.api.services.chat.v1.model.CardWithId;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
   import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
   import com.google.api.services.chat.v1.model.Message;
   import com.google.cloud.functions.HttpFunction;
   import com.google.cloud.functions.HttpRequest;
   import com.google.cloud.functions.HttpResponse;
   import com.google.gson.Gson;
   import com.google.gson.JsonObject;
   import java.util.List;
   
   public class HelloChat implements HttpFunction {
     private static final Gson gson = new Gson();
   
     @Override
     public void service(HttpRequest request, HttpResponse response) throws Exception {
       JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
   
       if (request.getMethod().equals("GET") || !body.has("message")) {
         response.getWriter().write("Hello! This function must be called from Google Chat.");
         return;
       }
   
       JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
       String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
       String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
       Message message = createMessage(displayName, avatarUrl);
   
       response.getWriter().write(gson.toJson(message));
     }
   
     Message createMessage(String displayName, String avatarUrl) {
       GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
       cardHeader.setTitle(String.format("Hello %s!", displayName));
   
       GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
       textParagraph.setText("Your avatar picture: ");
   
       GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
       avatarWidget.setTextParagraph(textParagraph);
   
       GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
       image.setImageUrl(avatarUrl);
   
       GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
       avatarImageWidget.setImage(image);
   
       GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
       section.setWidgets(List.of(avatarWidget, avatarImageWidget));
   
       GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
       card.setName("Avatar Card");
       card.setHeader(cardHeader);
       card.setSections(List.of(section));
   
       CardWithId cardWithId = new CardWithId();
       cardWithId.setCardId("previewLink");
       cardWithId.setCard(card);
   
       Message message = new Message();
       message.setText("Here's your avatar");
       message.setCardsV2(List.of(cardWithId));
   
       return message;
     }
   }

9. 將 pom.xml 的內容替換為以下程式碼：

   java/avatar-app/pom.xml

   前往 GitHub 查看

   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>cloudfunctions</groupId>
     <artifactId>http-function</artifactId>
     <version>1.0-SNAPSHOT</version>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <dependency>
         <groupId>com.google.cloud.functions</groupId>
         <artifactId>functions-framework-api</artifactId>
         <version>1.0.1</version>
       </dependency>
   
       <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
       <dependency>
           <groupId>com.google.code.gson</groupId>
           <artifactId>gson</artifactId>
           <version>2.9.1</version>
       </dependency>
   
       <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
       <dependency>
         <groupId>com.google.apis</groupId>
         <artifactId>google-api-services-chat</artifactId>
         <version>v1-rev20230115-2.0.0</version>
       </dependency>
     </dependencies>
   
     <!-- Required for Java 11 functions in the inline editor -->
     <build>
       <plugins>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.8.1</version>
           <configuration>
             <excludes>
               <exclude>.google/</exclude>
             </excludes>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>

10. 點選「Deploy」。

Cloud Functions 詳細資料頁面會開啟，然後您的函式會顯示兩個 進度指標：一個用於建構，另一個用於服務。如果兩者皆是 進度指標會消失，並替換成勾號，也就是您的函式 並準備就緒

授權 Google Chat 叫用函式

如要授權 Google Chat 叫用函式，請新增 Google Chat 擁有 Cloud Run 叫用者角色的服務帳戶。

1. 前往 Google Cloud 控制台中的 Cloud Run 頁面。

   前往 Cloud Run

2. 在 Cloud Run 服務清單中，勾選接收端旁的核取方塊 函式。(不要點選函式本身)。

3. 按一下 [權限]，「Permissions」(權限) 面板隨即開啟。

4. 按一下「新增主體」。

5. 在「New principals」(新增主體) 中輸入 [e-mail]。

6. 在「請選擇角色」中，選取「Cloud Run」>Cloud Run 叫用者。

7. 按一下 [儲存]。

將應用程式發布到 Google Chat

部署 Cloud 函式後，請按照下列步驟將函式轉換成 Google Chat 應用程式：

1. 在 Google Cloud 控制台中，按一下「選單」圖示 > Cloud Functions。

   前往 Cloud Functions 頁面

   請確認您啟用 Cloud Functions 的專案處於啟用狀態 已選取。

2. 在函式清單中，按一下「QuickStartChatApp」QuickStartChatApp。

3. 按一下「觸發條件」分頁標籤。

4. 在「HTTPS」下方複製網址。

5. 搜尋「Google Chat API」依序點選「Google Chat API」和「管理」。

   前往 Chat API

6. 按一下「設定」，然後設定 Google Chat 應用程式：

   1. 在「App name」(應用程式名稱) 中輸入 Quickstart App。
   2. 在「顯示圖片」中輸入 https://developers.google.com/chat/images/quickstart-app-avatar.png。
   3. 在「Description」(說明) 中輸入 Quickstart app。
   4. 在「功能」下方，選取「接收 1:1 訊息」， 加入聊天室和群組對話。
   5. 在「連線設定」下方，選取「應用程式網址」，並貼上以下項目的網址： 放入 Cloud 函式觸發條件
   6. 在「驗證目標對象」中，選取「應用程式網址」。
   7. 在「Visibility」(顯示設定) 下方選取 將這個 Google Chat 應用程式提供給特定使用者和 群組並輸入您的電子郵件地址。
   8. 在「記錄」底下，選取 [將錯誤記錄至 Logging]。

7. 按一下 [儲存]。

Chat 應用程式已準備好接收及回覆 Chat 訊息。

測試 Chat 應用程式

如要測試 Chat 應用程式，請開啟含有下列對話的即時訊息聊天室： 傳送訊息：

1. 使用你使用的 Google Workspace 帳戶開啟 Google Chat (在您將自己新增為信任的測試人員時提供)。

   前往 Google Chat

2. 按一下「新的即時通訊」圖示 。
3. 在 [新增 1 或多位使用者] 欄位中，輸入你的使用者名稱 Chat 應用程式。

4. 從搜尋結果中選取 Chat 應用程式。直接 訊息隨即開啟。

   注意：如果在清單中找不到您的 Chat 應用程式 請確實在 UI 設定瀏覽權限設定Chat API 設定 頁面。
5. 開啟與應用程式互傳的新即時訊息，輸入 Hello，然後按下 enter。

Chat 應用程式的回應含有 資訊卡訊息： 寄件者的名稱和顯示圖片，如下圖所示：

如要新增信任的測試人員並進一步瞭解如何測試互動功能，請參閱 測試互動式功能， Google Chat 應用程式。

疑難排解

Google Chat 應用程式或 card 會傳回錯誤， 即時通訊介面會顯示「發生錯誤」的訊息。 或「無法處理你的要求」。有時使用 Chat UI 不會顯示任何錯誤訊息，但 Chat 應用程式或 資訊卡產生非預期的結果例如資訊卡訊息 顯示。

雖然 Chat UI 中可能不會顯示錯誤訊息， 提供描述性錯誤訊息和記錄資料，協助您修正錯誤 。如需觀看說明， 偵錯及修正錯誤，請參閱 疑難排解並修正 Google Chat 錯誤。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取 但建議採用 Cloud 專案

注意：刪除專案會出現以下結果：

• 專案中的所有內容都會遭到刪除。 若您使用現有專案進行本教學課程，當您刪除專案時，也會一併刪除您在該專案中完成的任何其他工作。
• 自訂專案 ID 會遺失。您建立這項專案時，可能會建立一個日後想要使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 上的網址)，請刪除在專案中選取的資源，而不是刪除整個專案。

如果打算進行多個教學課程及快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

1. 在 Google Cloud 控制台中，前往「管理資源」頁面。按一下 選單 > IAM 與管理員 >「管理資源」。

   前往 Resource Manager

2. 在專案清單中選取要刪除的專案，然後按一下 刪除 。
3. 在對話方塊中輸入專案 ID，然後按一下「Shut down」(關閉) 即可刪除 專案。

相關主題

• 如要為 Chat 應用程式新增更多功能，請參閱 包括：

  • 建立互動式資訊卡訊息
  • 回應斜線指令
  • 開啟並回覆對話方塊

• 選擇 Chat 應用程式架構

• 驗證來自 Google Chat 的要求