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

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

アプリは、それだけでも他のシステムと連携し、コンパニオンアプリケーションでアカウントの接続、データアクセスの承認、追加データの表示、ユーザー設定を行うことがよくあります。

アプリの構成をリクエストする

アプリは、通常の返信の一部として URL を表示するだけでなく、メッセージへのレスポンスとして、構成 URL を非公開でユーザーに提示することもできます。

構成 URL を返す

リクエストを完了する際にアプリで直接完了できない追加構成が必要な場合は、次の形式のレスポンスを返します。

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

これにより、Google Chat は、認証、認可、構成のために指定された構成 URL にアクセスするためのリンクを含むプライベートプロンプトをユーザーに提示します。request-config レスポンスは、通常のレスポンスメッセージと相互に排他的です。テキスト、カード、その他の属性は無視されます。

ユーザーに構成 URL の入力を求めるアプリ。

アプリに対するすべてのイベントには、configCompleteRedirectUrl パラメータも含まれます。この URL は、プロセスの完了時に使用するように構成 URL でエンコードする必要があります。この URL へのリダイレクトは、構成リクエストが完了したことを Google Chat に通知します。

アプリがフローを開始するタイミングは、受信した特定のメッセージによって異なります。@app help のようなメッセージに応答する場合、アプリは追加の構成を必要とせずにメッセージで応答する必要があります。

元のメッセージで提供された configCompleteRedirectUrl にユーザーがリダイレクトされると、Google Chat は次の手順を実行します。

開始ユーザーに表示されたプロンプトを消去します
元のメッセージを一般公開に変換して、スペースの他のメンバーに表示できるようにする
元のメッセージを同じアプリに 2 回ディスパッチする

configCompleteRedirectUrl にアクセスしても、単一のユーザーメッセージにのみ影響します。ユーザーがアプリに複数回メッセージを送信しようとして、複数のプロンプトを受け取った場合、特定のプロンプトをクリックして認証 / 構成プロセスを完了すると、その特定のメッセージ / プロンプトにのみ影響します。その他のメッセージやプロンプトは変更されません。

この方法でイベントが再ディスパッチされるとき、通常は元のイベントと同じにする必要がありますが、イベントが異なる場合があります。たとえば、メッセージにアプリ A とアプリ B の両方が含まれている場合、アプリ A がアプリ B で認証する前に標準メッセージを返すと、ユーザーはメッセージテキストを編集できます。この場合、ユーザーが認証を完了すると、編集されたメッセージテキストがアプリ B に送信されます。

アプリ内メッセージでユーザーを識別する

アプリに送信される各メッセージには、アプリを操作しているユーザーの ID が含まれています。

次の JSON フラグメントの例は、アプリへのメッセージに含まれるユーザー ID の予想される形式を示しています。

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

ユーザーのプライマリ ID として users.name プロパティの値を使用します。この値は、各ユーザーの安定した一意の ID です。

Google Chat を使用していない Chat ユーザーを特定する

API の OAuth 認証をリクエストする場合など、アプリはユーザー ID を維持しながら Google Chat 以外の URL にリンクする必要があります。このような場合にユーザーを識別する最良の方法は、Google ログインを使用してデスティネーションアプリを保護することです。

ログイン時に発行された ID トークンを使用して、ユーザー ID を取得します。sub クレームにはユーザーの一意の ID が含まれ、Google Chat の ID に関連付けることができます。

これら 2 つの ID は完全に同じではありませんが、簡単に強制変換できます。sub クレームの値を Google Chat ユーザー名に強制変換するには、値の前に "users/" を付けます。たとえば、123 のクレーム値は、Chat アプリへのメッセージに含まれるユーザー名 users/123 と同じです。

例

MyProfile アプリは、REQUEST_CONFIG レスポンスを使用してアプリの構成を開始し、Google ログインレスポンスの ID トークンを使用してユーザーを識別する方法を示しています。