Halaman ini menjelaskan cara melakukan autentikasi terhadap Conversational Analytics API. Dokumen ini juga menjelaskan cara mengonfigurasi koneksi ke data Anda di Looker, BigQuery, Data Studio, dan database (AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL) menggunakan permintaan HTTP langsung atau SDK. API Analisis Percakapan menggunakan metode autentikasiGoogle Cloud standar.
Sebelum memulai
Sebelum dapat melakukan autentikasi terhadap API Analisis Percakapan dan mengonfigurasi koneksi ke data, Anda harus menyelesaikan prasyarat dan mengaktifkan API yang diperlukan untuk project Google Cloud , seperti yang dijelaskan dalam Mengaktifkan API Analisis Percakapan.
Jika Anda berencana menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) untuk melindungi resource Analisis Percakapan API, Anda harus memberikan izin kepada akun layanan API untuk menggunakan kunci Cloud Key Management Service Anda. Untuk mengetahui detailnya, lihat Sebelum memulai dalam dokumentasi CMEK.
Melakukan autentikasi terhadap API Analisis Percakapan
Bagian ini menjelaskan cara melakukan autentikasi terhadap API Analisis Percakapan menggunakan metode HTTP dan Python untuk mendapatkan token otorisasi yang diperlukan. Contoh berikut menggunakan logika endpoint regional berdasarkan lokasi resource. Untuk mengetahui informasi selengkapnya tentang endpoint regional, lihat Residensi data.
HTTP curl
Contoh perintah curl berikut menargetkan metode endpoint API untuk menunjukkan cara mengirim permintaan yang diautentikasi menggunakan token identitas yang dihasilkan oleh Google Cloud CLI:
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD
Ganti nilai contoh sebagai berikut:
- ENDPOINT_URL: URL endpoint layanan yang sesuai dengan lokasi Anda, misalnya,
geminidataanalytics.googleapis.comuntuk lokasi defaultglobal, ataugeminidataanalytics.us.rep.googleapis.comuntuk multi-regionus. - PROJECT_ID: ID project Google Cloud tempat Anda mengaktifkan API yang diperlukan.
LOCATION: Lokasi tempat resource Anda disimpan (misalnya,
globalatauus-east4).METHOD: Metode endpoint target atau jalur resource (misalnya,
dataAgentsuntuk membuat agen, ataudataAgents/AGENT_IDuntuk mendapatkan agen tertentu).
HTTP menggunakan Python
Kode Python contoh berikut menargetkan metode endpoint API untuk menunjukkan cara mendapatkan token akses dan mengirim permintaan HTTP yang diautentikasi. Kode ini secara dinamis membuat URL endpoint berdasarkan jenis lokasi yang ditentukan.
billing_project = 'PROJECT_ID'
location = 'LOCATION'
access_token = !gcloud auth application-default print-access-token
# Set the base URL based on location.
if not location or location == "global":
base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
# Regional endpoints
base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
# Multi-regional endpoints
base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"
url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/METHOD"
headers = {"Authorization": f'Bearer {access_token[0]}'}
Ganti nilai contoh sebagai berikut:
- PROJECT_ID: ID project Google Cloud tempat Anda mengaktifkan API yang diperlukan.
LOCATION: Lokasi tempat resource Anda disimpan (misalnya,
globalatauus-east4).METHOD: Metode endpoint target atau jalur resource. Contoh:
- Untuk membuat agen data, gunakan metode
POSTdan tentukandataAgents. - Untuk menampilkan daftar agen data yang ada, gunakan metode
GETdan tentukandataAgents.
- Untuk membuat agen data, gunakan metode
Python SDK
Contoh kode Python berikut menunjukkan cara mengautentikasi Akun Google Anda untuk mengakses Analisis Percakapan API dalam Colaboratory:
from google.colab import auth
auth.authenticate_user()
Menghubungkan ke Looker dengan Conversational Analytics API
Untuk mengetahui peran dan izin yang diperlukan, opsi otorisasi, dan kode contoh untuk terhubung ke Looker Explore, lihat Terhubung ke Looker. Untuk instance yang hanya menggunakan koneksi pribadi, lihat Menghubungkan ke instance Looker (Google Cloud core) yang menggunakan koneksi pribadi.
Menghubungkan ke BigQuery dengan Conversational Analytics API
Bagian ini menjelaskan cara mengonfigurasi Analisis Percakapan API untuk terhubung ke BigQuery menggunakan permintaan HTTP langsung atau SDK. Conversational Analytics API mendukung koneksi ke tabel BigQuery, dan ke grafik dengan BigQuery Graph.
Dengan Analisis Percakapan API, tidak ada batasan ketat terkait jumlah Tabel BigQuery yang dapat Anda hubungkan. Namun, menghubungkan ke banyak tabel dapat mengurangi akurasi atau menyebabkan Anda melebihi batas token input Gemini. Kueri yang memerlukan gabungan kompleks di beberapa tabel juga dapat menghasilkan respons yang kurang akurat.
Menghubungkan ke tabel
Untuk terhubung ke satu atau beberapa tabel BigQuery, berikan project ID, ID set data, dan ID tabel untuk setiap tabel.
Contoh berikut menunjukkan cara terhubung ke satu atau beberapa tabel BigQuery menggunakan permintaan HTTP atau Python SDK.
HTTP menggunakan Python
Kode contoh berikut menentukan koneksi ke beberapa tabel BigQuery:
bigquery_data_sources = {
"bq": {
"tableReferences": [
{
"projectId": "PROJECT_ID",
"datasetId": "DATASET_ID",
"tableId": "TABLE_ID"
},
{
"projectId": "PROJECT_ID_2",
"datasetId": "DATASET_ID_2",
"tableId": "TABLE_ID_2"
},
{
"projectId": "PROJECT_ID_3",
"datasetId": "DATASET_ID_3",
"tableId": "TABLE_ID_3"
},
]
}
}
Ganti nilai contoh sebagai berikut:
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: ID project Google Cloud yang berisi set data dan tabel BigQuery yang ingin Anda hubungkan. Untuk terhubung ke set data publik, tentukan
bigquery-public-data. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: ID set data BigQuery (atau
catalog.namespaceuntuk tabel katalog runtime Lakehouse). - TABLE_ID, TABLE_ID_2, TABLE_ID_3: ID tabel BigQuery (atau nama tabel untuk tabel katalog runtime Lakehouse).
Python SDK
Anda dapat menggunakan auth SDK dari Colaboratory untuk melakukan autentikasi menggunakan kredensial Akun Google Anda dan mengizinkan klien Colab mengakses BigQuery menggunakan kredensial Anda.
Contoh kode Python berikut menentukan koneksi ke beberapa tabel BigQuery dan menunjukkan cara melakukan autentikasi menggunakan kredensial Akun Google Anda dalam Colaboratory untuk mengizinkan permintaan.
from google.colab import auth
auth.authenticate_user()
# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "PROJECT_ID"
bigquery_table_reference.dataset_id = "DATASET_ID"
bigquery_table_reference.table_id = "TABLE_ID"
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "PROJECT_ID_2"
bigquery_table_reference_2.dataset_id = "DATASET_ID_2"
bigquery_table_reference_2.table_id = "TABLE_ID_2"
bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "PROJECT_ID_3"
bigquery_table_reference_3.dataset_id = "DATASET_ID_3"
bigquery_table_reference_3.table_id = "TABLE_ID_3"
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2, bigquery_table_reference_3]
Ganti nilai contoh sebagai berikut:
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: ID project Google Cloud yang berisi set data dan tabel BigQuery yang ingin Anda hubungkan. Untuk terhubung ke set data publik, tentukan
bigquery-public-data. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: ID set data BigQuery (atau
catalog.namespaceuntuk tabel katalog runtime Lakehouse). Sebagai contoh,san_francisco - TABLE_ID, TABLE_ID_2, TABLE_ID_3: ID tabel BigQuery (atau nama tabel untuk tabel katalog runtime Lakehouse). Contoh,
street_trees.
Menghubungkan ke BigQuery Graph
Contoh berikut menunjukkan cara terhubung ke satu atau beberapa grafik dengan BigQuery Graph menggunakan permintaan HTTP atau Python SDK.
Untuk mengetahui informasi tentang persyaratan edisi BigQuery dan batasan kueri grafik, lihat Menghubungkan ke BigQuery Graph.
HTTP menggunakan Python
Kode contoh berikut menentukan koneksi ke grafik BigQuery:
bigquery_data_sources = {
"bq": {
"propertyGraphReferences": [
{
"projectId": "GRAPH_PROJECT_ID",
"datasetId": "GRAPH_DATASET_ID",
"propertyGraphId": "GRAPH_ID"
}
]
}
}
Ganti nilai contoh sebagai berikut:
- GRAPH_PROJECT_ID: ID project Google Cloud yang berisi grafik BigQuery.
- GRAPH_DATASET_ID: ID set data BigQuery yang berisi grafik.
- GRAPH_ID: ID grafik BigQuery.
Python SDK
Anda dapat menggunakan auth SDK dari Colaboratory untuk melakukan autentikasi ke BigQuery menggunakan kredensial pengguna Anda yang diautentikasi ke Colaboratory.
Contoh kode Python berikut menentukan koneksi ke grafik BigQuery:
from google.colab import auth
auth.authenticate_user()
# BigQuery graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]
Ganti nilai contoh sebagai berikut:
- GRAPH_PROJECT_ID: ID project Google Cloud yang berisi grafik BigQuery.
- GRAPH_DATASET_ID: ID set data BigQuery yang berisi grafik.
- GRAPH_ID: ID grafik BigQuery.
Menghubungkan ke Data Studio dengan API Analisis Percakapan
Untuk terhubung ke Looker Studio dengan Conversational Analytics API, Anda harus mengaktifkan Looker Studio API terlebih dahulu. Bagian ini menjelaskan cara mengonfigurasi Analisis Percakapan API untuk terhubung ke Data Studio menggunakan permintaan HTTP langsung atau SDK.
Untuk menggunakan Analisis Percakapan API dengan Data Studio Pro, langganan Pro Anda harus berada di luar perimeter VPC-SC.
Mengaktifkan Data Studio API
Untuk mengaktifkan Data Studio API, ikuti petunjuk di Mengaktifkan API.
Melakukan Autentikasi ke Data Studio
Untuk terhubung ke Data Studio dengan Analisis Percakapan API, Anda harus memastikan pengguna atau akun layanan yang diautentikasi diberi otorisasi untuk mengakses sumber data Data Studio, lalu memberikan ID sumber data.
HTTP menggunakan Python
Setelah mengaktifkan Data Studio API, Anda dapat terhubung ke Data Studio dengan membuat permintaan curl HTTP menggunakan Python. Kode contoh berikut menunjukkan cara menentukan detail sumber data Data Studio dalam isi permintaan HTTP Anda.
Anda dapat terhubung ke Data Studio dengan membuat permintaan HTTP langsung. Contoh panggilan HTTP ditampilkan dalam blok kode berikut.
looker_studio_data_source = {
"studio":{
"studio_references":
[
{
"datasource_id": "DATASOURCE_ID"
}
]
}
}
Ganti your_studio_datasource_id dengan ID sumber data sebenarnya dari sumber data Data Studio yang ingin Anda gunakan.
Python SDK
Setelah mengaktifkan Data Studio API, Anda dapat terhubung ke Data Studio menggunakan SDK. Contoh kode Python berikut menunjukkan cara menentukan detail sumber data Data Studio Anda.
datasource_id = "DATASOURCE_ID"
# Looker Studio
studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.studio.studio_references = [studio_references]
Ganti STUDIO-DATASOURCE-ID dengan ID sumber data sebenarnya dari sumber data Data Studio yang ingin Anda gunakan.
Terhubung ke database dengan API Analisis Percakapan
Untuk terhubung ke database dengan Conversational Analytics API, Anda harus memiliki izin IAM yang diperlukan untuk instance database Anda. Secara opsional, jika Anda menggunakan set konteks (Pratinjau) dengan sumber data database, untuk membuat, mengupload, atau mengelola set konteks, Anda juga harus mengaktifkan Knowledge Catalog API dan memberikan peran Dataplex Catalog Editor (roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) pada project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks.
Menghubungkan ke AlloyDB untuk PostgreSQL
Pengguna atau akun layanan harus memiliki peran alloydb.databaseUser. Untuk mengetahui informasi selengkapnya, lihat Autentikasi database IAM AlloyDB.
HTTP menggunakan Python
Kode contoh berikut menunjukkan cara menentukan detail sumber data AlloyDB dalam isi permintaan HTTP Anda.
alloydb_data_sources = {
"alloydb": {
"database_reference": {
"project_id": alloydb_project_id,
"region": location,
"cluster_id": alloydb_cluster_id,
"instance_id": alloydb_instance_id,
"database_id": alloydb_database_id,
"table_ids":["table1", "table2", "table3"]
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/alloydb_project_id/locations/{location}/contextSets/your_context_set_id"
# }
}
}
Ganti nilai contoh sebagai berikut:
- your_table_id: Daftar ID tabel yang dipisahkan koma. Jika tidak ditetapkan, semua tabel dalam database akan dipertimbangkan.
- your_context_set_id: Opsional: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi AlloyDB.
Python SDK
Contoh kode Python berikut menunjukkan cara menentukan detail sumber data AlloyDB menggunakan Python SDK.
# AlloyDB data source
alloydb_table_ids = ["your_table_id_1", "your_table_id_2"]
alloydb_context_set_id = "your_context_set_id"
alloydb_reference = geminidataanalytics.AlloyDbReference()
alloydb_reference.database_reference.table_id = alloydb_table_ids
alloydb_reference_database_reference.project_id = billing_project
alloydb_reference_database_reference.region = "us-central1" # Example region
alloydb_reference_database_reference.cluster_id = alloydb_cluster_id
alloydb_reference_database_reference.instance_id = alloydb_instance_id
alloydb_reference_database_reference.database_id = alloydb_database_id
# optional set agent context reference
# alloydb_ref_1.agent_context_reference.context_set_id = f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
alloydb_reference.agent_context_reference.context_set_id = alloydb_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.alloydb.alloydb_reference = alloydb_reference
Ganti nilai contoh sebagai berikut:
- your_table_id_1: ID tabel pertama di instance AlloyDB Anda.
- your_table_id_2: ID tabel kedua di instance AlloyDB Anda.
- your_context_set_id: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi AlloyDB.
Menghubungkan ke GoogleSQL untuk Spanner
Pengguna atau akun layanan harus memiliki peran spanner.databaseReader. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.
HTTP menggunakan Python
Kode contoh berikut menunjukkan cara menentukan detail sumber data GoogleSQL untuk Spanner dalam isi permintaan HTTP Anda.
spanner_data_sources = {
"spanner_reference": {
"database_reference": {
"project_id": spanner_project_id,
"region": location,
"engine": engine,
"instance_id": spanner_instance_id,
"database_id": spanner_database_id,
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
# }
}
}
Ganti nilai contoh sebagai berikut:
- your_table_id_1: ID tabel pertama di instance GoogleSQL untuk Spanner Anda.
- your_table_id_2: ID tabel kedua di instance GoogleSQL untuk Spanner Anda.
- your_context_set_id: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi Spanner.
Python SDK
Contoh kode Python berikut menunjukkan cara menentukan detail sumber data GoogleSQL untuk Spanner menggunakan Python SDK.
# Spanner data source
spanner_table_ids = ["your_table_id_1", "your_table_id_2"]
spanner_context_set_id = "your_context_set_id"
spanner_reference = geminidataanalytics.SpannerReference()
spanner_reference.database_reference.table_id = spanner_table_ids
spanner_reference.agent_context_reference.context_set_id = spanner_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.spanner.spanner_reference = spanner_reference
Ganti nilai contoh sebagai berikut:
- your_table_id_1: ID tabel pertama di instance GoogleSQL untuk Spanner Anda.
- your_table_id_2: ID tabel kedua di instance GoogleSQL untuk Spanner Anda.
- your_context_set_id: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi Spanner.
Menghubungkan ke Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL
Bagian berikut memberikan petunjuk untuk terhubung ke Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL. Pengguna atau akun layanan harus memiliki peran cloudsql.studioUser dan cloudsql.instanceUser. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi database IAM untuk Cloud SQL untuk MySQL dan Mengelola pengguna dengan autentikasi database IAM untuk Cloud SQL untuk PostgreSQL.
HTTP menggunakan Python
Kode contoh berikut menunjukkan cara menentukan detail sumber data Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL dalam isi permintaan HTTP Anda.
cloudsql_data_source = {
"cloudSqlReference": {
"databaseReference": {
"engine": MYSQL,
"project_id": cloud-db-nl2sql,
"region": us-central1,
"instance_id": nl2sql-birdsql-mysql,
"database_id": financial
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/cloud-db-nl2sql/locations/us-central1/contextSets/bdf_pg_all_templates\"
# }
}
}
Ganti nilai contoh sebagai berikut:
- your_table_id_1: ID tabel pertama di instance Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL Anda.
- your_table_id_2: ID tabel kedua di instance Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL Anda.
- your_context_set_id: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi untuk Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL.
Python SDK
Contoh kode Python berikut menunjukkan cara menentukan detail sumber data Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL menggunakan Python SDK.
# Cloud SQL data source
cloudsql_table_ids = ["your_table_id_1", "your_table_id_2"]
cloudsql_context_set_id = "your_context_set_id"
cloudsql_reference = geminidataanalytics.CloudSqlReference()
cloudsql_reference.database_reference.table_id = cloudsql_table_ids
cloudsql_reference.agent_context_reference.context_set_id = cloudsql_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloudsql.cloudsql_reference = cloudsql_reference
Ganti nilai contoh sebagai berikut:
- your_table_id_1: ID tabel pertama di instance Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL Anda.
- your_table_id_2: ID tabel kedua di instance Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL Anda.
- your_context_set_id: ID lengkap set konteks yang akan diambil. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi untuk Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL.