IAM による Conversational Analytics API のアクセス制御

Conversational Analytics API は、アクセス制御に Identity and Access Management（IAM）を使用します。これにより、データ エージェントを共有し、データ エージェントの作成、管理、操作を行う権限を持つユーザーを制御できます。このページでは、これらの権限を付与するためにプリンシパル（ユーザー、グループ、サービス アカウントなど）に割り当てることができる IAM 事前定義ロールについて説明します。

IAM に加えて、組織のポリシーを使用して、Conversational Analytics API リソースに制約を設定し、組織、フォルダ、プロジェクト レベルでの使用方法を制御できます。

始める前に

Conversational Analytics API の IAM ロールの割り当てに必要な権限を取得するには、Conversational Analytics API が有効になっているプロジェクトに対する Project IAM 管理者 （roles/resourcemanager.projectIamAdmin）IAM ロールを付与するように管理者へ依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

注: IAM の基本ロールに、Conversational Analytics API IAM ロールを割り当てる権限が含まれている場合もあります。本番環境では基本ロールを付与しないようにしてください。このロールは、開発環境またはテスト環境で付与してください。

Conversational Analytics API の IAM ロールの概要

Conversational Analytics API の IAM 事前定義ロールにより、データ エージェントの作成、管理、操作を行うことができるユーザーをきめ細かく制御できます。このセクションでは、IAM ロールを割り当ててデータ エージェントを共有する方法と、他の一般的なユーザータスクに必要な IAM ロールについて説明します。

エージェント共有の仕組み

プロジェクト レベルでロールを付与して、プロジェクト内のすべてのエージェントに権限を付与できます。特定のエージェントへのアクセスを制御するには、エージェントのオーナー（Gemini Data Analytics Data Agent Owner ロールを持つプリンシパル）が、そのエージェントの IAM ポリシーをプログラムで変更できます。

重要: Conversational Analytics API の IAM ロールは、基盤となるデータソースではなく、エージェントとその構成へのアクセスを制御します。ユーザーがエージェントとやり取りすると、API はそのユーザーの認証情報を使用して、接続されたデータソースにクエリを送信します。そのため、エージェントとチャットするには、ユーザーに次の権限が必要です。

• エージェントにアクセスするための適切な Conversational Analytics API IAM ロール
• クエリ対象のデータにアクセスするためのデータソース（BigQuery、Looker、データベース データソースなど）の十分な権限

次の図は、エージェントのオーナーが特定のエージェントへのアクセスを管理する方法を示しています。

このシナリオでは、Gemini データ分析 Data Agent Creatorロールを持つシニア データ アナリストがエージェントを作成します。ユーザーがエージェントを作成すると、そのエージェントに対する Gemini データ分析 Data Agent Owner ロールが自動的に付与されます。エージェントの所有者であるシニア データ アナリストは、IAM ポリシーを設定してエージェントへのアクセスを管理し、チームメンバーに次のロールを付与します。

• Gemini Data Analytics Data Agent Editor: エージェント オーナーがジュニア データ アナリストにこのロールを付与します。このロールを使用すると、ジュニア アナリストはエージェントの構成を編集し、エージェントとチャットできます。
• Gemini データ分析データ エージェント ユーザー: エージェントの構成を編集する必要がないチームメンバーに、エージェント オーナーがこのロールを付与します。このロールにより、チームメンバーはエージェントとチャットできます。

一般的なユーザータスクに必要なロール

割り当てるロールを決定するには、次の一般的なユーザータスクについて検討してください。

すべての Gemini データ分析リソースを管理する

プロジェクト内のすべてのデータ エージェントとロケーションに対する完全なアクセス権が必要な管理者には、Gemini データ分析管理者ロールを割り当てます。

すべての Gemini データ分析リソースを表示してチャットする

プロジェクト内のすべてのエージェント構成に対する読み取り専用アクセス権と、それらとチャットする権限が必要なユーザーには、Gemini データ分析閲覧者ロールを割り当てます。

新しいデータ エージェントを作成する

プロジェクト内で新しいデータ エージェントを作成するユーザーには Gemini データ分析 Data Agent Creator ロールを割り当てます。

エージェントを共有する

エージェントの権限を管理して、エージェントを他のプリンシパルと共有する必要があるユーザーには、Gemini データ分析データ エージェント オーナーのロールを割り当てます。

