Google Chat API を構成する

作成する Google Chat アプリごとに、Chat API が有効化され、構成された独自の Google Cloud プロジェクトが必要です。

スペースの取得やメッセージの一覧表示など、ユーザー認証で読み取り専用の API 呼び出しを行うには、API を有効にして OAuth クライアントを作成するだけです。

API 呼び出しの作成、更新、削除を行う場合や、インタラクティブな Chat アプリ(Chat を拡張する Google Workspace アドオンとして構築)をデプロイしてテストする場合は、Chat API も構成する必要があります。Chat API の構成設定では、表示名、アバター、デプロイ エンドポイント、インタラクティブ機能など、Chat アプリに関するすべての詳細を指定します。

前提条件

Chat 用アプリの表示名、アバター、説明を選択する

Chat API を有効にすると、Chat でユーザーに表示される Chat アプリの詳細(表示名、アバター、説明など)を構成できます。これらの詳細は Chat にのみ表示されます。Chat アプリを Marketplace に公開するには、Chat アプリの Marketplace の掲載情報に表示される詳細も指定する必要があります。

Chat 用アプリを構成する前に、次の情報を準備します。

フィールド 説明 形式
アプリ名 Chat 用アプリの表示名。 最大 25 文字の英数字
アバターの URL Chat 用アプリのアバターとして表示される画像。 正方形のグラフィック画像(PNG または JPEG)を指す HTTPS URL。 推奨サイズは 256 × 256 ピクセル以上です。
説明 Chat 用アプリの簡単な説明。ユーザーが Chat でアプリを検索したときに表示されます。 最大 40 文字の英数字
詳しい説明文 省略可。Chat 用アプリでできることの説明。ユーザーが Chat 用アプリとの会話を開始するか、エージェントのセッション ホームページを開いたときに表示されます。現在、Google Cloud コンソールを使用してアプリ構成を更新する場合にのみサポートされており、Google Workspace アドオン API ではサポートされていません。 250 文字まで

Chat アプリの名前、アバター、説明が Chat UI でユーザーに表示されます。一部の Chat API 書き込みリクエストでは、Chat はこの情報を使用して、Chat 用アプリが Chat で行うアクションを属性付けします。

たとえば、spaces.create() メソッドを呼び出すと、次の画像に示すように、スペースを作成したユーザーの説明に Chat 用アプリの名前が含まれます。

Google Chat アプリがユーザー用のスペースを作成する。
図 1. spaces.create() メソッドを使用してユーザーに代わってスペースを作成するときに Chat に表示される帰属メッセージ。

Chat 用アプリを操作する際、ユーザーは次の方法でこの情報を確認または使用することもできます。

  • Chat 用アプリを @ メンションして、スペースに追加するか、メッセージを送信します。
  • Chat 用アプリを見つけてダイレクト メッセージを開始します。[アプリ] メニューのダイレクト メッセージには、Chat 用アプリの名前とアバターが表示されます。
  • ユーザーは、入力バーから Chat 用アプリをブラウジングして、名前、アバター、説明を確認できます。

Google Cloud コンソールで Chat アプリを構成する

