ユーザー ID を認証してデータソースに接続する

このページでは、会話型分析 API に対する認証を行う方法について説明します。また、直接 HTTP リクエストまたは SDK を使用して、Looker、BigQuery、データポータル、データベース(AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL)でデータの接続を構成する方法についても説明します。会話型分析 API は、標準の Google Cloud 認証方法を使用します。

始める前に

Conversational Analytics API で認証を行い、データへの接続を構成するには、Conversational Analytics API を有効にするで説明されている前提条件を満たし、 Google Cloud プロジェクトに必要な API を有効にする必要があります。

顧客管理の暗号鍵(CMEK)を使用して Conversational Analytics API リソースを保護する場合は、API のサービス アカウントに Cloud Key Management Service 鍵を使用する権限を付与する必要があります。詳細については、CMEK のドキュメントの始める前にをご覧ください。

会話型分析 API に対する認証を行う

このセクションでは、HTTP メソッドと Python メソッドを使用して必要な認可トークンを取得し、会話型分析 API に対する認証を行う方法について説明します。次のサンプルでは、リソースのロケーションに基づくリージョン エンドポイント ロジックを使用します。リージョン エンドポイントの詳細については、データ所在地をご覧ください。

HTTP curl

次の curl コマンドの例は、API エンドポイント メソッドをターゲットにして、Google Cloud CLI によって生成された ID トークンを使用して認証済みリクエストを送信する方法を示しています。

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD

サンプル値を次のように置き換えます。

  • ENDPOINT_URL: ロケーションに対応するサービス エンドポイント URL。たとえば、global デフォルトの場所の場合は geminidataanalytics.googleapis.com、us マルチリージョンの場合は geminidataanalytics.us.rep.googleapis.com。
  • PROJECT_ID: 必要な API を有効にした Google Cloud プロジェクトの ID。
  • LOCATION: リソースが保存されているロケーション(例: global、us-east4)。

  • METHOD: ターゲット エンドポイントのメソッドまたはリソースパス(例: エージェントを作成する場合は dataAgents、特定のエージェントを取得する場合は dataAgents/AGENT_ID)。

Python を使用した HTTP

次の Python サンプルコードは、API エンドポイント メソッドをターゲットにして、アクセス トークンを取得し、認証済みの HTTP リクエストを送信する方法を示しています。このコードは、指定されたロケーション タイプに基づいてエンドポイント URL を動的に構築します。

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]}'}

サンプル値を次のように置き換えます。

  • PROJECT_ID: 必要な API を有効にした Google Cloud プロジェクトの ID。
  • LOCATION: リソースが保存されているロケーション(例: global、us-east4)。

  • METHOD: ターゲット エンドポイントのメソッドまたはリソースパス。次に例を示します。

    • データ エージェントを作成するには、POST メソッドを使用して dataAgents を指定します。
    • 既存のデータ エージェントの一覧を取得するには、GET メソッドを使用して dataAgents を指定します。

Python SDK

次の Python コードサンプルは、Colaboratory 内で Conversational Analytics API にアクセスするために Google アカウントを認証する方法を示しています。

from google.colab import auth
auth.authenticate_user()

Conversational Analytics API を使用して Looker に接続する

必要なロールと権限、認可オプション、Looker Explore への接続のサンプルコードについては、Looker に接続するをご覧ください。プライベート接続のみを使用するインスタンスについては、プライベート接続を使用する Looker(Google Cloud コア)インスタンスに接続するをご覧ください。

Conversational Analytics API を使用して BigQuery に接続する

このセクションでは、直接 HTTP リクエストまたは SDK を使用して、BigQuery に接続するように会話型分析 API を構成する方法について説明します。会話型分析 API は、BigQuery テーブルへの接続と、BigQuery Graph を使用したグラフへの接続をサポートしています。

会話型分析 API では、接続できる BigQuery テーブルの数に上限はありません。ただし、多数のテーブルに接続すると、精度が低下したり、Gemini の入力トークン上限を超えたりする可能性があります。複数のテーブルにわたる複雑な結合を必要とするクエリでも、レスポンスの精度が低下する可能性があります。

テーブルに接続する

1 つ以上の BigQuery テーブルに接続するには、各テーブルのプロジェクト ID、データセット ID、テーブル ID を指定します。

次の例は、HTTP リクエストまたは Python SDK を使用して 1 つ以上の BigQuery テーブルに接続する方法を示しています。

Python を使用した HTTP

次のサンプルコードは、複数の 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"
        },
      ]
    }
}

サンプル値を次のように置き換えます。

  • PROJECT_ID、PROJECT_ID_2、PROJECT_ID_3: 接続する BigQuery データセットとテーブルを含む Google Cloud プロジェクトの ID。公開データセットに接続するには、bigquery-public-data を指定します。
  • DATASET_ID、DATASET_ID_2、DATASET_ID_3: BigQuery データセットの ID(Lakehouse ランタイム カタログ テーブルの場合は catalog.namespace)。
  • TABLE_ID、TABLE_ID_2、TABLE_ID_3: BigQuery テーブルの ID(または Lakehouse ランタイム カタログ テーブルのテーブル名)。

