使用對話式分析 API 驗證並連線至資料來源

開發人員可透過 geminidataanalytics.googleapis.com 存取 Conversational Analytics API，建構以人工智慧 (AI) 技術為基礎的聊天介面或資料代理程式，使用自然語言回答 BigQuery、Looker 和 Looker Studio 中結構化資料的問題。

本頁說明如何驗證 Conversational Analytics API，以及如何使用直接 HTTP 要求或 SDK，在 Looker、BigQuery 和 Looker Studio 中設定資料連線。Conversational Analytics API 使用標準的Google Cloud 驗證方法。

事前準備

如要向 Conversational Analytics API 進行驗證，並設定資料連線，請先完成必要條件，並為 Google Cloud 專案啟用必要的 API，詳情請參閱「啟用 Conversational Analytics API」。

向 Conversational Analytics API 進行驗證

本節說明如何使用 HTTP 和 Python 方法取得必要的授權權杖，藉此透過 geminidataanalytics.googleapis.com 向 Conversational Analytics API 進行驗證。

HTTP curl

下列範例 curl 指令會將要求傳送至 Conversational Analytics API。gcloud auth print-identity-token 指令會提供用於授權的存取權杖。在程式碼範例中，將 替換為適當的 API 資源路徑。

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://geminidataanalytics.googleapis.com/

使用 Python 進行 HTTP

下列 Python 範例程式碼說明如何使用 Google Cloud CLI 和 Python，取得 HTTP 驗證的存取權杖。

  billing_project = 'YOUR_BILLING_PROJECT'
  access_token = !gcloud auth application-default print-access-token
  url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}:method"
  headers = {"Authorization": f'Bearer {access_token[0]}'}

請依下列方式替換範例值：

  • YOUR_BILLING_PROJECT：已啟用必要 API 的帳單專案 ID。
  • method：目標端點的資源路徑。例如：
    • 如要建立資料代理程式，請使用 POST 方法和資源路徑 /v1beta/projects/{billing_project}/locations/global/dataAgents。
    • 如要列出現有資料代理程式，請使用 GET 方法和資源路徑 /v1beta/projects/{billing_project}/locations/global/dataAgents。

Python SDK

下列 Python 程式碼範例說明如何在 Colaboratory 中驗證 Google 帳戶，以存取 Conversational Analytics API：

from google.colab import auth
auth.authenticate_user()

透過 Conversational Analytics API 連結至 Looker

如要使用 Conversational Analytics API 連線至 Looker，請提供下列資訊：

此外，驗證使用者或服務帳戶必須具備必要 Looker 權限。

然後選擇使用 Looker API 金鑰 (用戶端 ID 和用戶端密鑰) 或存取權杖進行驗證。使用 Looker (Google Cloud Core) 私人 IP 選項的客戶必須使用存取權權杖進行驗證。

使用 Conversational Analytics API 時，一次只能連結一個 Looker 探索。

必要 Looker 權限

用於驗證的使用者或服務帳戶憑證必須具備 Looker 角色，且該角色包含您要查詢的模型適用的下列權限：

您可以在 Looker 執行個體的「管理」>「角色」部分設定這些權限。

使用 Looker API 金鑰進行驗證

本節說明如何產生 API 金鑰，以及如何使用直接 HTTP 要求或 SDK 設定 Conversational Analytics API，以便連線至 Looker。如果客戶使用 Looker (Google Cloud Core) 私人 IP 選項，就無法使用這個方法，必須透過存取權權杖進行驗證。

如要與 Looker 執行個體建立連線，您需要有效的 Looker API 金鑰 (由 Looker 建立，包含用戶端 ID 和用戶端密鑰)。Looker 會使用這些金鑰授權對 Looker API 的要求。

如要進一步瞭解如何產生新的 Looker API 金鑰，請參閱「管理設定 - 使用者」。如要進一步瞭解驗證方法和如何管理 Looker API 金鑰，請參閱「Looker API 驗證」。

使用 Python 進行 HTTP

產生 API 金鑰 (用戶端 ID 和密鑰) 後，即可設定 Conversational Analytics API，直接發出 HTTP 要求來連結至 Looker。下列程式碼範例示範如何在 HTTP 要求的內文中，指定 Looker 資料來源詳細資料和 API 金鑰。


