HTTP Google Chat アプリを作成する

このページでは、HTTP Chat アプリを作成する方法について説明します。このアーキテクチャを実装する方法はいくつかあります。Google Cloud では、Cloud Run と App Engine を使用できます。このクイックスタートでは、Chat アプリがユーザーのメッセージに応答するために使用する Cloud Run functions の関数を作成してデプロイします。

このアーキテクチャでは、次の図に示すように、HTTP を使用して Google Cloud またはオンプレミス サーバーと統合するように Chat を構成します。

オンプレミス サーバーのウェブサービスを使用する Chat 用アプリのアーキテクチャ。

上の図では、HTTP Chat アプリを操作するユーザーの情報フローは次のようになります。

  1. ユーザーが、ダイレクト メッセージまたは Chat スペースで Chat アプリにメッセージを送信します。
  2. HTTP リクエストが、Chat アプリのロジックを含むクラウドまたはオンプレミス システムであるウェブサーバーに送信されます。
  3. 必要に応じて、Chat アプリのロジックを Google Workspace サービス（カレンダーやスプレッドシートなど）、他の Google サービス（マップ、YouTube、Vertex AI など）、または他のウェブサービス（プロジェクト管理システムやチケット発行ツールなど）と統合できます。
  4. ウェブサーバーは、HTTP レスポンスを Chat の Chat アプリサービスに返送します。
  5. レスポンスがユーザーに配信されます。
  6. 必要に応じて、Chat アプリは Chat API を呼び出して、メッセージを非同期で投稿したり、他のオペレーションを実行したりできます。

このアーキテクチャでは、さまざまなプログラミング言語を使用して Chat アプリを設計できるため、システムにすでに存在する既存のライブラリやコンポーネントを柔軟に使用できます。

目標

  • 環境をセットアップする。
  • Cloud Run functions の関数を作成してデプロイする。
  • アプリを Chat に公開する。
  • アプリをテストする。

前提条件

環境を設定する

Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の API を有効にできます。

  • Google API コンソールで、Google Chat API、Cloud Build API、Cloud Functions API、 Cloud Pub/Sub API、Cloud Logging API、Artifact Registry API、Cloud Run API を有効にします。

    API を有効にする

Cloud Run functions の関数を作成してデプロイする

送信者の表示名とアバター画像を含む Chat カードを生成する Cloud Run functions の関数を作成してデプロイします。Chat アプリがメッセージを受信すると、関数が実行され、カードで応答します。

Chat アプリの関数を作成してデプロイする手順は次のとおりです。

Node.js

  1. Google API コンソールで、[Cloud Run] ページに移動します。

    Cloud Run に移動

    Chat アプリのプロジェクトが選択されていることを確認します。

  2. [関数を作成] をクリックします。

  3. [サービスの作成] ページで、関数を設定します。

    1. [サービス名] フィールドに「quickstartchatapp」と入力します。
    2. [リージョン] リストでリージョンを選択します。
    3. [ランタイム] リストで、最新バージョンの Node.js を選択します。
    4. [認証] セクションで、[認証を要求する] を選択します。
    5. [**作成**] をクリックし、Cloud Run がサービスを作成するのを待ちます。 コンソールが [ソース] タブにリダイレクトされます。

  4. [ソース] タブで、次の操作を行います。

    1. [**エントリ ポイント**] で、デフォルトのテキストを削除して「avatarApp」と入力します。

    2. index.js の内容を次のコードに置き換えます。

      node/avatar-app/index.js
      const functions = require('@google-cloud/functions-framework');

// Command IDs (configure these in Google Chat API)
const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
const HELP_COMMAND_ID = 2; // ID for the "Help" quick command

/**
 * Google Cloud Function that handles HTTP requests from Google Chat.
 *
 * @param {Object} req - The HTTP request object sent from Google Chat.
 * @param {Object} res - The HTTP response object.
 */
functions.http('avatarApp', (req, res) => {
  const event = req.body;

  if (event.appCommandMetadata) {
    handleAppCommands(event, res);
  } else {
    handleRegularMessage(event, res);
  }
});

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

/**
 * Handles regular messages (not commands).
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleRegularMessage(event, res) {
  const messageData = createMessage(event.user);
  res.send(messageData);
}

/**
 * Creates a card message with the user's avatar.
 *
 * @param {Object} user - The user who sent the message.
 * @param {string} user.displayName - The user's display name.
 * @param {string} user.avatarUrl - The URL of the user's avatar.
 * @return {Object} - The card message object.
 */
function createMessage({displayName, avatarUrl}) {
  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: {
          title: `Hello ${displayName}!`,
        },
        sections: [{
          widgets: [
            {textParagraph: {text: 'Your avatar picture:'}},
            {image: {imageUrl: avatarUrl}},
          ],
        }],
      },
    }],
  };
}

    3. [保存して再デプロイ] をクリックします。