Python SDK

Colaboratory の auth SDK を使用して、Google アカウントの認証情報で認証を行い、認証情報を使用して BigQuery にアクセスすることを Colab クライアントに認可できます。

次の Python コードサンプルは、複数の BigQuery テーブルへの接続を定義し、Colaboratory 内で Google アカウントの認証情報を使用して認証を行い、リクエストを承認する方法を示しています。

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]

サンプル値を次のように置き換えます。

  • PROJECT_ID、PROJECT_ID_2、PROJECT_ID_3: 接続する BigQuery データセットとテーブルを含む Google Cloud プロジェクトの ID。公開データセットに接続するには、bigquery-public-data を指定します。
  • DATASET_ID、DATASET_ID_2、DATASET_ID_3: BigQuery データセットの ID(Lakehouse ランタイム カタログ テーブルの場合は catalog.namespace)。例: san_francisco。
  • TABLE_ID、TABLE_ID_2、TABLE_ID_3: BigQuery テーブルの ID(または Lakehouse ランタイム カタログ テーブルのテーブル名)。例: street_trees

BigQuery Graph に接続する

次の例は、HTTP リクエストまたは Python SDK を使用して、BigQuery Graph で 1 つ以上のグラフに接続する方法を示しています。

BigQuery エディションの要件とグラフクエリの制限については、BigQuery Graph に接続するをご覧ください。

Python を使用した HTTP

次のサンプルコードは、BigQuery グラフへの接続を定義します。

bigquery_data_sources = {
    "bq": {
      "propertyGraphReferences": [
        {
          "projectId": "GRAPH_PROJECT_ID",
          "datasetId": "GRAPH_DATASET_ID",
          "propertyGraphId": "GRAPH_ID"
        }
      ]
    }
}

サンプル値を次のように置き換えます。

  • GRAPH_PROJECT_ID: BigQuery グラフを含む Google Cloud プロジェクトの ID。
  • GRAPH_DATASET_ID: グラフを含む BigQuery データセットの ID。
  • GRAPH_ID: BigQuery グラフの ID。

Python SDK

Colaboratory の auth SDK を使用して、Colaboratory で認証されたユーザーの認証情報で BigQuery に対する認証を行うことができます。

次の Python コードサンプルは、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]

サンプル値を次のように置き換えます。

  • GRAPH_PROJECT_ID: BigQuery グラフを含む Google Cloud プロジェクトの ID。
  • GRAPH_DATASET_ID: グラフを含む BigQuery データセットの ID。
  • GRAPH_ID: BigQuery グラフの ID。

Conversational Analytics API を使用してデータポータルに接続する

Conversational Analytics API を使用してデータポータルに接続するには、まずデータポータル API を有効にする必要があります。このセクションでは、直接 HTTP リクエストまたは SDK を使用して、データポータルに接続するように 会話型分析 API を構成する方法について説明します。

データポータル Pro で会話型分析 API を使用するには、Pro サブスクリプションが VPC-SC 境界外にある必要があります。

Data Studio API を有効にする

データポータル API を有効にするには、API を有効にするの手順を実施します。

データポータルに対する認証

会話型分析 API を使用してデータポータルに接続するには、認証されたユーザーまたはサービス アカウントにデータポータルのデータソースへのアクセス権が付与されていることを確認してから、データソース ID を指定する必要があります。

Python を使用した HTTP

Data Studio API を有効にすると、Python で HTTP curl リクエストを送信して、データポータルに接続できます。次のサンプルコードは、HTTP リクエストの本文でデータポータルのデータソースの詳細を指定する方法を示しています。

データポータルへの接続は、直接 HTTP リクエストを送信することで行うことができます。HTTP 呼び出しの例を次のコードブロックに示します。

looker_studio_data_source = {
    "studio":{
        "studio_references":
        [
            {
              "datasource_id": "DATASOURCE_ID"
            }
        ]
    }
}

your_studio_datasource_id は、使用するデータポータル データソースの実際のデータソース ID に置き換えます。

Python SDK

Data Studio API を有効にすると、SDK を使用してデータポータルに接続できます。次の Python コードサンプルは、データポータルのデータソースの詳細を指定する方法を示しています。


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]

STUDIO-DATASOURCE-ID は、使用するデータポータル データソースの実際のデータソース ID に置き換えます。

Conversational Analytics API を使用してデータベースに接続する

会話型分析 API を使用してデータベースに接続するには、データベース インスタンスに必要な IAM 権限が必要です。必要に応じて、データベース データソースでコンテキスト セット(プレビュー)を使用する場合は、コンテキスト セットを作成、アップロード、管理するために、Knowledge Catalog API を有効にし、プロジェクトに対する Dataplex Catalog 編集者(roles/dataplex.catalogEditor)または Dataplex Catalog 管理者(roles/dataplex.catalogAdmin)のロールを付与する必要があります。詳細については、コンテキスト セットの権限をご覧ください。