Chat 用アプリの詳細を確認したら、Cloud プロジェクトを開いて Chat API を構成します。

  1. Google Cloud コンソールで、Chat API ページに移動し、[構成] ページをクリックします。

    [Chat API の構成] ページに移動

  2. [アプリケーション情報] で、[アプリ名]、[アバターの URL]、[説明] の各フィールドに入力します。

  3. 省略可: [Long description] フィールドに入力します。

  4. 省略可: [マークアップ構文] メニューから、Chat アプリのメッセージのデフォルトのマークアップ構文([マークダウン] または [Chat])を選択します。テキストの書式設定と、Chat が API リクエストのマークアップ構文を決定する方法については、メッセージの書式設定をご覧ください。

  5. [インタラクティブな機能] で、Chat アプリがユーザー操作に応答するかどうかを構成します。

    インタラクティブな Chat 用アプリを構築するには、[インタラクティブ機能を有効にする] をオンにして、次の操作を行います。

    1. [機能] で以下を実行します。
      • 省略可: [アプリホームをサポートする] を選択して、Chat アプリとの 1 対 1 のダイレクト メッセージの [ホーム] タブにホームページ カードを表示します。
      • [スペースとグループの会話に参加する] を選択して、Chat アプリをインストールして使用できるようにします。デフォルトでは、ユーザーは Chat 用アプリをインストールし、ユーザーと Chat 用アプリの間の専用スペースで Chat 用アプリとメッセージをやり取りできます。また、ユーザーは複数のユーザーがいるスペースに Chat 用アプリを追加して、Chat 用アプリとやり取りすることもできます。
    2. [接続設定] で、Chat からイベント オブジェクトを受信するために使用するアーキテクチャを選択します。

      • HTTP サービスを使用するには、[HTTP エンドポイント URL] を選択して URL を指定します。
      • Google Apps Script プロジェクトを使用するには、[Apps Script] を選択し、プロジェクトのデプロイ ID を指定します。
      • Dialogflow エージェントを使用するには、[Dialogflow] を選択し、[Dialogflow CX] または [Dialogflow ES] を選択して、エージェントのリソース名を指定します。
      • Pub/Sub を使用するには、[Cloud Pub/Sub] を選択してトピック名を入力します。
    3. 省略可: イベント オブジェクトを特定のエンドポイントまたは関数にルーティングするには、[接続設定] > [トリガー] に移動し、次の Chat トリガーのコールバック エンドポイントまたは関数を指定または更新します。

      • アプリホーム([アプリホームをサポート] が有効になっている場合): ユーザーが Chat アプリとの 1 対 1 のダイレクト メッセージで [ホーム] タブを開きます。
      • スペースに追加: ユーザーがグループの会話またはスペースに Chat 用アプリを追加するか、1 対 1 のメッセージ用に Chat 用アプリをインストールします。
      • メッセージ: ユーザーが Chat 用アプリにメッセージを送信します。たとえば、ユーザーが Chat 用アプリにダイレクト メッセージを送信したり、複数のユーザーがいるスペースで Chat 用アプリを @メンションしたりします。
      • スペースから削除: ユーザーがスペースから Chat 用アプリをアンインストールまたは削除した。
      • アプリコマンド: ユーザーが Chat アプリからクイック コマンド、スラッシュ コマンド、またはメッセージ アクションを呼び出します。
    4. 省略可: セッション、スターター プロンプト、コマンド(クイック コマンド、スラッシュ コマンド、メッセージ アクション)、リンク プレビューなどの他のインタラクティブ機能を追加します。

    5. [公開設定] で [この Chat 用アプリを特定のユーザーとグループが使用できるようにします] を選択し、Google Workspace 組織内の個人または Google グループのメールアドレスを入力します。

      • 自分でアプリをインストールしてテストするには、自分のメールアドレスを入力します。
      • Marketplace に公開せずに、チームまたは組織全体で内部 Chat 用アプリを共有するには、1 つ以上の Google グループを入力します。グループのメンバー数に上限はありません。アプリが chat.app.* スコープをリクエストする場合は、管理者の承認を得るためにアプリを公開する必要があります。
      • 管理者が Marketplace のインストールを許可リストのアプリに制限している場合、Google Cloud コンソールでは、このフィールドを開発用の 5 つの個別のユーザー メールアドレスに制限します。グループの公開設定は、管理者がアプリを許可リストに追加した後にのみ適用されます。
  6. 省略可: [ログ] で、[Logging にエラーを記録する] チェックボックスをオンにして、Google Cloud Logging を使用します。詳細については、Chat 用アプリのエラーログをクエリするをご覧ください。

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

構成を保存すると、Chat API の [公開設定] で指定したユーザーは、Chat アプリをインストール、テスト、使用できるようになります。Chat アプリのテストとデバッグを開始するには、Google Chat アプリのインタラクティブ機能をテストするをご覧ください。

Google Cloud CLI を使用して Chat アプリを構成する

