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

不公開預先發布版

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

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

注意： 如要使用 Conversational Analytics API，您必須加入私人搶先體驗計畫。如有意願參加，請填寫預覽版意願表單。

本頁說明如何驗證 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/v1alpha/projects/{billing_project}:method"
  headers = {"Authorization": f'Bearer {access_token[0]}'}

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

• YOUR_BILLING_PROJECT：已啟用必要 API 的帳單專案 ID。
• method：目標端點的資源路徑。例如：
  • 如要建立資料代理程式，請使用 POST 方法和資源路徑 /v1alpha/projects/{billing_project}/locations/global/dataAgents。
  • 如要列出現有資料代理程式，請使用 GET 方法和資源路徑 /v1alpha/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 執行個體的網址
• 要用做資料來源的特定 LookML 模型和 Looker 探索

然後選擇使用 Looker API 金鑰 (用戶端 ID 和用戶端密鑰) 或存取權杖進行驗證。

注意： 您一次只能透過 Conversational Analytics API 連線至一個 Looker 探索。

使用 Looker API 金鑰進行驗證

本節說明如何產生 API 金鑰，以及如何使用直接 HTTP 要求或 SDK 設定 Conversational Analytics API，以便連線至 Looker。

如要與 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 用戶端 ID (looker_client_id) 和 Looker 用戶端密鑰 (looker_client_secret) 儲存為環境變數，以提升安全性。

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 驗證」和「提供用戶端憑證以取得授權權杖」。

注意： 用於產生 access_token 值的憑證必須具備使用 Get LookML Model Explore 和 Run Inline Query Looker 端點所需的權限。develop 權限是最低要求。

使用 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

透過 Conversational Analytics API，您一次最多可以連結及查詢 10 個 BigQuery 資料表。

注意： 如果查詢需要跨多個表格進行複雜的聯結，可能會導致回覆不夠準確。

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

使用 Python 進行 HTTP

向 BigQuery 專案完成驗證後，您就可以設定 Conversational Analytics API，直接發出 HTTP 要求來存取 BigQuery 中的資料。下列程式碼範例說明如何指定 BigQuery 資料來源詳細資料，以及 HTTP 要求的內文。

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "bigquery-public-data",
          "datasetId": "san_francisco",
          "tableId": "street_trees"
        }
      ]
    }
}

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

• bigquery-public-data：BigQuery 專案的 ID
• san_francisco：BigQuery 資料集的 ID
• street_trees：BigQuery 資料表的 ID

Python SDK

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

下列 Python 程式碼範例說明如何在 Colaboratory 中向 BigQuery 驗證 Google 帳戶，以及如何設定 Conversational Analytics API 來存取 BigQuery 資料來源。

from google.colab import auth
auth.authenticate_user()

bq_project_id = "YOUR-PROJECT-ID" # @param {type:"string"}
bq_dataset_id = "YOUR-DATASET-ID" # @param {type:"string"}
bq_table_id = "YOUR-TABLE-ID" # @param {type:"string"}

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = bq_project_id
bigquery_table_reference.dataset_id = bq_dataset_id
bigquery_table_reference.table_id = bq_table_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference]

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

• YOUR-PROJECT-ID：BigQuery 專案的 ID
• YOUR-DATASET-ID：BigQuery 資料集的 ID
• YOUR-TABLE-ID：BigQuery 資料表的 ID

使用 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。