Conversational Analytics API は、Identity and Access Management（IAM）を使用して、データ エージェントの作成、管理、操作へのアクセスを制御します。IAM では、プリンシパルにロールを割り当てることで、プリンシパル（ユーザー、グループ、サービス アカウントなど）に権限を付与します。各ロールは、プリンシパルが実行できるアクションを決定する 1 つ以上の権限をまとめたものです。
このページでは、Conversational Analytics API の事前定義 IAM ロールについて説明します。これらの IAM ロールは、Conversational Analytics API が有効になっているプロジェクトの Google Cloud コンソールで割り当てることができます。詳細な手順については、 Google Cloud コンソールを使用してロールを付与するをご覧ください。IAM ロールを付与するで説明されているように、Google Cloud CLI を使用してロールを付与することもできます。
始める前に
Conversational Analytics API の IAM ロールの割り当てに必要な権限を取得するには、Conversational Analytics API が有効になっているプロジェクトに対する Project IAM 管理者 （roles/resourcemanager.projectIamAdmin）IAM ロールを付与するように管理者へ依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
Conversational Analytics API の IAM ロールの概要
Conversational Analytics API には、事前定義された IAM ロールのセットが用意されています。これらのロールを使用すると、エージェントの作成と編集、エージェントの共有と管理、エージェントの表示とチャット、ステートレス チャットモードでの API の使用などのタスクに対する権限を付与できます。
Conversational Analytics API の事前定義 IAM ロールは、geminidataanalytics サービスの一部です。これらのロールの技術名は roles/geminidataanalytics.ROLE_NAME というパターンに従います。 Google Cloud コンソールで、[Gemini Data Analytics] サービスでフィルタすると、これらのロールを確認できます。
Conversational Analytics API の IAM ロールは、プロジェクト レベルで割り当てることができます。
一般的なユーザータスクに必要なロール
プリンシパルに割り当てるロールを決定するには、次の一般的なユーザータスクを検討してください。
- 新しいデータ エージェントを作成する
- プロジェクト内で新しいデータ エージェントを作成するユーザーに データ エージェント作成者のロールを割り当てます。
- エージェントの権限を管理する
- エージェントに対する最高レベルの制御（権限の管理、エージェントの共有または削除など）を必要とするユーザーに、データ エージェント オーナーのロールを割り当てます。ユーザーがエージェントを作成すると、システムはそのユーザーに特定のユーザーのこのロールを自動的に付与します。
- エージェント構成を編集する
- エージェントの構成（コンテキストやデータソース マッピングなど）を変更するユーザーに、データ エージェント編集者ロールを割り当てます。これらのユーザーには、エージェントを共有または削除する権限がありません。
- エージェントとチャットする
- 主に質問をして回答を受け取ることでエージェントとやり取りするユーザーまたはアプリケーションに、データ エージェント ユーザーのロールを割り当てます。
- エージェント構成を表示する
- エージェント構成を表示するための読み取り専用アクセス権が必要なユーザーに、データ エージェント閲覧者ロールを割り当てます。
- インライン コンテキストを使用してチャットする
- ステートレス モードで API を操作するアプリケーションまたはユーザーに Data Agent Stateless User ロールを割り当てます。このモードでは、ユーザーが各リクエスト内で会話のすべてのコンテキストを提供します。
事前定義ロールと各ロールに含まれる権限のリストについては、会話分析 API の事前定義ロールをご覧ください。
Conversational Analytics API の事前定義ロール
次の表に、Conversational Analytics API の事前定義ロールを示します。必要な権限が事前定義ロールで提供されていない場合は、カスタムのロールを独自に作成することもできます。
| ロール | 権限 |
|---|---|
|
Gemini データ分析データ エージェント作成者（ 特定のプロジェクトで新しいデータ エージェント リソースを作成する権限をプリンシパルに付与します。プリンシパルがエージェントを作成すると、システムは、そのプリンシパルに特定のエージェントの |
geminidataanalytics.dataAgents.create
|
|
Gemini データ分析データ エージェント オーナー（ プリンシパルに、エージェントの共有や削除など、プロジェクト内の任意のエージェントのライフサイクルに対するフル コントロールを付与します。このロールは、エージェントの共有を管理できる信頼できるプリンシパル用です。このロールは、 このロールを持つプリンシパルは、エージェントの共有と削除を行うことができます。 |
|
|
Gemini データ分析データ エージェント編集者（ 既存のエージェント構成の変更と管理を行う権限を付与します。このロールは、 |
|
|
Gemini データ分析データ エージェント ユーザー（ プリンシパルにアクセス権が付与されている特定のエージェントとチャットする権限を付与します。このロールは、 |
|
|
Gemini データ分析データ エージェント閲覧者（ プリンシパルにエージェント構成の一覧表示と閲覧の読み取り専用権限を付与します。このロールでは、エージェントとのチャットはできません。 |
|
|
Gemini データ分析データ エージェント ステートレス ユーザー（ プリンシパルに、ステートレス モードで Chat API を呼び出す権限を付与します。ステートレス チャットでは、コンテキストは作成時にエージェント構成に明示的に保存されるのではなく、リクエストで直接提供されます。 |
geminidataanalytics.chat
|
IAM ロールを付与する
Conversational Analytics API IAM ロールをプリンシパルに付与するには、 Google Cloud コンソールまたは Google Cloud CLI を使用します。
コンソール
Google Cloud コンソールでプリンシパルにロールを付与する手順は次のとおりです。
Google Cloud コンソールで、[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など）。