Google Cloud コンソールを使用する代わりに、Google Cloud CLI(gcloud CLI)を使用してコマンドラインから Chat アプリの構成を表示および更新できます。たとえば、スクリプトから Chat 用アプリを構成したり、コードとともに保存するファイルに構成を保存したりできます。

gcloud beta workspace-add-ons chat-app-config コマンド グループには、次のコマンドがあります。

  • describe: 構成を表示します。
  • update: Chat アプリを初めて構成するか、構成を変更します。

コマンドは、Google Workspace アドオン API の chatAppConfig リソースを使用します。

始める前に

  1. gcloud CLI をインストールします。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。
  2. ユーザー アカウントで gcloud CLI にログインします。このコマンドはサービス アカウントをサポートしていません。

    gcloud auth login
  3. Chat アプリのクラウド プロジェクトを gcloud CLI のデフォルト プロジェクトとして設定します。コマンドはプロジェクト番号を受け付けないため、プロジェクト ID を使用します。

    gcloud config set project PROJECT_ID

    または、各コマンドに --project フラグを追加します。

  4. Cloud プロジェクトで Google Workspace アドオン API を有効にします。

    gcloud services enable gsuiteaddons.googleapis.com
  5. Cloud プロジェクトに次の Identity and Access Management(IAM)ロールがあることを確認します。

    • Google Workspace アドオン デベロッパー(roles/gsuiteaddons.developer): 構成を表示、更新します。 Google Workspace アドオン読み取り(roles/gsuiteaddons.reader): 構成を表示のみします。これらのロールには、前提条件と認証に記載されている権限が含まれています。
    • Service Usage ユーザー(roles/serviceusage.serviceUsageConsumer)。gcloud CLI は、リクエストの割り当てプロジェクトとして Cloud プロジェクトを使用します。これには serviceusage.services.use 権限が必要です。

    オーナーロールと編集者ロールには、これらの権限がすべて含まれています。Google Cloud コンソールの構成ページへのアクセス権を付与する Chat アプリのオーナーロールと Chat アプリの閲覧者ロールでは不十分です。

構成を表示する

Chat 用アプリの構成を表示するには、describe コマンドを実行します。

gcloud beta workspace-add-ons chat-app-config describe

出力は次のようになります。

avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
  allowlistedTestingPrincipals:
  - user@example.com
  appCommands:
  - command: /help
    commandId: 1
    commandType: SLASH_COMMAND
    description: Show available commands
  connectionConfig:
    httpEndpointConfig:
      commonUrl: https://example.com/chat
  supportsMultiuserSpaces: true
  urlPatterns:
  - hostPattern: example.com
    pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE

Cloud プロジェクトに Chat アプリがまだない場合、コマンドは成功し、構成の name フィールドのみが出力されます。

name: projects/123456789012/chatAppConfig

出力を変更するには、次のいずれかのフラグを追加します。

  • --format=json: 構成を JSON 形式で出力します。
  • --view=basic: インタラクティブ機能の設定(interactiveFeatureConfig)を省略します。
  • --format="value(displayName)": 表示名のみを出力します。クラウド プロジェクトに Chat アプリがまだない場合は、空行を出力します。設定済みの Chat アプリには常に表示名があるため、スクリプトでこのフラグを使用して、Chat アプリが存在するかどうかを確認できます。

構成を更新する

Chat 用アプリを初めて構成する場合、または構成を変更する場合は、update コマンドを実行します。設定は、フラグまたは構成ファイルで指定します。1 つのコマンドで 2 つを組み合わせることはできません。

Cloud プロジェクトで初めてコマンドを実行するときは、少なくとも表示名と説明を指定する必要があります。状態を無効に設定しない限り、コマンドが終了するとすぐに Chat 用アプリが有効になります。テスターとして登録したユーザーは、アプリを検索して使用できるようになります。

フラグを使用する

次の例では、HTTP エンドポイントでイベントを受信する Chat アプリを構成します。