Python

  1. Google API コンソールで、[Cloud Run] ページに移動します。

    Cloud Run に移動

    Chat アプリのプロジェクトが選択されていることを確認します。

  2. [関数を作成] をクリックします。

  3. [サービスの作成] ページで、関数を設定します。

    1. [サービス名] フィールドに「quickstartchatapp」と入力します。
    2. [リージョン] リストでリージョンを選択します。
    3. [ランタイム] リストで、最新バージョンの Python を選択します。
    4. [認証] セクションで、[認証を要求する] を選択します。
    5. [**作成**] をクリックし、Cloud Run がサービスを作成するのを待ちます。 コンソールが [ソース] タブにリダイレクトされます。

  4. [ソース] タブで、次の操作を行います。

    1. [エントリ ポイント] で、デフォルトのテキストを削除して「avatar_app」と入力します。

    2. main.py の内容を次のコードに置き換えます。

      python/avatar-app/main.py
      from typing import Any, Mapping

import flask
import functions_framework

# Command IDs (configure these in Google Chat API)
ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
HELP_COMMAND_ID = 2  # ID for the "Help" quick command


@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
    """Google Cloud Function that handles HTTP requests from Google Chat.

    Args:
        flask.Request: the request

    Returns:
        Mapping[str, Any]: the response
    """
    event = req.get_json(silent=True)

    if event and "appCommandMetadata" in event:
        return handle_app_commands(event)
    else:
        return handle_regular_message(event)


def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}




