建立及設定 Cloud 資源連線

BigQuery 管理員可以建立 Cloud 資源連線，讓資料分析師執行下列工作：

• 使用 BigLake 資料表查詢結構化 Cloud Storage 資料。BigLake 資料表可讓您透過存取權委派功能查詢外部資料。
• 使用物件資料表查詢 Cloud Storage 中的非結構化資料。
• 使用 Cloud Run functions 或 Cloud Run 中支援的任何語言，實作遠端函式。
• 使用 Spanner 外部資料集查詢 Spanner 資料。 使用 Cloud Resource 連線的 Spanner 外部資料集可讓您透過存取權委派功能，查詢外部資料來源。
• 使用 BigQuery ML 遠端模型執行生成式 AI 工作。

如要進一步瞭解連線，請參閱連線簡介。

事前準備

• 啟用 BigQuery Connection API。

  啟用 API

• 如要取得建立 Cloud Resource 連線所需的權限，請要求管理員授予下列 IAM 角色：

  • 專案的 BigQuery 連線管理員 (roles/bigquery.connectionAdmin)
  • Storage 物件檢視者 (roles/storage.objectViewer) 在 bucket 上

  如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

  您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

  如要使用以 Cloud Storage 為基礎的 BigLake 資料表查詢結構化資料，或使用物件資料表查詢非結構化資料，與連線相關聯的服務帳戶也必須在包含外部資料的 bucket 中，具備 Storage 檢視者 (roles/storage.viewer)、Storage 物件使用者 (roles/storage.objectUser) 和 Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) 角色。
  
• 確認 Google Cloud SDK 版本為 366.0.0 以上：

  gcloud version

  視需要更新 Google Cloud SDK。

位置注意事項

使用 Cloud Storage 儲存資料檔案時，建議使用 Cloud Storage 單一地區或雙地區值區，以獲得最佳效能，而非多地區值區。

建立 Cloud 資源連線

BigLake 會使用連線存取 Cloud Storage。您可以將這個連線用於單一資料表或一組資料表。

如果您已設定預設連線，或具備 BigQuery 管理員角色，可以略過這個步驟。

建立供遠端模型使用的Cloud 資源連線，並取得連線的服務帳戶。在與上一步建立的資料集相同的位置中建立連線。

選取下列選項之一：

控制台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 在「Explorer」窗格中展開專案名稱，然後按一下「Connections」。

4. 在「Connections」(連線) 頁面中，按一下「Create connection」(建立連線)。

5. 在「連線類型」中，選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。

6. 在「連線 ID」欄位中，輸入連線名稱。

7. 在「位置類型」部分，選取連線位置。連線應與資料集等其他資源位於同一位置。

8. 點選「建立連線」。

9. 點選「前往連線」。

10. 在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

bq

1. 在指令列環境中建立連線：

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 參數會覆寫預設專案。

   更改下列內容：

   • REGION：您的連線區域
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • CONNECTION_ID：連線的 ID

   建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將其與連線建立關聯。

   疑難排解：如果收到下列連線錯誤訊息，請更新 Google Cloud SDK：

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 擷取並複製服務帳戶 ID，以供後續步驟使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   輸出結果會與下列內容相似：

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

使用 google_bigquery_connection 資源。

注意： 如要使用 Terraform 建立 BigQuery 物件，必須啟用 Cloud Resource Manager API。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

下列範例會在 US 地區中建立名為 my_cloud_resource_connection 的 Cloud 資源連線：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每個專案只需要執行一次這個指令，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf 中。

   視需要從 GitHub 複製程式碼。如果 Terraform 代码片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，然後在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

將存取權授予服務帳戶

如要建立遠端函式，您必須授予 Cloud Run 函式或 Cloud Run 必要角色。

如要連線至 Cloud Storage，您必須授予新連線 Cloud Storage 的唯讀存取權，這樣 BigQuery 就能代替使用者存取檔案。

選取下列選項之一：

控制台

建議您為連線資源的服務帳戶，授予 Storage 物件使用者 IAM 角色 (roles/storage.objectUser)，這樣服務帳戶就能存取 Cloud Storage bucket。

1. 前往「IAM & Admin」(IAM 與管理) 頁面。

   前往「IAM & Admin」(IAM 與管理)

2. 點按「 Grant access」(授予存取權)。

   「新增主體」對話方塊隨即開啟。

3. 在「新增主體」欄位，輸入先前複製的服務帳戶 ID。

4. 在「Select a role」(請選擇角色) 欄位中，依序選取「Cloud Storage」和「Storage Object User」(Storage 物件使用者)。

5. 按一下 [儲存]。

gcloud

使用 gcloud storage buckets add-iam-policy-binding 指令：

gcloud storage buckets add-iam-policy-binding gs://BUCKET \
--member=serviceAccount:MEMBER \
--role=roles/storage.objectUser

更改下列內容：

• BUCKET：儲存空間值區的名稱。
• MEMBER：您先前複製的服務帳戶 ID。

詳情請參閱「將主體新增至值區層級政策」。

Terraform

使用 google_bigquery_connection 資源。

注意： 如要使用 Terraform 建立 BigQuery 物件，必須啟用 Cloud Resource Manager API。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

以下範例會將 IAM 角色存取權授予 Cloud 資源連線的服務帳戶：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "connectionPermissionGrant" {
  project = data.google_project.default.project_id
  role    = "roles/storage.objectViewer"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每個專案只需要執行一次這個指令，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf 中。

   視需要從 GitHub 複製程式碼。如果 Terraform 代码片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，然後在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

注意： 將使用者遷移至 BigLake 資料表後，請移除他們直接存取 Cloud Storage 的權限。因為這類權限能讓使用者略過 BigLake 資料表目前設定的管理政策，像是資料欄/列層級安全防護機制。

與使用者共用連線

您可以授予下列角色，讓使用者查詢資料及管理連線：

• roles/bigquery.connectionUser：可讓使用者透過連線功能連結外部資料來源，並對其執行查詢。

• roles/bigquery.connectionAdmin：讓使用者管理連線。

如要進一步瞭解 BigQuery 中的 IAM 角色和權限，請參閱預先定義的角色和權限一文。

選取下列選項之一：

控制台

1. 前往「BigQuery」頁面

   前往「BigQuery」

   連線會列在專案中，位於「連線」群組。

2. 點選左側窗格中的 「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 按一下專案，然後依序點選「連線」和所需連線。

4. 在「詳細資料」窗格中，按一下「共用」即可共用連線。 接著，按照下列步驟操作：

   1. 在「連線權限」對話方塊中，新增或編輯主體，與其他主體共用連線。

   2. 按一下 [儲存]。

bq

您無法使用 bq 指令列工具共用連線。 如要共用連線，請使用 Google Cloud 控制台或 BigQuery Connections API 方法共用連線。

API

請使用 BigQuery Connections REST API 參考資料中的 projects.locations.connections.setIAM 方法，並提供 policy 資源的執行個體。

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:[e-mail]")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

後續步驟

• 瞭解不同連線類型。
• 瞭解如何管理連線。
• 瞭解 BigLake 資料表。
• 瞭解如何建立 BigLake 資料表。
• 瞭解如何將外部資料表升級為 BigLake 資料表。
• 瞭解物件資料表和建立方式。
• 瞭解如何導入遠端函式。
• 瞭解如何建立 Spanner 外部資料集。