このページは Cloud Translation API によって翻訳されました。

HTTP Google Chat アプリを作成する

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

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

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

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

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

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

目標

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

前提条件

Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
課金を有効にした Google Cloud プロジェクト。既存のプロジェクトで課金が有効になっていることを確認するには、プロジェクトの課金ステータスを確認するをご覧ください。プロジェクトを作成して課金管理を設定するには、Google Cloud プロジェクトを作成するをご覧ください。

環境を設定する

Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の 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 Run 関数を作成してデプロイする

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

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

Node.js

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

Cloud Run に移動

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

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

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

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

node/avatar-app/index.js

GitHub で表示

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}},
          ],
        }],
      },
    }],
  };
}

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

Python

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

Cloud Run に移動

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

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

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

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

python/avatar-app/main.py

GitHub で表示

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}},
                            ]
                        }
                    ],
                },
            }
        ],
    }

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

Java

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

Cloud Run に移動

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

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

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

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

java/avatar-app/src/main/java/AvatarApp.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.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)))))))));
  }
}

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/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>

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

関数を呼び出すための Google Chat の認可

Google Chat が関数を呼び出すことを承認するには、Cloud Run 起動元ロールを持つ Google Chat サービスアカウントを追加します。

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

Cloud Run に移動
Cloud Run サービスリストで、受信側関数の横にあるチェックボックスをオンにします。（関数自体はクリックしないでください）。
[権限] をクリックします。[権限] パネルが開きます。
[プリンシパルを追加] をクリックします。
[新しいプリンシパル] に「chat@system.gserviceaccount.com」と入力します。
[ロールを選択] で、[Cloud Run] > [Cloud Run 起動元] を選択します。
[保存] をクリックします。

Chat 用アプリを構成する

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

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

Cloud Run に移動

Cloud Run を有効にしたプロジェクトが選択されていることを確認します。
サービスのリストで、[quickstartchatapp] をクリックします。
[サービスの詳細] ページで、関数の URL をコピーします。
「Google Chat API」を検索し、[Google Chat API]、[管理] の順にクリックします。

Chat API に移動
[構成] をクリックして、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 にロギング] を選択します。
[保存] をクリックします。

Chat アプリは、Chat でメッセージを受信して返信できる状態になっています。

Chat 用アプリをテストする

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

信頼できるテスターとして登録した際に指定した Google Workspace アカウントを使用して、Google Chat を開きます。

Google Chat に移動
[チャットを新規作成] をクリックします。
[ユーザーを 1 人以上追加] フィールドに、Chat 用アプリの名前を入力します。
結果から Chat 用アプリを選択します。ダイレクトメッセージが開きます。

注: 結果のリストに Chat 用アプリが表示されない場合は、Google Cloud コンソールの Chat API 構成ページの [公開設定] に Google Workspace アカウントが含まれていることを確認してください。
そのアプリの新しいダイレクトメッセージに、「Hello」と入力して enter を押します。

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

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

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

トラブルシューティング

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

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

クリーンアップ

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

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このチュートリアルで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。appspot.com の URL など、プロジェクト ID を使用する URL を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースを削除します。

複数のチュートリアルとクイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにできます。

Google Cloud コンソールで、[リソースの管理] ページに移動します。メニュー アイコン > [IAM と管理] > [リソースの管理] をクリックします。
Resource Manager に移動します。
プロジェクトリストで、削除するプロジェクトを選択し、[削除] をクリックします。
ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

HTTP Google Chat アプリを作成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

前提条件

環境を設定する

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

Node.js

Python

Java

関数を呼び出すための Google Chat の認可

Chat 用アプリを構成する

Chat 用アプリをテストする

トラブルシューティング

クリーンアップ

関連トピック

HTTP Google Chat アプリを作成する