建立 Spanner 外部資料集

本文說明如何在 BigQuery 中建立連結至 Spanner 現有資料庫的外部資料集 (也稱為聯合資料集)。

外部資料集是 BigQuery 與外部資料來源在資料集層級的連結。您可以使用 GoogleSQL 查詢 Spanner 資料庫中的交易資料，不必將所有資料從 Spanner 複製或匯入 BigQuery 儲存空間。這些查詢結果會儲存在 BigQuery 中。

外部資料集中的資料表會自動填入對應外部資料來源中的資料表。您可以在 BigQuery 中直接查詢這些資料表，但無法修改、新增或刪除資料。不過，您在外部資料來源中進行的任何更新，都會自動反映在 BigQuery 中。

查詢 Spanner 時，查詢結果預設會儲存到暫時性資料表。 您也可以選擇將這些資料儲存為新的 BigQuery 資料表、與其他資料表彙整，或使用 DML 與現有資料表合併。

所需權限

如要取得建立外部資料集所需的權限，請要求管理員授予您 BigQuery 使用者 (roles/bigquery.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備 bigquery.datasets.create 權限，這是建立外部資料集時的必要權限。

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

如要進一步瞭解 BigQuery 中的 IAM 角色和權限，請參閱「IAM 簡介」。

使用 CLOUD_RESOURCE 連線

您也可以選擇讓 Spanner 外部資料集使用CLOUD_RESOURCE連線與 Spanner 資料庫互動，這樣一來，您就能透過 BigQuery 提供使用者 Spanner 資料存取權，不必直接授予他們 Spanner 資料庫存取權。由於 CLOUD_RESOURCE 連線中的服務帳戶會負責從 Spanner 擷取資料，您只需要授予使用者 Spanner 外部資料集的存取權即可。

使用 CLOUD_RESOURCE 連線建立 Spanner 外部資料集之前，請先完成下列步驟：

建立連線

您可以建立或使用現有的 CLOUD_RESOURCE 連線，連線至 Spanner。如要建立 Cloud 資源連線，請按照「建立 Cloud 資源連線」頁面的步驟操作。

建立連線後，請開啟連線，然後在「連線資訊」窗格中複製服務帳戶 ID。設定連線權限時，需要這個 ID。建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將其與連線建立關聯。

設定存取權

您必須授予新連線 Spanner 執行個體或資料庫的讀取權限。建議使用「Cloud Spanner 資料庫讀取者 (使用 Data Boost)」(roles/spanner.databaseReaderWithDataBoost) 預先定義的 IAM 角色。

請按照下列步驟，為您稍早從連線複製的服務帳戶授予資料庫層級的角色存取權：

1. 前往 Spanner「Instances」(執行個體) 頁面。

   前往執行個體頁面

2. 點選包含您的資料庫的執行個體名稱，前往「執行個體詳細資料」頁面。

3. 在「Overview」(總覽) 分頁中，選取資料庫的核取方塊。
   「Info panel」(資訊面板) 隨即出現。

4. 按一下「新增主體」。

5. 在「新增主體」面板的「新增主體」中，輸入先前複製的服務帳戶 ID。

6. 在「請選擇角色」欄位中，選取「Cloud Spanner 資料庫讀取者 (使用 Data Boost)」角色。

7. 按一下 [儲存]。

建立外部資料集

如要建立外部資料集，請按照下列步驟操作：

主控台

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

   前往 BigQuery 頁面

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

3. 展開「動作」選項，然後按一下「建立資料集」。

4. 在「建立資料集」頁面中，執行下列操作：

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

   • 在「外部資料集」部分，請執行下列操作：

     • 勾選「外部資料集的連結」旁邊的方塊。
     • 在「External dataset type」(外部資料集類型) 中，選取 Spanner。
     • 在「External source」(外部來源) 欄位中，輸入 Spanner 資料庫的完整 ID，格式如下：projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：projects/my_project/instances/my_instance/databases/my_database。
     • (選用) 在「Database role」(資料庫角色) 中輸入 Spanner 資料庫角色的名稱。如要進一步瞭解用於建立 Spanner 連線的資料庫角色
     • 如要使用連線建立外部資料集，請勾選「使用 Cloud Resource 連線」旁的方塊。

   • 保留其他預設設定。

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. 按一下「執行」。

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

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 資源。

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

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

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

API

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

請注意，外部資料集中的資料表名稱不區分大小寫。

使用 CLOUD_RESOURCE 連線建立外部資料集時，您必須對外部資料集使用的連線具備 bigquery.connections.delegate 權限 (可透過 BigQuery 連線管理員角色取得)。

控管資料表的存取權

Spanner 外部資料集支援使用者憑證 (EUC)。也就是說，從外部資料集存取 Spanner 資料表時，存取權是由 Spanner 控制。使用者必須在 Spanner 中獲得存取權，才能查詢這些資料表。

Spanner 外部資料集也支援存取權委派。存取權委派功能可將 Spanner 資料表的存取權，與外部資料集和基礎 Spanner 資料表的直接存取權分離開來。與服務帳戶相關聯的 Cloud 資源連線，可用於連線至 Spanner。即使使用者未在 Spanner 中取得存取權，也能從外部資料集查詢這些 Spanner 資料表。

列出外部資料集中的資料表

如要列出外部資料集中可供查詢的資料表，請參閱列出資料集。

取得資料表資訊

如要取得外部資料集中的資料表資訊 (例如結構定義詳細資料)，請參閱「取得資料表資訊」。

查詢 Spanner 資料

查詢外部資料集中的資料表，與查詢任何其他 BigQuery 資料集中的資料表相同。不過，系統不支援資料修改作業 (DML)。

查詢 Spanner 外部資料集中的資料表時，系統預設會使用 Data Boost，且無法變更。因此，您需要額外權限才能執行這類查詢。

在外部資料集中建立檢視區塊

您無法在外部資料集中建立檢視區塊。不過，您可以在標準資料集中建立檢視表，並以外部資料集中的資料表為基礎。詳情請參閱建立檢視畫面。

刪除外部資料集

刪除外部資料集與刪除任何其他 BigQuery 資料集相同。刪除外部資料集不會影響 Spanner 資料庫中的資料表。詳情請參閱「刪除資料集」。

限制

• 適用 BigQuery 聯合查詢的限制。
• 只有預設 Spanner 結構定義中的資料表可在 BigQuery 中存取。系統不支援名稱結構定義中的資料表。
• 在 BigQuery 中，您看不到 Spanner 資料庫中定義的主鍵和外鍵。
• 如果 Spanner 資料庫中的資料表含有 BigQuery 不支援的資料欄類型，則無法在 BigQuery 端存取該資料欄。
• 您無法在 Spanner 外部資料集中的資料表新增、刪除或更新資料或中繼資料。
• 您無法在 Spanner 外部資料集中建立新的資料表、檢視表或具體化檢視表。
• 系統不支援 INFORMATION_SCHEMA 檢視。
• 不支援中繼資料快取。
• 與資料表建立預設值相關的資料集層級設定不會影響外部資料集，因為您無法手動建立資料表。
• 系統不支援使用 PostgreSQL 方言的 Spanner 資料庫。
• 不支援 Write API 和 Read API。
• 不支援資料列層級安全防護、資料欄層級安全防護和資料遮蓋。
• 系統不支援以 Spanner 外部資料集中的資料表為基礎的具體化檢視表。
• 不支援與 Dataplex Universal Catalog 整合。例如，系統不支援資料設定檔和資料品質掃描。
• 系統不支援表格層級的標記。
• 撰寫查詢時，SQL 自動完成功能不適用於 Spanner 外部資料表。
• 外部資料集不支援「透過 Sensitive Data Protection 掃描」。
• 外部資料集不支援透過 BigQuery sharing (舊稱 Analytics Hub) 共用。
• 如果 Spanner 外部資料集使用使用者憑證 (EUC)，您可以建立參照外部資料集的授權檢視畫面。不過，查詢這個檢視區塊時，執行查詢者的 EUC 會傳送至 Spanner。
• 如果 Spanner 外部資料集使用 Cloud 資源連線進行存取權委派，您可以建立參照外部資料集的授權檢視區塊或授權常式。

後續步驟

• 進一步瞭解 Spanner 聯合查詢。