looker_credentials = {
  "oauth": {
      "secret": {
        "client_id": "your_looker_client_id",
        "client_secret": "your_looker_client_secret",
      }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

請依下列方式替換範例值：

  • your_looker_client_id：您產生的 Looker API 金鑰用戶端 ID
  • your_looker_client_secret：您產生的 Looker API 金鑰用戶端密鑰
  • https://your_company.looker.com：Looker 執行個體的完整網址
  • your_model：要使用的 LookML 模型名稱
  • your_explore：您要使用的指定模型中的探索名稱

Python SDK

產生 API 金鑰 (用戶端 ID 和密鑰) 後，即可使用 Python 設定 Conversational Analytics API，以便連結至 Looker。下列 Python 程式碼範例示範如何指定 Looker 資料來源詳細資料和 API 金鑰給 Conversational Analytics API。

looker_client_id = "YOUR-LOOKER-CLIENT-ID" # @param {type:"string"}
looker_client_secret = "YOUR-LOOKER-CLIENT-SECRET" # @param {type:"string"}
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI" # @param {type:"string"}
lookml_model = "YOUR-LOOKER-MODEL" # @param {type:"string"}
explore = "YOUR-LOOKER-EXPLORE" # @param {type:"string"}

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

請依下列方式替換範例值：

  • YOUR-LOOKER-CLIENT-ID：您產生的 Looker API 金鑰用戶端 ID
  • YOUR-LOOKER-CLIENT-SECRET：您產生的 Looker API 金鑰用戶端密鑰
  • YOUR-LOOKER-INSTANCE-URI：Looker 執行個體的完整網址
  • YOUR-LOOKER-MODEL：要使用的 Looker 模型名稱
  • YOUR-LOOKER-EXPLORE：要使用的 Looker 探索名稱

使用存取權杖進行驗證

本節說明如何設定 Conversational Analytics API，以便使用存取權杖連線至 Looker。

如要與 Looker 執行個體建立連線，您需要有效的 OAuth2 access_token 值，這個值是透過向 login Looker API 端點提出要求並成功取得回應後建立。

如要進一步瞭解如何產生存取權杖，請參閱「Looker API 驗證」和「提供用戶端憑證以取得授權權杖」。

使用 Python 進行 HTTP

下列程式碼範例示範如何在 HTTP 要求的內文中，指定 Looker 資料來源詳細資料和存取權杖。

建議您將 Looker 存取權杖 (access_token) 儲存為環境變數，以提升安全性。

looker_credentials = {
  "oauth": {
    "token": {
      "access_token": "YOUR-TOKEN",
    }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

請依下列方式替換範例值：

  • YOUR-TOKEN：您產生的 access_token 值，用於向 Looker 驗證。
  • https://your_company.looker.com：Looker 執行個體的完整網址
  • your_model：要使用的 LookML 模型名稱
  • your_explore：您要使用的指定模型中的探索名稱

Python SDK

下列 Python 程式碼範例說明如何定義 Looker 資料來源詳細資料和存取權杖，以便使用 Python SDK 進行驗證。

建議您將 Looker 存取權杖 (access_token) 儲存為環境變數，以提升安全性。

looker_access_token = "YOUR-TOKEN"
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI"
lookml_model = "YOUR-LOOKER-MODEL"
explore = "YOUR-LOOKER-EXPLORE"

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = looker_access_token

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

請依下列方式替換範例值：

  • YOUR-TOKEN：您用來向 Looker 驗證的 access_token 值
  • YOUR-LOOKER-INSTANCE-URI：Looker 執行個體的完整網址
  • YOUR-LOOKER-MODEL：要使用的 Looker 模型名稱
  • YOUR-LOOKER-EXPLORE：要使用的 Looker 探索名稱

使用 JavaScript 的 HTTP

下列程式碼範例示範如何在 HTTP 要求的內文中，指定 Looker 資料來源詳細資料和存取權杖。

建議您將 Looker 存取權杖 (access_token) 儲存為環境變數，以提升安全性。

const requestBody = {
  project: GCP_PROJECT,
  messages: [
    {
      user_message: {
        text: inputWithPreviousMessages,
      },
    },
  ],
  context: {
    system_instruction: agentConfig.system_instructions,
    datasource_references: {
      looker: {
        explore_references: [
          {
            looker_instance_uri: YOUR-LOOKER-INSTANCE-URI,
            lookml_model: YOUR-LOOKER-MODEL,
            explore: YOUR-LOOKER-EXPLORE,
          },
        ],
        credentials: {
          oauth: {
            token: {
              access_token: YOUR-TOKEN,
            },
          },
        },
      },
    },
  },
}

請依下列方式替換範例值：

  • YOUR-LOOKER-INSTANCE-URI：Looker 執行個體的完整網址
  • YOUR-LOOKER-MODEL：要使用的 LookML 模型名稱
  • YOUR-LOOKER-EXPLORE：您要使用的指定模型中的探索名稱
  • YOUR-TOKEN：您產生的 access_token 值，用於向 Looker 驗證。

使用 Conversational Analytics API 連結至 BigQuery

如要透過 Conversational Analytics API 連結至一或多個 BigQuery 資料表，您必須驗證每個資料表的相關 BigQuery 專案。請針對每個資料表提供下列資訊：

  • BigQuery 專案 ID
  • BigQuery 資料集 ID
  • BigQuery 資料表 ID

使用對話式數據分析 API 時，可連結的 BigQuery 資料表數量沒有硬性限制。不過，連結大量資料表可能會降低準確度，或導致您超出 Gemini 的輸入權杖限制。如果查詢需要跨多個表格進行複雜聯結，也可能導致回覆不夠準確。

本節說明如何設定 Conversational Analytics API，透過直接 HTTP 要求或 SDK 連線至 BigQuery。

使用 Python 進行 HTTP

下列程式碼範例定義了與多個 BigQuery 資料表的連線。

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "my_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        {
          "projectId": "my_project_id_3",
          "datasetId": "my_dataset_id_3",
          "tableId": "my_table_id_3"
        },
      ]
    }
}

請依下列方式替換範例值：

  • my_project_id：包含要連結的 BigQuery 資料集和資料表的專案 ID。 Google Cloud 如要連線至公開資料集，請指定 bigquery-public-data。
  • my_dataset_id：BigQuery 資料集的 ID。
  • my_table_id：BigQuery 資料表的 ID。

Python SDK

您可以使用 Colaboratory 的 auth SDK，透過已向 Colaboratory 驗證的使用者憑證，向 BigQuery 進行驗證。

下列 Python 程式碼範例定義了多個 BigQuery 資料表的連線，並示範如何在 Colaboratory 中向 BigQuery 驗證 Google 帳戶。

from google.colab import auth
auth.authenticate_user()

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "my_project_id"
bigquery_table_reference.dataset_id = "my_dataset_id"
bigquery_table_reference.table_id = "my_table_id"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_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]

請依下列方式替換範例值：

  • my_project_id：包含要連結的 BigQuery 資料集和資料表的專案 ID。 Google Cloud 如要連線至公開資料集，請指定 bigquery-public-data。
  • my_dataset_id：BigQuery 資料集的 ID。例如：san_francisco。
  • my_table_id：BigQuery 資料表的 ID。例如：street_trees。

使用 Conversational Analytics API 連結至 Looker Studio

如要透過 Conversational Analytics API 連結至 Looker Studio，請先啟用 Looker Studio API。本節說明如何設定 Conversational Analytics API，以便使用直接 HTTP 要求或 SDK 連線至 Looker Studio。

啟用 Looker Studio API

如要啟用 Looker Studio API，請按照「啟用 API」一文中的操作說明進行。

向 Looker Studio 驗證

如要透過 Conversational Analytics API 連結至 Looker Studio，您必須向 Looker Studio 驗證身分，並提供 Looker Studio 資料來源 ID。

使用 Python 進行 HTTP

啟用 Looker Studio API 後，您可以使用 Python 提出 HTTP curl 要求，向 Looker Studio 進行驗證。下列範例程式碼示範如何在 HTTP 要求的內文中指定 Looker 資料來源詳細資料。

您可以發出直接 HTTP 要求，向 Looker Studio 進行驗證。下列程式碼區塊顯示 HTTP 呼叫範例。

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

請將 your_studio_datasource_id 替換為要使用的 Looker Studio 資料來源實際 ID。

Python SDK

啟用 Looker Studio API 後，您可以使用 SDK 向 Looker Studio 進行驗證。下列 Python 程式碼範例說明如何指定 Looker 資料來源詳細資料，並向 Looker Studio 進行驗證。


datasource_id = "STUDIO-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 替換為要使用的 Looker Studio 資料來源實際 ID。