Google Chat ユーザーを特定して指定する

このページでは、Google Chat アプリとデベロッパーが Chat ユーザーを特定して指定する方法について説明します。

次のいずれかを行うには、Chat 用アプリまたはデベロッパーがユーザーを指定する必要があります。

Chat でユーザーを識別する仕組み

Google Chat API は、Chat を使用するユーザーとアプリごとに User リソースを生成します。User リソースには次のフィールドが含まれています。

  • name: リソース名。users/{user} の形式で指定します。{user} は一意で安定した識別子を表します。users/app は、呼び出し元の Chat 用アプリのエイリアスとして使用できます。
  • displayName: 出力のみ。ユーザーの表示名。
  • avatarUrl: 出力のみ。ユーザーのアバター画像の URL。
  • email: 出力のみ。ユーザーのメール アドレスです。
  • domainId: ユーザーの Google Workspace ドメインの固有識別子。
  • type: ユーザーのタイプ。ユーザーが Chat 用アプリ（BOT）か、ユーザー（HUMAN）かを示します。
  • isAnonymous: 出力のみ。true の場合、ユーザーが削除されたか、プロフィールが表示されないことを示します。

ユーザー プロフィールの詳細と可視性ルール

ユーザー認証を使用して Messages API と Memberships API を呼び出すと、Google Chat API は User リソースにプロフィールの詳細を入力します。この API は、内部ユーザー（Google Workspace 組織内）と外部ユーザー（外部組織または個人の Google アカウント内）の両方に対して displayName、email、avatarUrl を入力します。

API がユーザー プロファイルを移入する場所の例は次のとおりです。

  • Message の sender。
  • メッセージ annotations 内のユーザー（ユーザー @mentions など）。
  • Membership リソース内の member。

プライバシーと公開設定のルール

ユーザーのプライバシーを保護するため、Google Chat API はユーザーのプロフィール詳細を入力するかどうかを判断する際に、特定の可視性ルールを適用します。

  • 入力済みのプロフィール: ユーザーがスペースへの招待を承諾している（スペースのメンバーである）場合、または呼び出し元のユーザーとの間に以前の親近感（ダイレクト メッセージのやり取りの履歴など）がある場合、API はプロフィールの詳細（displayName、email、avatarUrl が存在し、isAnonymous が false）を入力します。
  • 匿名プロファイル: メンバーではなく、通話しているユーザーとの親近感もないユーザーがスペースで言及された場合、そのユーザーのプロファイルは匿名のままになります。匿名ユーザーの場合、isAnonymous は true になり、displayName、email、avatarUrl などの詳細は省略されます。ただし、アプリ認証を使用して行われた API リクエストの場合、displayName フィールドには常に値が入力されます。

次の JSON の例は、API レスポンスまたはインタラクション イベントで返される、プロファイルの詳細が入力された User リソースを示しています。

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

次の JSON の例は、ユーザー プロファイルの詳細が呼び出し元に表示されない匿名の User リソースを示しています。

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

Google Chat API への呼び出しでユーザーを指定する

ユーザーを指定するには、{user} 値に次の値を使用します。

  • Google Workspace 組織のユーザーの場合は、次のいずれかの方法を使用します。

    • Chat API の User リソースの name（users/123456789 など）。
    • People API の Person リソースの名前の {person_id}。ここで、resourceName は people/{person_id} です。たとえば、Chat API の users/123456789 は、People API の people/123456789 と同じ人物を表します。
    • Directory API の User リソースの id（例: Chat API の users/123456789）は、Directory API の users/123456789 と同じ人物を表します。
    • ユーザー認証を使用して行われた API リクエストの場合、ユーザーのメールアドレスをエイリアスとして使用します（例: users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com）。

  • 外部の Google Workspace 組織のユーザー、または Google アカウントを使用するユーザーの場合は、次のいずれかを使用します。

    • メール エイリアス（users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com や users/EMAIL_USERNAME@gmail.com など）。
    • 以前の API 呼び出しまたはインタラクション イベントから取得した User リソースの正規 name（users/12345678901234567890 など）。

API レスポンスまたはインタラクション イベントからユーザーを特定する

API 呼び出しまたは受信イベントから返されたユーザーを特定する方法はいくつかあります。

ユーザー認証を使用すると、Google Chat API は内部ユーザーと外部ユーザーの両方のプロフィールを入力するため、デベロッパーは Directory API を呼び出してメンバーとメッセージ送信者の名前やメールアドレスを解決する必要はありません。