gcloud beta workspace-add-ons chat-app-config update \
    --display-name="Quickstart App" \
    --description="Quickstart app" \
    --avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
    --http-endpoint-url=HTTP_ENDPOINT_URL \
    --supports-multiuser-spaces \
    --add-allowlisted-testing-principals=USER_EMAIL \
    --error-logging-enabled

次のように置き換えます。

  • HTTP_ENDPOINT_URL: Chat からイベント オブジェクトを受信する HTTPS URL。
  • USER_EMAIL: Chat アプリをインストールしてテストできる Google Workspace 組織内のユーザーまたはグループのメールアドレス(独自のメールアドレスなど)。

このコマンドにより、更新された構成が出力されます。

次の表に、Google Cloud コンソールの Chat API の [構成] ページの設定のフラグを示します。各フラグの詳細については、update コマンド リファレンスをご覧ください。

Google Cloud コンソールでの設定 フラグ
アプリ名 --display-name
アバターの URL --avatar-uri: アバターの要件を満たす画像の HTTPS URL。デフォルトのアバターを使用する場合は --clear-avatar-uri。
説明 --description
アプリのステータス --state=active または --state=disabled
マークアップ構文 --markup-syntax=markdown または --markup-syntax=chat
スペースとグループの会話に参加する --supports-multiuser-spaces または --no-supports-multiuser-spaces
接続設定 次のいずれかです。
  • HTTP エンドポイント URL: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic。同じクラウド プロジェクト内のトピックを projects/PROJECT_ID/topics/TOPIC_ID 形式で指定します。
  • Dialogflow: --dialogflow-edition=es、または --dialogflow-edition=cx(--dialogflow-agent はエージェントまたは環境のリソース名(projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID など)に設定)
公開設定 --add-allowlisted-testing-principals、--remove-allowlisted-testing-principals、--clear-allowlisted-testing-principals
エラーを Logging に記録する --error-logging-enabled または --no-error-logging-enabled

コマンド、リンク プレビュー、各トリガーの個別のエンドポイントにはフラグがありません。これらを構成するには、構成ファイルを使用します。

たとえば、他の設定を変更せずに Chat 用アプリをオフにするには、次のコマンドを実行します。再度有効にするには、--state=active を使用します。

gcloud beta workspace-add-ons chat-app-config update --state=disabled

構成ファイルを使用する

構成をファイルに保存する場合、またはフラグのない設定を構成する場合は、YAML ファイルまたは JSON ファイルを update コマンドに渡します。このファイルでは、chatAppConfig リソースのフィールドを使用します。これは、describe コマンドが出力するフィールドと同じです。

  1. 更新する設定を含むファイルを作成します。たとえば、次の内容の chat_app_config.yaml という名前のファイルを作成します。

    displayName: Cymbal Assistant
    description: Helps manage tasks and schedules
    avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
    state: ACTIVE
    errorLoggingEnabled: true
    interactiveFeatureConfig:
      supportsMultiuserSpaces: true
      connectionConfig:
        httpEndpointConfig:
          commonUrl: https://example.com/chat
      appCommands:
      - commandId: 1
        commandType: SLASH_COMMAND
        command: /help
        description: Show available commands
      urlPatterns:
      - hostPattern: example.com
        pathPrefix: tasks/
      allowlistedTestingPrincipals:
      - USER_EMAIL
    

    USER_EMAIL は、Google Workspace 組織内の Chat アプリをインストールしてテストできるユーザーまたはグループのメールアドレスに置き換えます。

  2. --config-file フラグを指定して update コマンドを実行します。

    gcloud beta workspace-add-ons chat-app-config update \
        --config-file=chat_app_config.yaml

Chat 用アプリの現在の構成から開始するには、describe コマンドの出力をファイルに保存します。

gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yaml

次に、ファイルを編集して、変更しないフィールドを削除し、ファイルを update コマンドに渡します。コマンドで更新できない設定がファイルに含まれている場合、コマンドは失敗します。詳細については、制限事項をご覧ください。

