Halaman ini diterjemahkan oleh Cloud Translation API.

Kontrol akses Conversational Analytics API dengan IAM

Conversational Analytics API menggunakan Identity and Access Management (IAM) untuk kontrol akses, yang memungkinkan Anda membagikan agen data dan mengontrol siapa yang memiliki izin untuk membuat, mengelola, dan berinteraksi dengannya. Halaman ini menjelaskan peran IAM bawaan yang dapat Anda tetapkan ke akun utama (seperti pengguna, grup, dan akun layanan) untuk memberikan izin ini.

Sebelum memulai

Untuk mendapatkan izin yang diperlukan untuk menetapkan peran IAM Conversational Analytics API, minta administrator Anda untuk memberi Anda peran IAM Project IAM Admin (roles/resourcemanager.projectIamAdmin) di project tempat Conversational Analytics API diaktifkan. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Ringkasan peran IAM Conversational Analytics API

Peran IAM yang telah ditentukan sebelumnya untuk Conversational Analytics API memberikan kontrol terperinci atas siapa yang dapat membuat, mengelola, dan berinteraksi dengan agen data. Bagian ini menjelaskan cara membagikan agen data dengan menetapkan peran IAM dan menjelaskan peran IAM yang diperlukan untuk tugas pengguna umum lainnya.

Anda dapat memberikan peran di tingkat project untuk memberikan izin bagi semua agen dalam project. Untuk mengontrol akses ke agen tertentu, pemilik agen (pokok dengan peran Pemilik Agen Data Analytics Gemini) dapat mengubah kebijakan IAM agen tersebut secara terprogram.

Diagram berikut menunjukkan cara pemilik agen dapat mengelola akses ke agen tertentu:

Pemilik agen memberikan peran Editor Agen Data dan Pengguna Agen Data kepada pengguna lain.

Dalam skenario ini, Analis Data Senior dengan peran Pembuat Agen Data Analisis Data Gemini membuat agen. Saat pengguna membuat agen, mereka akan otomatis diberi peran Pemilik Agen Data Analisis Data Gemini untuk agen tersebut. Sebagai pemilik agen, Analis Data Senior mengelola akses ke agen dengan menetapkan kebijakan IAM-nya dan memberikan peran berikut kepada anggota tim:

Editor Agen Data Analisis Data Gemini: Pemilik agen memberikan peran ini kepada Analis Data Junior. Peran ini memungkinkan analis junior mengedit konfigurasi agen dan melakukan percakapan dengan agen.
Pengguna Agen Data Analisis Data Gemini: Pemilik agen memberikan peran ini kepada anggota tim yang tidak perlu dapat mengedit konfigurasi agen. Peran ini memungkinkan anggota tim tersebut melakukan chat dengan agen.

Peran yang diperlukan untuk tugas pengguna umum

Untuk membantu Anda memutuskan peran mana yang akan ditetapkan, pertimbangkan tugas pengguna umum berikut:

Membuat agen data baru: Tetapkan peran Pembuat Agen Data Analisis Data Gemini kepada pengguna yang bertanggung jawab untuk membuat agen data baru dalam project.
Membagikan agen: Tetapkan peran Pemilik Agen Data Analytics Gemini kepada pengguna yang perlu membagikan agen kepada prinsipal lain dengan mengelola izin agen.
Mengelola izin agen: Tetapkan peran Pemilik Agen Data Analytics Gemini kepada pengguna yang perlu membagikan agen kepada pengguna lain dengan mengelola izin agen, atau yang memerlukan tingkat kontrol tertinggi atas agen, termasuk kemampuan untuk menghapus agen. Saat pengguna membuat agen, sistem akan otomatis memberikan peran ini kepada pengguna tersebut untuk agen tertentu.
Mengedit konfigurasi agen: Tetapkan peran Editor Agen Data Analytics Gemini kepada pengguna yang mengubah konfigurasi agen, seperti pemetaan sumber data atau konteksnya. Pengguna ini tidak memiliki izin untuk membagikan atau menghapus agen.
Chat dengan agen: Tetapkan peran Pengguna Agen Data Analytics Gemini kepada pengguna atau aplikasi yang terutama berinteraksi dengan agen dengan mengajukan pertanyaan dan menerima respons.
Melihat konfigurasi agen: Tetapkan peran Pelihat Agen Data Analisis Data Gemini kepada pengguna yang memerlukan akses hanya baca untuk melihat konfigurasi agen.
Memulai percakapan dengan menggunakan konteks inline: Tetapkan peran Pengguna Chat Stateless Gemini Data Analytics kepada pengguna atau aplikasi yang berinteraksi dengan API dalam mode stateless, di mana pengguna memberikan semua konteks untuk percakapan dalam setiap permintaan.

Peran bawaan untuk Conversational Analytics API

Tabel berikut menjelaskan peran standar untuk Conversational Analytics API. Jika peran standar tidak memberikan sekumpulan izin yang Anda inginkan, Anda juga dapat membuat peran khusus sendiri.

