Chat アプリを他のサービスやツールに接続する

このページでは、Google Chat アプリを Google Chat の外部のサービスやツールに接続する方法について説明します。Chat 用アプリは単体でも強力ですが、他のシステムと連携して動作することが多く、アカウントの接続、データアクセスの承認、追加データの表示、ユーザー設定の構成を行うコンパニオン アプリケーションが必要です。

サードパーティ サービスまたは OAuth フローを使用してユーザーを認証するために、Chat 用アプリは次の手順を実行します。

1. 認証または構成が必要なタイミングを検出する。
2. ユーザーにログインまたはサービスの構成を求める基本的な認証カードを返します。
3. 完了 URI にリダイレクトして、ユーザーが認証を完了した後、Google Chat が元のインタラクションを自動的に再試行するようにします。

前提条件

HTTP

ユーザー インタラクションを受け取って応答する Google Chat 用アプリ。作成するには、HTTP クイックスタートを完了します。

注: このガイドのコードサンプルは、Node.js 用の Google Cloud Run 関数として実行するように記述されています。

Apps Script

ユーザー インタラクションを受け取って応答する Google Chat 用アプリ。作成するには、Apps Script クイックスタートを完了します。

承認が必要であることを検出する

Chat 用アプリを操作する際、ユーザーは次のようなさまざまな理由で、保護されたリソースにアクセスする権限がない場合があります。

• サードパーティ サービスに接続するためのアクセス トークンがまだ生成されていないか、有効期限が切れています。
• アクセス トークンがリクエストされたリソースをカバーしていません。
• アクセス トークンにリクエストに必要なスコープが含まれていない。

Chat 用アプリは、ユーザーがログインしてサービスへのアクセスを承認できるように、これらのケースを検出する必要があります。

Apps Script でビルドしている場合は、OAuth2 for Google Apps Script ライブラリ（または OAuth1 バージョン）を使用できます。このライブラリの hasAccess 関数は、ユーザーがサービスへのアクセスを承認したかどうかを確認します。または、UrlFetchApp.fetch リクエストを使用する場合は、muteHttpExceptions パラメータを true に設定して、返された HttpResponse オブジェクトのレスポンス コードとコンテンツを検査できます。

基本的な認証カードでユーザーにプロンプトを表示する

Chat 用アプリで認証または構成が必要であることが検出された場合は、AuthorizationError レスポンスを返して、ユーザーに非公開の基本認証カードを表示します。

注: カスタム認証カードは Chat ではサポートされていません。Chat ユーザーにログインを求めるには、Chat 用アプリが基本的な認証カードを返す必要があります。

次の画像は、Google の基本的な認証カードの例を示しています。

図 1: Example Account の基本認証プロンプト。このプロンプトには、Chat 用アプリが追加情報を表示するため、アカウントへのアクセス許可を必要としていることが示されています。

基本的な認証カードをユーザーに表示するには、AuthorizationError オブジェクトを返します。

HTTP

次の JSON レスポンスを返します。

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

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

• AUTHORIZATION_URL: 認証、認可、構成を処理するウェブアプリの HTTPS URL。
• RESOURCE_DISPLAY_NAME: 保護されたリソースまたはサービスの表示名。この名前は、認証プロンプトでユーザーに表示されます。たとえば、RESOURCE_DISPLAY_NAME が Example Account の場合、アプリが Example Account にアクセスするには承認が必要であることを示すメッセージが表示されます。

構成リクエストを完了する

Chat では、ユーザーが承認プロセスを完了すると、Chat が手動更新なしで元のインタラクションを自動的に再試行します。トリガーが [メッセージ]、[スペースに追加]、[アプリ コマンド] の場合、Chat は自動再試行をサポートします。

これらのトリガーの場合、Chat 用アプリはイベント ペイロードで完了リダイレクト URI（configCompleteRedirectUri / completeRedirectUri）を受け取ります。

• メッセージ: chat.messagePayload.configCompleteRedirectUri
• スペースに追加しました: chat.addedToSpacePayload.configCompleteRedirectUri
• アプリコマンド: chat.appCommandPayload.configCompleteRedirectUri