def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles regular messages (not commands).

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """

    if not event or "user" not in event:
        return "Invalid request."

    message_data = create_message(event["user"])
    return message_data


def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
    """Creates a card message with the user's avatar.

    Args:
        Mapping[str, Any] user: The user who sent the message.

    Returns:
        Mapping[str, Any]: a card with the user's avatar.
    """
    display_name = user.get("displayName", "")
    avatar_url = user.get("avatarUrl", "")

    return {
        "text": "Here's your avatar",
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": {"title": f"Hello {display_name}!"},
                    "sections": [
                        {
                            "widgets": [
                                {"textParagraph": {"text": "Your avatar picture:"}},
                                {"image": {"imageUrl": avatar_url}},
                            ]
                        }
                    ],
                },
            }
        ],
    }

    3. [保存して再デプロイ] をクリックします。

Java

  1. Google API コンソールで、[Cloud Run] ページに移動します。

    Cloud Run に移動

    Chat アプリのプロジェクトが選択されていることを確認します。

  2. [関数を作成] をクリックします。

  3. [サービスの作成] ページで、関数を設定します。

    1. [サービス名] フィールドに「quickstartchatapp」と入力します。
    2. [リージョン] リストでリージョンを選択します。
    3. [ランタイム] リストで、最新バージョンの Java を選択します。
    4. [認証] セクションで、[認証を要求する] を選択します。
    5. [**作成**] をクリックし、Cloud Run がサービスを作成するのを待ちます。 コンソールが [ソース] タブにリダイレクトされます。

  4. [ソース] タブで、次の操作を行います。

    1. [**エントリ ポイント**] で、デフォルトのテキストを削除して「App」と入力します。
    2. src/main/java/com/example/Example.java を src/main/java/AvatarApp.java に名前変更します。

    3. AvatarApp.java の内容を次のコードに置き換えます。

      java/avatar-app/src/main/java/AvatarApp.java
      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.api.services.chat.v1.model.User;
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 AvatarApp implements HttpFunction {
  private static final Gson gson = new Gson();

  // Command IDs (configure these in Google Chat API)
  private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
  private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);

    if (event.has("appCommandMetadata")) {
      handleAppCommands(event, response);
    } else {
      handleRegularMessage(event, response);
    }
  }

  /**
   * Handles slash and quick commands.
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
    int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

    switch (appCommandId) {
      case ABOUT_COMMAND_ID:
        Message aboutMessage = new Message();
        aboutMessage.setText("The Avatar app replies to Google Chat messages.");
        aboutMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(aboutMessage));
        return;
      case HELP_COMMAND_ID:
        Message helpMessage = new Message();
        helpMessage.setText("The Avatar app replies to Google Chat messages.");
        helpMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(helpMessage));
        return;
    }
  }

  /**
   * Handles regular messages (not commands).
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {

    if (!event.has("user")) {
      response.getWriter().write("Invalid request.");
      return;
    }

    JsonObject user = event.getAsJsonObject("user");
    String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
    String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);
    response.getWriter().write(gson.toJson(message));
  }

  /**
   * Creates a card message with the user's avatar.
   *
   * @param displayName The user's display name.
   * @param avatarUrl   The URL of the user's avatar.
   * @return The card message object.
   */
  private Message createMessage(String displayName, String avatarUrl) {
    return new Message()
        .setText("Here's your avatar")
        .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
                .setName("Avatar Card")
                .setHeader(new GoogleAppsCardV1CardHeader()
                    .setTitle(String.format("Hello %s!", displayName)))
                .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                    new GoogleAppsCardV1Widget()
                        .setTextParagraph(new GoogleAppsCardV1TextParagraph()
                            .setText("Your avatar picture:")),
                    new GoogleAppsCardV1Widget()
                        .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

    4. pom.xml の内容を次のコードに置き換えます。

      java/avatar-app/pom.xml
      <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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>gcfv2</groupId>
  <artifactId>avatar-app</artifactId>
  <version>0.0.1</version>
  <name>Avatar App</name>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.1.4</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.12.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-rev20250116-2.0.0</version>
    </dependency>

  </dependencies>

</project>

    5. [保存して再デプロイ] をクリックします。

関数を呼び出す権限を Google Chat に付与する

関数を呼び出す権限を Google Chat に付与するには、Google Chat サービス アカウントに Cloud Run 起動元 のロールを追加します。

  1. Google API コンソールで、[Cloud Run] ページに移動します。

    Cloud Run に移動

  2. Cloud Run サービスリストで、受信側関数の横にあるチェックボックスをオンにします。（関数自体はクリックしないでください）。

  3. [権限] をクリックします。[権限] パネルが開きます。

  4. [プリンシパルを追加] をクリックします。

  5. [新しいプリンシパル] に chat@system.gserviceaccount.com と入力します。

  6. [ロールを選択] で、[Cloud Run] > [Cloud Run 起動元] を選択します。

  7. [保存] をクリックします。

Chat アプリを構成する

Cloud Run functions の関数をデプロイしたら、次の手順に沿って Google Chat アプリに変換します。

  1. Google API コンソールで、[Cloud Run] ページに移動します。

    Cloud Run に移動

    Cloud Run を有効にしたプロジェクトが選択されていることを確認します 。

  2. サービスリストで [quickstartchatapp] をクリックします。

  3. [サービスの詳細] ページで、関数のURL をコピーします。

  4. 「Google Chat API」を検索し、[Google Chat API]、[管理] の順にクリックします。

    Chat API に移動

  5. [構成] をクリックして、Google Chat アプリを設定します。

    1. [この Chat アプリを Google Workspace アドオンとしてビルドする] をオフにします。確認を求めるダイアログが表示されます。ダイアログで [無効にする] をクリックします。
    2. [アプリ名] に Quickstart App と入力します。
    3. [アバターの URL] に「https://developers.google.com/chat/images/quickstart-app-avatar.png」と入力します。
    4. [説明] に Quickstart app と入力します。
    5. [機能] で、[スペースとグループの会話に参加する] を選択します。
    6. [接続設定] で、[HTTP エンドポイント URL] を選択します。
    7. [トリガー] で、[すべてのトリガーに共通の HTTP エンドポイント URL を使用する] を選択し、Cloud Run functions の関数トリガーの URL をボックスに貼り付けます。
    8. [公開設定] で、 [ドメイン内の特定のユーザーおよび グループにこの Chat 用アプリの利用を許可する] を選択し、メールアドレスを入力します。
    9. [ログ] で、[エラーを Logging に記録する] を選択します。

  6. [保存] をクリックします。

Chat アプリは、Chat でメッセージを受信して応答する準備ができました。

Chat 用アプリをテストする

Chat アプリをテストするには、Chat アプリとのダイレクト メッセージ スペースを開いてメッセージを送信します。

  1. 信頼できるテスターとして追加したときに指定した Google Workspace アカウントを使用して Google Chat を開きます。

    Google Chat に移動

  2. [**チャットを新規作成**] をクリックします。
  3. [1 人以上のユーザーを追加] フィールドに、Chat アプリの名前を入力します。

  4. 結果から Chat アプリを選択します。ダイレクト メッセージが開きます。

  5. そのアプリの新しいダイレクト メッセージに、「Hello」と入力して enter を押します。

Chat アプリのレスポンスには、次の画像に示すように、送信者の名前とアバター画像を表示する カード メッセージが含まれています。

送信者の表示名とアバター画像を含むカードで応答する Chat 用アプリ

信頼できるテスターを追加して、インタラクティブ機能のテストについて詳しくは、 Google Chat アプリのインタラクティブ機能をテストするをご覧ください。

トラブルシューティング

Google Chat アプリまたは カードがエラーを返すと、 Chat インターフェースに「問題が発生しました」というメッセージが表示されます。 または「リクエストを処理できませんでした」Chat UI にエラー メッセージが表示されない場合でも、Chat アプリまたはカードが予期しない結果を生成することがあります。たとえば、カード メッセージが表示されないことがあります。

Chat UI にエラー メッセージが表示されない場合でも、 Chat アプリのエラー ロギングが有効になっている場合は、エラーの修正に役立つ説明的なエラー メッセージとログデータを使用できます。 エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、Cloud プロジェクトを削除することをおすすめします。

  1. Google API Console で、[リソースの管理] ページに移動します。 [Menu] >[IAM & Admin] >[Manage Resources] をクリックします。

    [Resource Manager] に移動

  2. プロジェクト リストで、削除するプロジェクトを選択し、 [Delete] . をクリックします。
  3. ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。