Peran	Izin
Pembuat Agen Data Analisis Data Gemini (`roles/geminidataanalytics.dataAgentCreator`) Memberikan izin kepada akun utama untuk membuat resource agen data baru dalam project tertentu. Saat akun utama membuat agen, sistem akan otomatis memberikan peran `dataAgentOwner` kepada akun utama tersebut untuk agen tertentu.	`geminidataanalytics.dataAgents.create`
Gemini Data Analytics Data Agent Owner (`roles/geminidataanalytics.dataAgentOwner`) Memberikan kontrol penuh kepada prinsipal atas siklus proses agen apa pun dalam project, termasuk berbagi dan menghapus agen. Peran ini ditujukan untuk akun utama tepercaya yang dapat mengelola berbagi agen. Peran ini mewarisi semua izin dari peran `dataAgentEditor`, `dataAgentUser`, dan `dataAgentViewer`. Akun utama dengan peran ini dapat membagikan dan menghapus agen.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Editor Agen Data Analisis Data Gemini (`roles/geminidataanalytics.dataAgentEditor`) Memberikan izin untuk mengubah dan mengelola konfigurasi agen yang ada. Peran ini mewarisi semua izin dari peran `dataAgentUser` dan `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Pengguna Agen Data Analisis Data Gemini (`roles/geminidataanalytics.dataAgentUser`) Memberikan izin untuk melakukan chat dengan agen tertentu yang telah diberi akses oleh akun utama. Peran ini mewarisi semua izin dari peran `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Pelihat Agen Data Analisis Data Gemini (`roles/geminidataanalytics.dataAgentViewer`) Memberikan izin hanya baca kepada akun utama untuk mencantumkan dan melihat konfigurasi agen. Peran ini tidak mengizinkan chat dengan agen.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Pengguna Chat Stateless Gemini Data Analytics (`roles/geminidataanalytics.dataAgentStatelessUser`) Memberi izin utama untuk memanggil Chat API dalam mode stateless. Dengan chat stateless, konteks diberikan langsung dalam permintaan, bukan disimpan secara eksplisit dalam konfigurasi agen selama pembuatan.	`geminidataanalytics.chat`

Memberikan peran IAM

Anda dapat memberikan peran IAM Conversational Analytics API di tingkat project atau untuk agen tertentu. Memberikan peran di tingkat project akan memberi akun utama izin yang sama untuk semua agen dalam project tersebut, sementara menetapkan kebijakan pada agen tertentu memberikan kontrol yang lebih terperinci.

Peran IAM bawaan untuk Conversational Analytics API adalah bagian dari layanan geminidataanalytics. Nama teknis untuk peran ini mengikuti pola roles/geminidataanalytics.ROLE_NAME. Di konsol Google Cloud , Anda dapat menemukan peran ini dengan memfilter layanan Gemini Data Analytics.

Memberikan peran untuk semua agen dalam project

Gunakan konsol Google Cloud atau Google Cloud CLI untuk memberikan peran bagi seluruh project.

console

Untuk memberikan peran kepada akun utama di konsol Google Cloud , selesaikan langkah-langkah berikut:

Di konsol Google Cloud , buka halaman IAM.

Buka IAM
Klik Grant access.
Di kolom New principals, masukkan alamat email pengguna, grup, atau akun layanan.
Dari menu Pilih peran, filter Gemini Data Analytics untuk melihat peran IAM yang tersedia untuk Conversational Analytics API.
Pilih peran yang sesuai, seperti Pengguna Agen Data Analisis Data Gemini.
Klik Simpan.

gcloud

Untuk memberikan peran menggunakan gcloud CLI, selesaikan langkah-langkah berikut:

gcloud auth login
gcloud config set project project_id

Jika perlu, untuk mencantumkan peran IAM Conversational Analytics API yang dapat Anda berikan untuk project Anda, gunakan perintah gcloud iam list-grantable-roles sebagai berikut:

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

Berikan peran kepada akun utama menggunakan perintah gcloud projects add-iam-policy-binding.

Untuk memberikan peran kepada pengguna, gunakan perintah berikut:

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

Untuk menetapkan peran ke akun layanan, gunakan perintah berikut:

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

Dalam petunjuk sebelumnya, ganti nilai sampel sebagai berikut:

project_id: ID project Google Cloud Anda.
user_email: Alamat email pengguna, seperti test-user@gmail.com.
service_account_email: Alamat email akun layanan, seperti test-proj@example.domain.com.
gda_grantable_role: Peran IAM Conversational Analytics API tertentu yang ingin Anda berikan, seperti geminidataanalytics.dataAgentCreator.

Memberikan peran untuk agen tertentu

Untuk mengelola akses bagi agen data tertentu, Anda harus mengubah kebijakan izinkan agen tersebut secara terprogram. Proses ini mengikuti pola baca-ubah-tulis standar di mana Anda membaca kebijakan saat ini, mengubahnya, lalu menuliskannya kembali.

Contoh berikut menunjukkan isi permintaan untuk mendapatkan dan menetapkan kebijakan IAM untuk agen data.

HTTP

Untuk mendapatkan kebijakan yang ada untuk agen, kirim permintaan POST ke endpoint :getIamPolicy dengan isi permintaan berikut:

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

Untuk menetapkan kebijakan untuk agen, kirim permintaan POST ke endpoint :setIamPolicy dengan isi permintaan berikut:

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

Ganti kode berikut:

PROJECT_ID: ID project Google Cloud Anda.
AGENT_ID: ID agen data yang akan mendapatkan atau menetapkan kebijakan.
ROLE: Peran yang akan diberikan, seperti roles/geminidataanalytics.dataAgentUser.
EMAIL: Alamat email pengguna, seperti test-user@gmail.com.

Untuk contoh lengkap, lihat Mendapatkan kebijakan IAM untuk agen data dan Menetapkan kebijakan IAM untuk agen data.

Python SDK

Untuk mendapatkan kebijakan yang ada untuk agen, gunakan metode get_iam_policy, seperti dalam contoh permintaan berikut:

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

Untuk menetapkan kebijakan bagi agen, gunakan metode set_iam_policy, seperti dalam contoh permintaan berikut:

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
)