エージェントの権限を管理する

エージェントの権限を管理してエージェントを他のユーザーと共有する必要があるユーザー、またはエージェントの削除など、エージェントに対する最高レベルの制御を必要とするユーザーには、Gemini データ分析データ エージェント オーナーのロールを割り当てます。ユーザーがエージェントを作成すると、システムはそのユーザーに特定のユーザーのこのロールを自動的に付与します。

エージェント構成を編集する

エージェントの構成（コンテキストやデータソース マッピングなど）を変更するユーザーには、Gemini データ分析データ エージェント編集者ロールを割り当てます。これらのユーザーには、エージェントを共有または削除する権限がありません。

エージェントとチャットする

主に質問をして回答を受け取ることでエージェントとやり取りするユーザーまたはアプリケーションには、Gemini データ分析データ エージェント ユーザーのロールを割り当てます。

エージェント構成を表示する

エージェント構成を表示するための読み取り専用アクセス権が必要なユーザーには、Gemini データ分析データ エージェント閲覧者ロールを割り当てます。

インライン コンテキストを使用してチャットする

ステートレス モードで API を操作するユーザーまたはアプリケーションには Gemini データ分析ステートレス チャット ユーザー ロールを割り当てます。このモードでは、ユーザーが各リクエスト内で会話のすべてのコンテキストを提供します。

自然言語を使用してデータをクエリする

QueryData メソッド（AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL）を使用してデータベース データソースをクエリするユーザーまたはアプリケーションに、Gemini Data Analytics Query Data User ロールを割り当てます。代わりにデータ エージェントとチャットするには、データ エージェントのロールを割り当てます。

Conversational Analytics API の事前定義ロール

注: ユーザーにデータ エージェントへのアクセス権を付与しても、他のユーザーが開始した会話を表示することはできません。たとえば、エージェントの会話を一覧表示すると、現在のユーザーが作成した会話のみが返されます。

次の表に、Conversational Analytics API の事前定義ロールと、一般的な付与レベル（プロジェクト レベルまたは特定のデータ エージェント）を示します。必要な権限が事前定義ロールで提供されていない場合は、カスタムのロールを独自に作成することもできます。

エージェント リソースレベルで dataAgentOwner、dataAgentEditor、dataAgentUser、dataAgentViewer のロールを付与します。権限の付与範囲が広くなりすぎないように、プロジェクト レベルのアクセス権付与は管理者に限定してください。プロジェクト レベルのアクセス権付与では、プロジェクト内のすべてのエージェントに権限が付与されるためです。

事前定義ロールには、次のカテゴリの権限が含まれています。

• geminidataanalytics.dataAgents.*: データ エージェント リソースへのアクセスを制御します。これには、データ エージェントの作成、表示、更新、削除、チャット、エージェントの IAM ポリシーの管理が含まれます。
• geminidataanalytics.operations.*: 長時間実行のバックグラウンド オペレーションの検査、一覧表示、キャンセル、削除へのアクセスを制御します。
• geminidataanalytics.locations.*: 利用可能な Google Cloud ロケーションの表示と一覧表示、ステートレス チャットやデータ エンジニアリング エージェントなどのロケーション レベルの機能の呼び出しに対するアクセスを制御します。

