建立 Spanner 外部資料集

主控台

1. 在 Google Cloud 控制台開啟「BigQuery」頁面。

   前往「BigQuery」頁面

2. 在「Explorer」面板中，選取要建立資料集的專案。

3. 展開 more_vert「動作」選項，然後點選「建立資料集」。

4. 在「Create dataset」頁面上執行下列操作：

   • 針對「Dataset ID」(資料集 ID)，輸入唯一的資料集名稱。
   • 針對「Location type」(位置類型)，選擇資料集的位置，例如 us-central1 或多區域 us。資料集建立後，就無法變更位置。

   • 如要使用「外部資料集」，請執行下列操作：

     • 勾選「外部資料集的連結」旁的方塊。
     • 在「External dataset type」(外部資料集類型) 中，選取 Spanner。
     • 在「外部來源」中，請使用下列格式輸入 Spanner 資料庫的完整 ID：projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：projects/my_project/instances/my_instance/databases/my_database。
     • 您可以選擇在「資料庫角色」中輸入 Spanner 資料庫角色的名稱。如需更多資訊，請參閱建立 Spanner 連線時使用的資料庫角色。
     • 您可以視需要勾選「使用 Cloud 資源連線」旁的方塊，藉此透過連線建立外部資料集。

   • 保留其他預設設定。

5. 點選「建立資料集」。

SQL

使用 CREATE EXTERNAL SCHEMA 資料定義語言 (DDL) 陳述式。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE EXTERNAL SCHEMA DATASET_NAME
     OPTIONS (
       external_source = 'SPANNER_EXTERNAL_SOURCE',
       location = 'LOCATION');
   /*
     Alternatively, create with a connection:
   */
   CREATE EXTERNAL SCHEMA DATASET_NAME
     WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
     OPTIONS (
       external_source = 'SPANNER_EXTERNAL_SOURCE',
       location = 'LOCATION');

   請依指示取代下列項目：

   • DATASET_NAME：BigQuery 中新資料集的名稱。
   • SPANNER_EXTERNAL_SOURCE：完整且經過完整指定的 Spanner 資料庫名稱，其中包含識別來源的前置字串，格式如下：google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如 google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database 或 google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database。
   • LOCATION：新資料集在 BigQuery 中的位置，例如 us-central1。建立資料集後，就無法變更位置。
   • (選用)CONNECTION_NAME：Cloud 資源連線的名稱。

3. 按一下 play_circle「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

bq

在指令列環境中，使用 bq mk 指令建立外部資料集：

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

或者，您也可以使用連線建立：

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

更改下列內容：

• LOCATION：新資料集在 BigQuery 中的所在位置，例如 us-central1。建立資料集後，您就無法變更位置。您可以使用 .bigqueryrc 檔案設定預設位置值。
• SPANNER_EXTERNAL_SOURCE：完整且經過修飾的 Spanner 資料庫名稱，其中包含識別來源的前置字串，格式如下：google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如 google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database 或 google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database。
• DATASET_NAME：BigQuery 中新資料集的名稱。如要在非預設專案中建立資料集，請採用下列格式將專案 ID 新增至資料集：PROJECT_ID:DATASET_NAME。
• (選用)CONNECTION_NAME：Cloud 資源連線的名稱。

Terraform

使用 google_bigquery_dataset 資源。

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

以下範例會建立 Spanner 外部資料集：

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

如要在 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 已建立或更新這些資源。

API

請呼叫 datasets.insert 方法，搭配 Spanner 資料庫的已定義資料集資源和 externalDatasetReference 欄位。