update コマンドは、ファイル内の name フィールドを無視します。このコマンドは、gcloud CLI で設定した Cloud プロジェクトを常に更新するため、同じファイルを使用して別の Cloud プロジェクトで Chat アプリを構成できます。

コマンドによる変更の適用方法

  • 指定した設定のみが変更されます。フラグを使用すると、コマンドは渡されたフラグの設定を変更します。構成ファイルを使用すると、ファイル内のフィールドが変更されるため、ファイルに構成全体を含める必要はありません。接続設定は例外です。設定した接続タイプは現在の接続タイプに置き換えられ、設定した Dialogflow エディションは Dialogflow 構成全体に置き換えられます。
  • リストは全体として置き換えられます。ファイルに appCommands、urlPatterns、allowlistedTestingPrincipals のいずれかのフィールドが含まれている場合、ファイル内のリストが現在のリストに置き換えられます。個々のテスターを追加または削除するには、--add-allowlisted-testing-principals フラグと --remove-allowlisted-testing-principals フラグを使用します。
  • 値を空にすると、設定がクリアされます。たとえば、interactiveFeatureConfig の下に urlPatterns: [] を含むファイルは、すべてのリンク プレビュー URL パターンを削除します。
  • 失敗したコマンドは何も変更しません。値が無効な場合、コマンドはエラーを出力し、構成をそのままにします。
  • リクエストにはレート制限があります。この API では、Cloud プロジェクトごと、組織ごとに、1 分あたりの読み取りリクエスト数と更新リクエスト数が制限されます。各 update コマンドは 1 つの更新リクエストを送信します。フラグを使用してテスターを追加または削除すると、コマンドは読み取りリクエストも送信します。複数の設定を変更するには、設定ごとにコマンドを実行するのではなく、1 つのコマンドまたは 1 つのファイルで設定を渡します。

制限事項

  • コマンドは、Google Workspace アドオンとして構築された Chat アプリのみをサポートしています。
  • これらのコマンドは、サービス アカウントまたはサービス アカウントの権限借用をサポートしていません。ユーザー アカウントで gcloud CLI にログインする必要があります。
  • Cloud プロジェクトには 1 つの Chat 用アプリ構成があり、コマンドで削除することはできません。ユーザーが Chat 用アプリを使用できないようにするには、アプリの状態を無効に設定するか、クラウド プロジェクトを削除します。
  • 更新は、公開中の Chat 用アプリに適用されます。コマンドには、ドラフトモードやドライラン モードはありません。
  • Chat 用アプリが Google Workspace Marketplace で公開されているか審査中の場合、コマンドで表示名、アバター、説明、コマンド、リンク プレビューの URL パターンを変更することはできません。
  • これらのコマンドは、chatAppConfig リソースの設定をサポートしています。リソースに含まれていない設定を構成するには、Google Cloud コンソールを使用します。

トラブルシューティング

コマンドが失敗した場合は、次の表でエラー メッセージのテキストを探します。メッセージが INVALID_ARGUMENT などのステータスで始まる場合、Google Workspace アドオン API がリクエストを拒否しています。ステータスの後のテキストに問題の説明が記載されています。

エラー メッセージに次を含む 原因 解決策
Invalid choice: 'chat-app-config' または Invalid choice: 'workspace-add-ons' コマンドに beta が含まれていないか、使用している gcloud CLI のバージョンにコマンドが含まれていません。 コマンドを gcloud beta workspace-add-ons chat-app-config で開始します。エラーが解決しない場合は、gcloud CLI を最新バージョンに更新します。
PROJECT ID プロジェクトがプロジェクト番号に設定されている。 プロジェクトをプロジェクト ID に設定します。
Failed to parse value(s) in protobuf 構成ファイルに、gcloud CLI が認識しないフィールドが含まれています。エラー メッセージにはフィールドの名前が表示されます。 フィールド名を describe コマンドの出力と比較します。フィールドが新しい場合は、gcloud CLI を最新バージョンに更新します。
does not have permission to access projects instance API がリクエストを拒否しました。このメッセージの後に、理由が示されます。例:
  • アカウントに必要な IAM ロールがありません。テキストに Caller does not have required permission to use project が含まれている場合、Service Usage コンシューマー ロールがありません。
  • Google Workspace アドオン API が Cloud プロジェクトで有効になっていません。
  • サービス アカウントでログインした。