AlloyDB for PostgreSQL に接続する

ユーザーまたはサービス アカウントには alloydb.databaseUser ロールが必要です。詳細については、AlloyDB IAM データベース認証をご覧ください。

Python を使用した HTTP

次のサンプルコードは、HTTP リクエストの本文で AlloyDB データソースの詳細を指定する方法を示しています。

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"
      # }
  }
}

サンプル値を次のように置き換えます。

  • your_table_id: テーブル ID のカンマ区切りリスト。設定しない場合、データベース内のすべてのテーブルが考慮されます。
  • your_context_set_id: 省略可。取得するコンテキスト セットの完全な ID。コンテキスト セット ID を確認する方法については、AlloyDB のドキュメントをご覧ください。

Python SDK

次の Python コードサンプルは、Python SDK を使用して AlloyDB のデータソースの詳細を定義する方法を示しています。

# 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

サンプル値を次のように置き換えます。

  • your_table_id_1: AlloyDB インスタンスの最初のテーブルの ID。
  • your_table_id_2: AlloyDB インスタンスの 2 番目のテーブルの ID。
  • your_context_set_id: 取得するコンテキスト セットの完全な ID。コンテキスト セット ID を確認する方法については、AlloyDB のドキュメントをご覧ください。

GoogleSQL for Spanner に接続する

ユーザーまたはサービス アカウントには spanner.databaseReader ロールが必要です。詳細については、IAM ロールを適用するをご覧ください。

Python を使用した HTTP

次のサンプルコードは、HTTP リクエストの本文で GoogleSQL for Spanner データソースの詳細を指定する方法を示しています。

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"
        # }
    }
}

サンプル値を次のように置き換えます。

  • your_table_id_1: GoogleSQL for Spanner インスタンスの最初のテーブルの ID。
  • your_table_id_2: GoogleSQL for Spanner インスタンスの 2 番目のテーブルの ID。
  • your_context_set_id: 取得するコンテキスト セットの完全な ID。コンテキスト セット ID を確認する方法については、Spanner のドキュメントをご覧ください。

Python SDK

次の Python コードサンプルは、Python SDK を使用して GoogleSQL for Spanner データソースの詳細を定義する方法を示しています。

# 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

サンプル値を次のように置き換えます。

  • your_table_id_1: GoogleSQL for Spanner インスタンスの最初のテーブルの ID。
  • your_table_id_2: GoogleSQL for Spanner インスタンスの 2 番目のテーブルの ID。
  • your_context_set_id: 取得するコンテキスト セットの完全な ID。コンテキスト セット ID を確認する方法については、Spanner のドキュメントをご覧ください。

Cloud SQL for MySQL と Cloud SQL for PostgreSQL に接続する

以降のセクションでは、Cloud SQL for MySQL と Cloud SQL for PostgreSQL の両方を接続する手順について説明します。ユーザーまたはサービス アカウントには、cloudsql.studioUser ロールと cloudsql.instanceUser ロールが必要です。詳細については、Cloud SQL for MySQL の IAM データベース認証でユーザーを管理すると Cloud SQL for PostgreSQL の IAM データベース認証でユーザーを管理するをご覧ください。

Python を使用した HTTP

次のサンプルコードは、HTTP リクエストの本文で Cloud SQL for MySQL と Cloud SQL for PostgreSQL のデータソースの詳細を指定する方法を示しています。

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\"
        # }
    }
}

サンプル値を次のように置き換えます。

  • your_table_id_1: Cloud SQL for MySQL インスタンスと Cloud SQL for PostgreSQL インスタンスの最初のテーブルの ID。
  • your_table_id_2: Cloud SQL for MySQL と Cloud SQL for PostgreSQL インスタンスの 2 番目のテーブルの ID。
  • your_context_set_id: 取得するコンテキスト セットの完全な ID。コンテキスト セット ID を見つける方法については、Cloud SQL for MySQL と Cloud SQL for PostgreSQL のドキュメントをご覧ください。

Python SDK

次の Python コードサンプルは、Python SDK を使用して Cloud SQL for MySQL と Cloud SQL for PostgreSQL のデータソースの詳細を定義する方法を示しています。

# 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

サンプル値を次のように置き換えます。

  • your_table_id_1: Cloud SQL for MySQL インスタンスと Cloud SQL for PostgreSQL インスタンスの最初のテーブルの ID。
  • your_table_id_2: Cloud SQL for MySQL と Cloud SQL for PostgreSQL インスタンスの 2 番目のテーブルの ID。
  • your_context_set_id: 取得するコンテキスト セットの完全な ID。コンテキスト セット ID を見つける方法については、Cloud SQL for MySQL と Cloud SQL for PostgreSQL のドキュメントをご覧ください。