ロール	一般的な付与レベル	権限
Gemini データ分析管理者（roles/geminidataanalytics.admin） プロジェクト内のすべての Gemini データ分析リソースに対する完全な管理者権限を付与します。プリンシパルがデータ エージェントの作成、編集、共有、削除、エージェントとのチャット、バックグラウンド オペレーションの管理を行えるようにします。	プロジェクト	geminidataanalytics.* geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.create geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.setIamPolicy geminidataanalytics.dataAgents.update geminidataanalytics.locations.chat geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.locations.useDataEngineeringAgent geminidataanalytics.operations.cancel geminidataanalytics.operations.delete geminidataanalytics.operations.get geminidataanalytics.operations.list resourcemanager.projects.get resourcemanager.projects.list
Gemini データ分析閲覧者（roles/geminidataanalytics.viewer） プロジェクト内のエージェント構成を表示し、任意のエージェントとチャットする権限を付与します。エージェントの作成、編集、共有、削除を行う権限は付与されません。	プロジェクト	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.locations.* geminidataanalytics.locations.chat geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.locations.useDataEngineeringAgent geminidataanalytics.operations.get geminidataanalytics.operations.list resourcemanager.projects.get resourcemanager.projects.list
Gemini データ分析データ エージェント作成者（roles/geminidataanalytics.dataAgentCreator） 特定のプロジェクトで新しいデータ エージェント リソースを作成する権限をプリンシパルに付与します。プリンシパルがエージェントを作成すると、システムは、そのプリンシパルに特定のエージェントの dataAgentOwner ロールを自動的に付与します。	プロジェクト	geminidataanalytics.dataAgents.create geminidataanalytics.locations.chat geminidataanalytics.operations.get
Gemini データ分析 Data Agent Owner（roles/geminidataanalytics.dataAgentOwner） プリンシパルに、エージェントの共有や削除など、プロジェクト内の任意のエージェントのライフサイクルに対するフル コントロールを付与します。このロールは、エージェントの共有を管理できる信頼できるプリンシパル用です。このロールは、dataAgentEditor、dataAgentUser、dataAgentViewer の各ロールからすべての権限を継承します。 このロールを持つプリンシパルは、エージェントの共有と削除を行うことができます。	エージェントまたはプロジェクト	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.setIamPolicy geminidataanalytics.dataAgents.update geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.operations.* geminidataanalytics.operations.cancel geminidataanalytics.operations.delete geminidataanalytics.operations.get geminidataanalytics.operations.list
Gemini データ分析 Data Agent Editor（roles/geminidataanalytics.dataAgentEditor） 既存のエージェント構成の変更と管理を行う権限を付与します。このロールは、dataAgentUser ロールと dataAgentViewer ロールからすべての権限を継承します。	エージェントまたはプロジェクト	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.update geminidataanalytics.operations.get
Gemini データ分析 Data Agent User（roles/geminidataanalytics.dataAgentUser） プリンシパルにアクセス権が付与されている特定のエージェントとチャットする権限を付与します。このロールは、dataAgentViewer ロールのすべての権限を継承します。	エージェントまたはプロジェクト	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list
Gemini データ分析 Data Agent Viewer（roles/geminidataanalytics.dataAgentViewer） プリンシパルにエージェント構成の一覧表示と閲覧の読み取り専用権限を付与します。このロールでは、エージェントとのチャットはできません。	エージェントまたはプロジェクト	geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list
Gemini データ分析ステートレス チャット ユーザー（roles/geminidataanalytics.dataAgentStatelessUser） プリンシパルに、ステートレス モードで Chat API を呼び出す権限を付与します。ステートレス チャットでは、コンテキストは作成時にエージェント構成に明示的に保存されるのではなく、リクエストで直接提供されます。	プロジェクト	geminidataanalytics.locations.chat geminidataanalytics.locations.useDataEngineeringAgent
Gemini データ分析クエリデータ ユーザー（roles/geminidataanalytics.queryDataUser） QueryData メソッド（AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL）を使用して、自然言語でデータベース データソースをクエリする権限をプリンシパルに付与します。このロールでは、データ エージェントへのアクセスは許可されません。	プロジェクト	geminidataanalytics.locations.queryData

IAM ロールを付与する

Conversational Analytics API の IAM ロールは、プロジェクト レベルまたは特定のエージェントに付与できます。プロジェクト レベルでロールを付与すると、プリンシパルにはそのプロジェクト内のすべてのエージェントに対して同じ権限が付与されますが、特定のエージェントにポリシーを設定すると、よりきめ細かい制御が可能になります。

Conversational Analytics API の IAM 事前定義ロールは、geminidataanalytics サービスの一部です。これらのロールの技術名は roles/geminidataanalytics.ROLE_NAME というパターンに従います。 Google Cloud コンソールで、[Gemini Data Analytics] サービスでフィルタすると、これらのロールを確認できます。

プロジェクト内のすべてのエージェントにロールを付与する

Google Cloud コンソールまたは Google Cloud CLI を使用して、プロジェクト全体のロールを付与します。

コンソール

Google Cloud コンソールでプリンシパルにロールを付与する手順は次のとおりです。

1. Google Cloud コンソールで、[IAM] ページに移動します。

   IAM に移動

2. [アクセス権を付与] をクリックします。