始める前にの要件を確認します。
INVALID_ARGUMENT 値が無効です。たとえば、表示名は 3 ~ 25 文字、説明は 1 ~ 40 文字にする必要があります。メッセージに not found or deleted が含まれている場合、プロジェクト ID が正しくありません。 エラー メッセージに記載されている値を修正し、コマンドを再度実行します。
FAILED_PRECONDITION Chat 用アプリがリクエストを許可していない。たとえば、Google Workspace アドオンとして構築されていない場合や、Google Workspace Marketplace で公開されていて設定を変更できない場合です。 エラー メッセージに記載されている手順に沿って対応します。Google Workspace アドオンではない Chat アプリを構成するには、Google Cloud コンソールを使用するか、変換します。
RESOURCE_EXHAUSTED または 429 API が、クラウド プロジェクトまたは組織に対して短時間に多数のリクエストを受信しました。 1 分ほど待ってからコマンドを再度実行します。

Google Workspace アドオン API を使用して Chat アプリを構成する

Google Cloud コンソールで Chat アプリを手動で構成する代わりに、Google Workspace add-ons API の chatAppConfig リソースを使用して、Google Workspace アドオンとして構築された Chat アプリの構成をプログラムで読み取り、更新できます。

chatAppConfig は、各クラウド プロジェクトに常に存在するシングルトン リソースです。構成を初めて保存する前に、リソースには空の構成が含まれています(これは、最初の保存前にリソースを読み取った場合に GetChatAppConfig が返す構成でもあります)。リソースはすでに存在するため、別途作成する必要はありません。UpdateChatAppConfig を使用して、初期構成の保存と既存の構成の更新の両方を行います。

前提条件と認証

GetChatAppConfig または UpdateChatAppConfig を呼び出す前に、次の前提条件を満たす必要があります。

  1. Cloud プロジェクトで Google Workspace アドオン API(gsuiteaddons.googleapis.com)を有効にします。必要に応じて、Google Cloud コンソールで Chat 用アプリの構成を表示または更新する場合や、Chat API を呼び出す場合は、Google Chat API(chat.googleapis.com)を有効にできます。
  2. https://www.googleapis.com/auth/cloud-platform スコープを含む OAuth 2.0 認証情報を使用して、人間のユーザーとして認証します。chatAppConfig メソッドでは、サービス アカウント認証はサポートされていません。
  3. 認証されたユーザーに、ターゲット クラウド プロジェクトで必要な Identity and Access Management(IAM)権限があることを確認します。
    • gsuiteaddons.chatAppConfigs.get と chat.bots.get。構成(GetChatAppConfig)を読み取ります。
    • gsuiteaddons.chatAppConfigs.update、chat.bots.update、chat.bots.get。構成(UpdateChatAppConfig)を更新します。
  4. クライアント ライブラリを使用する場合は、使用する言語の Google Workspace アドオン API クライアント ライブラリの最新バージョンをインストールします。クライアント ライブラリのリストについては、Google Workspace アドオン API リファレンスをご覧ください。

Chat 用アプリの構成を更新する

Chat アプリを初めて構成する場合、または既存の構成を更新する場合は、Cloud プロジェクトのシングルトン chatAppConfig リソースに PATCH リクエスト(UpdateChatAppConfig)を送信します。

  • chatAppConfig が空のクラウド プロジェクトを最初に保存する場合は、displayName(3 ~ 25 文字)と description(1 ~ 40 文字)が必要です。最初の保存時に interactiveFeatureConfig を省略すると、Chat アプリは非インタラクティブとして構成されます。
  • 以降の更新では、オプションの updateMask クエリ パラメータを使用して、更新するカンマ区切りのフィールドを指定します(または、updateMask を省略して、指定されたすべてのフィールドを更新します)。繰り返しフィールド(appCommands、urlPatterns、allowlistedTestingPrincipals)を更新すると、リスト全体が置き換えられます。
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

