預設連線總覽

為簡化工作流程，您可以在 BigQuery 中設定預設的雲端資源連線，用於建立外部資料表和 BigQuery ML 遠端模型。管理員設定預設連線後，使用者在建立資源時就能參照該連線，而不需要指定連線詳細資料。

BigQuery 支援下列資源中的預設連線：

• Cloud Storage BigLake 資料表
• 物件資料表
• BigQuery 中的 Apache Iceberg 專用 BigLake 資料表
• 遠端模型

如要使用預設連線，請在下列 SQL 子句中指定 DEFAULT 關鍵字：

• CREATE EXTERNAL TABLE 陳述式的 WITH CONNECTION 子句
• 遠端模型的 CREATE MODEL 陳述式 中的 REMOTE WITH CONNECTION 子句

事前準備

Enable the BigQuery Connection API.

Enable the API

必要角色和權限

如要使用預設連線，請使用下列身分與存取權管理 (IAM) 角色：

• 使用專案中的預設連線：BigQuery 連線使用者 (roles/bigquery.connectionUser)
• 在專案中設定預設連線：BigQuery 管理員 (roles/bigquery.admin)

• 如果需要為預設連線的服務帳戶授予權限：

  • 如果使用預設連線建立外部資料表，則必須是外部資料表所使用的任何 Cloud Storage 值區的儲存空間管理員 (roles/storage.admin)。

  • 如果使用預設連線建立遠端模型：在包含 Vertex AI 端點的專案中，使用專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)。針對下列類型的遠端模型，這是目前的專案：

    • 透過 Cloud AI 服務的遠端模型。
    • 透過 Google 或合作夥伴模型建立的遠端模型，方法是將模型名稱指定為端點。

    對於所有其他遠端模型，這個專案會包含目標模型要部署的 Vertex AI 端點。

    如果您使用遠端模型分析物件資料表中的非結構化資料，且物件資料表中使用的 Cloud Storage 值區位於與 Vertex AI 端點不同的專案中，則您必須在物件資料表使用的 Cloud Storage 值區中擁有儲存空間管理員 (roles/storage.admin) 權限。

  只有在您是管理員，並要將連線設為預設連線，或是使用者使用預設連線，但尚未將適當角色授予服務帳戶時，才需要這些角色。詳情請參閱「設定預設連線」。

這些預先定義的角色包含執行本文件中工作所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

設定預設連線

如要首次設定預設連線，請使用下列其中一種方法：

• 建立連線、將適當角色授予連線的服務帳戶，然後將連線設為預設連線。

  建立及設定預設連線的使用者必須具備 BigQuery 管理員角色，以及儲存空間管理員或專案 IAM 管理員角色 (視情況而定)。預設連線使用者需要具備 BigQuery 連線使用者角色。

• 建立連線，然後將其設為預設連線。使用預設連線時，服務會授予適當的角色給預設連線的服務帳戶。

  建立及設定預設連線的使用者必須具備 BigQuery 管理員角色。預設連線使用者需要具備 BigQuery 連線使用者角色，以及儲存空間管理員或專案 IAM 管理員角色 (視情況而定)。

• 在支援的陳述式中指定 DEFAULT 關鍵字。服務會建立連線，將適當角色授予連線的服務帳戶，然後將連線設為預設連線。

  預設連線使用者需要具備 BigQuery 管理員角色，以及儲存空間管理員或專案 IAM 管理員角色 (視情況而定)。

設定專案的預設連線

使用 ALTER PROJECT SET OPTIONS DDL 陳述式，為專案設定預設的 Cloud 資源連線。

以下範例會設定專案的預設連線：

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);
  

更改下列內容：

• PROJECT_ID：設定預設連線的專案 ID。
• REGION：連線的區域。
• CONNECTION_ID：要用於資料表和模型的預設連線 ID 或名稱。只需指定連線 ID 或名稱，並排除連線名稱或 ID 中附加的專案 ID 和區域前置字串。

如要進一步瞭解如何為專案設定預設連線，請參閱「管理預設設定」。

為預設連線提供權限

當您使用預設連線建立外部資料表或遠端模型時，如果服務帳戶尚未擁有適當的角色，Google Cloud 會授予預設連線的服務帳戶適當的角色。如果您沒有外部資料表或遠端模型所使用的 Cloud Storage 或 Vertex AI 資源的管理權限，這項操作就會失敗。

系統會將下列角色授予預設連線的服務帳戶：

使用 CONNECTION DEFAULT 建立外部資料表

以下範例說明如何在 BigQuery 中指定 WITH CONNECTION DEFAULT，以建立外部資料表。

範例：建立 Cloud Storage BigLake 資料表

下列 SQL 運算式會使用預設連線建立 Cloud Storage BigLake 資料表：

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

範例：使用預設連線建立物件資料表

下列 SQL 運算式會使用預設連線建立物件資料表：

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

範例：使用預設連結在 BigQuery 中建立 BigLake Iceberg 資料表

下列 SQL 運算式會使用預設連線建立 BigQuery 中的 BigLake Iceberg 資料表：

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

使用 REMOTE WITH CONNECTION DEFAULT 建立遠端模型

以下範例說明如何在 BigQuery 中指定 REMOTE WITH CONNECTION DEFAULT，以建立遠端模型。

範例：在 Vertex AI 模型上建立遠端模型

下列 SQL 運算式會使用預設連線建立遠端模型：

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

範例：透過 Cloud AI 服務建立遠端模型

下列 SQL 運算式會使用預設連線，透過Cloud AI 服務建立遠端模型：

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

範例：建立具有 HTTPS 端點的遠端模型

下列 SQL 運算式會建立含有 HTTPS 端點的遠端模型和預設連線：

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

後續步驟

• 瞭解 BigQuery 的預設設定。