3. [新しいプリンシパル] フィールドに、ユーザー、グループ、サービス アカウントのメールアドレスを入力します。

4. [ロールを選択] メニューで、[Gemini Data Analytics] でフィルタして、Conversational Analytics API で使用可能な IAM ロールを表示します。

5. Gemini Data Analytics Data Agent Userなどの適切なロールを選択します。

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

gcloud

gcloud CLI を使用してロールを付与するには、次の操作を行います。

1. Google Cloud にログインして、プロジェクトを設定します。

gcloud auth login
gcloud config set project PROJECT_ID

1. 必要に応じて、プロジェクトに付与できる Conversational Analytics API IAM ロールを一覧表示するには、次のように gcloud iam list-grantable-roles コマンドを使用します。

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/PROJECT_ID --filter "geminidataanalytics"

1. gcloud projects add-iam-policy-binding コマンドを使用して、プリンシパルにロールを付与します。

• ユーザーにロールを付与するには、次のコマンドを使用します。

gcloud projects add-iam-policy-binding PROJECT_ID --member='user:USER_EMAIL' --role='roles/GDA_GRANTABLE_ROLE'

• サービス アカウントにロールを割り当てるには、次のコマンドを使用します。

gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:SERVICE_ACCOUNT_EMAIL' --role='roles/GDA_GRANTABLE_ROLE'

前の手順で、サンプル値を次のように置き換えます。

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• USER_EMAIL: ユーザーのメールアドレス（例: [e-mail]）。
• SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス（例: [e-mail]）。
• GDA_GRANTABLE_ROLE: 付与する特定の Conversational Analytics API IAM ロール（geminidataanalytics.dataAgentCreator など）。

特定のエージェントにロールを付与する

特定のデータ エージェントのアクセスを管理するには、そのエージェントの許可ポリシーをプログラムで変更する必要があります。このプロセスは、現在のポリシーを読み取り、変更して書き戻すという標準の read-modify-write パターンに従います。

重要: setIamPolicy メソッドは、エージェントの既存のポリシーをオーバーライドします。新しいロールを付与するときに既存の権限を保持するには、まず getIAMPolicy を呼び出して既存のポリシーを取得し、そのポリシーを変更してから、setIamPolicy の呼び出しで更新されたポリシー オブジェクトを渡す必要があります。

次のサンプルは、データ エージェントの IAM ポリシーを取得および設定するためのリクエスト本文を示しています。

HTTP

エージェントの既存のポリシーを取得するには、次のリクエスト本文を使用して :getIamPolicy エンドポイントに POST リクエストを送信します。

{
  "resource": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
}

エージェントのポリシーを設定するには、次のリクエスト本文を使用して :setIamPolicy エンドポイントに POST リクエストを送信します。

{
  "policy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "user:EMAIL"
        ]
      }
    ]
  }
}

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: データ エージェントが保存されているロケーション（global、us、us-east4 など）。詳細については、データ所在地をご覧ください。
• AGENT_ID: ポリシーを取得または設定するデータ エージェントの ID。
• ROLE: 付与するロール（roles/geminidataanalytics.dataAgentUser など）。
• EMAIL: ユーザーのメールアドレス（例: [e-mail]）。

完全な例については、データ エージェントの IAM ポリシーを取得するとデータ エージェントの IAM ポリシーを設定するをご覧ください。

Python SDK

エージェントの既存のポリシーを取得するには、次のサンプル リクエストのように get_iam_policy メソッドを使用します。

resource = "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

エージェントのポリシーを設定するには、次のリクエスト例のように set_iam_policy メソッドを使用します。

resource = "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="ROLE",
            members=["user:EMAIL"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: データ エージェントが保存されているロケーション（global、us、us-east4 など）。詳細については、データ所在地をご覧ください。
• AGENT_ID: ポリシーを取得または設定するデータ エージェントの ID。
• ROLE: 付与するロール（roles/geminidataanalytics.dataAgentUser など）。
• EMAIL: ユーザーのメールアドレス（例: [e-mail]）。

完全な例については、データ エージェントの IAM ポリシーを取得するとデータ エージェントの IAM ポリシーを設定するをご覧ください。

次のステップ

• Conversational Analytics API について詳細を確認する。
• データソースと API に対して認証する方法を確認する。