リクエスト URL、ヘッダー、本文の次の部分を置き換えます。

  • PROJECT_NUMBER: Chat アプリをホストするクラウド プロジェクトの数値プロジェクト番号。
  • ACCESS_TOKEN: https://www.googleapis.com/auth/cloud-platform スコープで認可されたユーザー OAuth 2.0 アクセス トークン。
  • USER_EMAIL: Chat アプリのテスト用に許可リストに登録する Google Workspace 組織のメールアドレスまたは Google グループ(独自のメールアドレスなど)。
  • リクエスト本文の構成フィールドの例(displayName、description、avatarUri、interactiveFeatureConfig など。エンドポイント構成、コマンド、リンク プレビューの URL パターン、テスト プリンシパルを含む)を、Chat アプリの値に置き換えます。サポートされているすべてのフィールドとエンドポイント オプションの詳細については、projects.chatAppConfig REST リファレンスと projects.chatAppConfig.patch をご覧ください。

Chat 用アプリの構成を取得する

Cloud プロジェクトの現在の Chat 用アプリの構成を読み取るには、GetChatAppConfig を呼び出します。オプションの view クエリ パラメータ(ChatAppConfigView)を渡すことができます。

  • BASIC(デフォルト): interactiveFeatureConfig を含まない基本的なメタデータを返します。
  • FULL: interactiveFeatureConfig を含むすべての構成フィールドを返します。

Chat 用アプリの構成がクラウド プロジェクトにまだ保存されていない場合、このメソッドは空の ChatAppConfig オブジェクトを返します。

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

使用量上限

chatAppConfig メソッドにはプロジェクトごとの割り当てがあります。割り当てを超過すると、リクエストは失敗し、429: Too many requests HTTP ステータス コードが返されます。割り当て上限については、Google Workspace アドオン API の使用量上限をご覧ください。

エラーのトラブルシューティングを行う

chatAppConfig リクエストが失敗した場合は、エラー レスポンスの HTTP ステータス コードと message フィールドを確認します。次の表に、一般的なエラー、その原因、解決方法を示します。

HTTP ステータス コード 一般的な原因 解決策
400: Bad Request(INVALID_ARGUMENT)
  • updateMask に、存在しないフィールドまたは更新できないフィールドが含まれています。
  • フィールドの値が指定されていないか、無効です。たとえば、interactiveFeatureConfig には connectionConfig が含まれていません。
message フィールドで無効なフィールドを確認し、リクエストを修正します。サポートされているフィールドと値については、projects.chatAppConfig リファレンスをご覧ください。
400: Bad Request(FAILED_PRECONDITION)
  • Chat アプリが Google Workspace アドオンとしてビルドされていない。
  • Chat 用アプリが Google Workspace Marketplace で公開されているため、このフィールドは変更できません。
  • 新しい値は、既存の Chat 用アプリの構成と互換性がありません。
  • Chat アプリを Google Workspace アドオンに変換するか、Google Cloud コンソールで構成します。
  • message フィールドの手順に沿って、公開されているリスティングを更新します。
  • message フィールドで競合する設定を確認し、同じリクエストで両方の設定を更新するか、既存の設定を先に変更してください。
403: Forbidden(PERMISSION_DENIED)
  • 認証されたユーザーに、クラウド プロジェクトに必要な IAM 権限がありません。
  • リクエストは、ユーザー アカウントではなくサービス アカウントで認証されます。
  • 前提条件と認証に記載されている権限をユーザーに付与します。
  • https://www.googleapis.com/auth/cloud-platform スコープを使用して人間のユーザーとして認証します。
