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

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

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

始める前に

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

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

Conversational Analytics API の IAM ロールの概要

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

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

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

エージェントオーナーが、他のユーザーにデータエージェント編集者ロールとデータエージェントユーザーロールを付与します。

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

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

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

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

新しいデータエージェントを作成する: プロジェクト内で新しいデータエージェントを作成するユーザーに Gemini Data Analytics データエージェント作成者のロールを割り当てます。
エージェントを共有する: エージェントの権限を管理してエージェントを他のプリンシパルと共有する必要があるユーザーに、Gemini Data Analytics データエージェントオーナーのロールを割り当てます。
エージェントの権限を管理する: エージェントの権限を管理してエージェントを他のユーザーと共有する必要があるユーザー、またはエージェントに対する最高レベルの制御（エージェントの削除など）を必要とするユーザーに、Gemini Data Analytics データエージェントオーナーのロールを割り当てます。ユーザーがエージェントを作成すると、システムはそのユーザーに特定のユーザーのこのロールを自動的に付与します。
エージェント構成を編集する: エージェントの構成（コンテキストやデータソースマッピングなど）を変更するユーザーに、Gemini Data Analytics データエージェント編集者ロールを割り当てます。これらのユーザーには、エージェントを共有または削除する権限がありません。
エージェントとチャットする: 主に質問をして回答を受け取ることでエージェントとやり取りするユーザーまたはアプリケーションに、Gemini データ分析データエージェントユーザーのロールを割り当てます。
エージェント構成を表示する: エージェント構成を表示するための読み取り専用アクセス権が必要なユーザーに、Gemini Data Analytics データエージェント閲覧者ロールを割り当てます。
インラインコンテキストを使用してチャットする: ステートレスモードで API を操作するユーザーまたはアプリケーションに Gemini Data Analytics Stateless Chat User ロールを割り当てます。このモードでは、ユーザーが各リクエスト内で会話のすべてのコンテキストを提供します。

Conversational Analytics API の事前定義ロール

次の表に、Conversational Analytics API の事前定義ロールを示します。必要な権限が事前定義ロールで提供されていない場合は、カスタムのロールを独自に作成することもできます。

ロール	権限
Gemini データ分析データエージェント作成者（`roles/geminidataanalytics.dataAgentCreator`）特定のプロジェクトで新しいデータエージェントリソースを作成する権限をプリンシパルに付与します。プリンシパルがエージェントを作成すると、システムは、そのプリンシパルに特定のエージェントの `dataAgentOwner` ロールを自動的に付与します。	`geminidataanalytics.dataAgents.create`
Gemini データ分析データエージェントオーナー（`roles/geminidataanalytics.dataAgentOwner`）プリンシパルに、エージェントの共有や削除など、プロジェクト内の任意のエージェントのライフサイクルに対するフルコントロールを付与します。このロールは、エージェントの共有を管理できる信頼できるプリンシパル用です。このロールは、`dataAgentEditor`、`dataAgentUser`、`dataAgentViewer` の各ロールからすべての権限を継承します。このロールを持つプリンシパルは、エージェントの共有と削除を行うことができます。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Gemini データ分析データエージェント編集者（`roles/geminidataanalytics.dataAgentEditor`）既存のエージェント構成の変更と管理を行う権限を付与します。このロールは、`dataAgentUser` ロールと `dataAgentViewer` ロールからすべての権限を継承します。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Gemini データ分析データエージェントユーザー（`roles/geminidataanalytics.dataAgentUser`）プリンシパルにアクセス権が付与されている特定のエージェントとチャットする権限を付与します。このロールは、`dataAgentViewer` ロールのすべての権限を継承します。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Gemini データ分析データエージェント閲覧者（`roles/geminidataanalytics.dataAgentViewer`）プリンシパルにエージェント構成の一覧表示と閲覧の読み取り専用権限を付与します。このロールでは、エージェントとのチャットはできません。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Gemini データ分析ステートレスチャットユーザー（`roles/geminidataanalytics.dataAgentStatelessUser`）プリンシパルに、ステートレスモードで Chat API を呼び出す権限を付与します。ステートレスチャットでは、コンテキストは作成時にエージェント構成に明示的に保存されるのではなく、リクエストで直接提供されます。	`geminidataanalytics.chat`

IAM ロールを付与する

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

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

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

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

Console

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

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

IAM に移動
[アクセス権を付与] をクリックします。
[新しいプリンシパル] フィールドに、ユーザー、グループ、サービスアカウントのメールアドレスを入力します。
[ロールを選択] メニューで、[Gemini Data Analytics] でフィルタして、Conversational Analytics API で使用可能な IAM ロールを表示します。
Gemini Data Analytics データエージェントユーザーなどの適切なロールを選択します。
[保存] をクリックします。

gcloud

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

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

gcloud auth login
gcloud config set project project_id

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

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

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: ユーザーのメールアドレス（例: test-user@gmail.com）。
service_account_email: サービスアカウントのメールアドレス（例: test-proj@example.domain.com）。
gda_grantable_role: 付与する特定の Conversational Analytics API IAM ロール（geminidataanalytics.dataAgentCreator など）。

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

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

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

HTTP

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

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

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

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

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
AGENT_ID: ポリシーを取得または設定するデータエージェントの ID。
ROLE: 付与するロール（roles/geminidataanalytics.dataAgentUser など）。
EMAIL: ユーザーのメールアドレス（例: test-user@gmail.com）。

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

Python SDK

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

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

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

resource = "projects/PROJECT_ID/locations/global/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
)