Mengautentikasi identitas pengguna dan terhubung ke sumber data

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.com untuk lokasi default global, atau geminidataanalytics.us.rep.googleapis.com untuk multi-region us.
  • PROJECT_ID: ID project Google Cloud tempat Anda mengaktifkan API yang diperlukan.
  • LOCATION: Lokasi tempat resource Anda disimpan (misalnya, global atau us-east4).

  • METHOD: Metode endpoint target atau jalur resource (misalnya, dataAgents untuk membuat agen, atau dataAgents/AGENT_ID untuk 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, global atau us-east4).

  • METHOD: Metode endpoint target atau jalur resource. Contoh:

    • Untuk membuat agen data, gunakan metode POST dan tentukan dataAgents.
    • Untuk menampilkan daftar agen data yang ada, gunakan metode GET dan tentukan dataAgents.

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.namespace untuk 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.namespace untuk 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.