404: Not Found(NOT_FOUND) リソース名の Cloud プロジェクトが存在しないか、認証されたユーザーがアクセスできません。 リソース名が projects/PROJECT_NUMBER/chatAppConfig 形式の正しいプロジェクト番号を使用していること、およびユーザーがクラウド プロジェクトにアクセスできることを確認します。
429: Too Many Requests(RESOURCE_EXHAUSTED) プロジェクトごとの割り当てを超過している。 しばらく待ってから、リクエストを再試行します。上限については、使用量上限をご覧ください。

既存の Google Workspace アドオンに関する考慮事項

Chat 用アプリは、他の Google Workspace アプリケーションを拡張する Google Workspace アドオンとは異なる構成が必要です。アドオンが他の Google Workspace アプリケーションを拡張する場合は、Chat アプリを構成する際の次の要件を考慮してください。

  • 個人ユーザーと Google Workspace 管理者の両方が、Marketplace からアドオンをインストールできる必要があります。これらのインストール設定は、Marketplace SDK で構成します。
  • Chat 用アプリは、マニフェストの addons.common オブジェクトで他の Google Workspace アプリケーション用に構成した名前とロゴを使用しません。
  • Google Workspace Marketplace に公開されているアドオンの場合、Google Chat API の構成設定の変更の下書きを保存することはできません。Chat API の構成設定を更新して保存すると、更新された Chat アプリは既存のすべてのユーザーがすぐに利用できるようになります。Marketplace のリスティングを更新するには、変更を送信する前に下書きを作成します。
  • Apps Script を使用してアドオンを構築した場合:
    • アドオン構成の残りの部分で使用するのと同じ Apps Script デプロイ ID を使用する必要があります。
    • Apps Script エディタを使用して、Chat にテストデプロイをインストールすることはできません。代わりに、Chat UI から直接インストールする必要があります。
  • HTTP サービスを使用してアドオンを構築した場合は、Google Workspace アドオン API を使用して作成する projects.deployments マニフェストで、Chat アプリの構成の詳細を省略します。Google Workspace Marketplace SDK で指定した HTTP デプロイは、他の Google Workspace アプリケーションにのみ使用されます。代わりに、Google Cloud コンソール、gcloud CLI、または Google Workspace アドオン API の chatAppConfig リソースを使用して、Chat アプリを構成します。

他のユーザーに Chat API の構成権限を付与する

Chat 用アプリのオーナーまたは Chat 用アプリの閲覧者の Google Cloud Identity Access Management(IAM)ロールを付与することで、特定のユーザーに Chat 用アプリの構成ページへのアクセス権を付与できます。これらのロールを持つユーザーは、[API とサービス] ダッシュボードを使用して Chat 用アプリの構成ページに移動することはできませんが、次のように Chat 用アプリのホスト クラウド プロジェクトの Google Cloud コンソールに移動して構成ページにアクセスできます。

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

ここで、PROJECT_ID は、Chat アプリをホストする Google Cloud プロジェクトのプロジェクト ID です。

アドオンではない Chat 用アプリ: Google Chat API を構成する

Google Workspace アドオンではない Chat アプリを管理している場合、構成では、イベントごとのトリガーではなく、すべてのインタラクション イベントに単一のエンドポイントを使用します。

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

    [Chat API の構成] ページに移動

  2. [インタラクティブ機能] で、[インタラクティブ機能を有効にする] をオンにします。

  3. [この Chat アプリを Google Workspace アドオンとしてビルドする] をオフにします。確認を求めるダイアログが表示されます。ダイアログで [無効にする] をクリックします。

  4. [機能] で、必要に応じて [アプリのホームをサポートする] または [スペースとグループの会話に参加する] を選択します。

  5. [接続設定] で、Chat アプリの単一のエンドポイント(HTTP エンドポイント URL、Apps Script デプロイ ID、Cloud Pub/Sub トピック名、Dialogflow)を指定します。

  6. オプションの [コマンド]、[スターター プロンプト]、[リンク プレビュー]、[公開設定]、[ログ] を構成し、[保存] をクリックします。

アドオンではない Chat アプリを、Google Chat を拡張する Google Workspace アドオンにアップグレードするには、Google Chat アプリを Google Workspace アドオンに変換するをご覧ください。