このリダイレクト URI を <var>AUTHORIZATION_URL</var> でエンコードし、認可フローの完了後にユーザーのブラウザをこの URI にリダイレクトする必要があります。この URL にリダイレクトすると、Google Chat に認証リクエストまたは構成リクエストが完了したことが通知されます。

ユーザーが元のイベント ペイロードで指定された完了リダイレクト URI に正常にリダイレクトされると、Google Chat は次の手順を実行します。

1. 開始ユーザーに表示されるプライベート認証プロンプトを消去します。
2. 元のメッセージを公開に変換し、スペースの他のメンバーに表示できるようにします。
3. 元のイベント オブジェクトを Chat 用アプリに 2 回送信します。

完了リダイレクト URI にリダイレクトしない場合でも、ユーザーは認証フローを完了できますが、Google Chat は以前の実行を自動的に再試行しません。ユーザーは Chat 用アプリを手動で再度呼び出す必要があります。

完了リダイレクト URI にアクセスしても、影響を受けるのは 1 回のユーザー操作のみです。ユーザーが Chat 用アプリに複数回メッセージを送信し、複数のプロンプトを受け取った場合、1 つのプロンプトの認証と構成プロセスを完了すると、その特定のやり取りのみが再試行されます。

Chat の外部で Chat ユーザーを認証する

Chat の外部の URL（OAuth ウェブコールバックなど）にリンクする場合は、外部ウェブ セッションと Chat のユーザー ID を関連付ける必要があります。宛先のウェブアプリを Google ログインで保護することをおすすめします。

ログイン時に発行されたID トークンを使用して、ユーザー ID を取得します。sub クレームにはユーザーの固有の Google ID が含まれており、Google Chat のユーザー リソース名（chat.user.name）と関連付けることができます。

注意: アサートされたユーザー ID を受け入れる前に、必ずトークンの完全性を検証してください。

sub クレームを Google Chat の users/{user} リソース名に関連付けるには、sub クレーム値の先頭に users/ を追加します。たとえば、sub クレーム値 123 は、Chat 用アプリに送信されるイベント オブジェクトの users/123 に対応します。

コードサンプル

次のコードサンプルは、Chat 用アプリが基本認証カードを使用してオフライン OAuth2 認証情報をリクエストし、データベースに保存して、完了 URI にリダイレクトし、ユーザー認証を使用して API 呼び出しを行う方法を示しています。

Node.js

GitHub で表示

Python

GitHub で表示

Java

GitHub で表示

Apps Script

GitHub で表示

関連トピック

• ユーザー インタラクションを受け取って応答する
• Google Chat アプリと Google Chat API リクエストの認証と認可
• Google Workspace アドオンをサードパーティ サービスに接続する

アドオンではない Chat 用アプリ: Chat 用アプリを他のサービスやツールに接続する

Google Workspace アドオンではない Chat 用アプリを管理している場合、Chat 用アプリはタイプ REQUEST_CONFIG の actionResponse を使用して構成をリクエストし、トップレベルの Event オブジェクトから configCompleteRedirectUrl を読み取ります。

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

アドオンではない Chat 用アプリのユーザーから構成をリクエストする

アドオンではない Chat 用アプリでは、次の形式で構成 URL をユーザーに返します。

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

これにより、Google Chat はユーザーにプライベート プロンプトを表示します。ここで、CONFIGURATION_URL は、追加の認証、認可、構成を行うためにユーザーがアクセスするリンクです。REQUEST_CONFIG レスポンスは通常のレスポンス メッセージと相互に排他的です。テキスト、カード、その他の属性は無視されます。

アドオンではない Chat 用アプリで構成リクエストを完了する

アドオンではない Chat 用アプリが受け取るすべての MESSAGE、ADDED_TO_SPACE、APP_COMMAND のインタラクション Event には、トップレベルのフィールド configCompleteRedirectUrl が含まれます。この URL を構成 URL でエンコードし、完了時にユーザーをリダイレクトして、Google Chat がプロンプトを消去し、元のメッセージを公開に変換して、元のインタラクション イベントを Chat 用アプリに再送信するようにします。

実装例については、GitHub の Node.js 接続アプリのサンプルと Python MyProfile 認証アプリのサンプルをご覧ください。