設定 AlloyDB 存取 BigQuery 即時資料的權限

如要直接從 AlloyDB for PostgreSQL 查詢 BigQuery 中的即時分析資料，而不執行擷取、轉換和載入 (ETL) 遷移作業，可以設定 Lakehouse 聯合。Lakehouse 聯合查詢功能可整合營運資料庫和數據分析資料倉儲，讓您支援即時數據分析和互動式應用程式，不必維護個別的資料管道。詳情請參閱「即時資料存取權總覽」。

這項整合功能可讓您在 AlloyDB 中執行查詢，即時存取 BigQuery 資料，並將 AlloyDB 中的作業資料表與參照 BigQuery 資料集的外來資料表彙整。

設定湖倉聯盟前，您需要 AlloyDB 叢集和主要執行個體，以及 BigQuery 資料集和資料表。詳情請參閱「建立資料集」和「建立及使用資料表」。

事前準備

  1. 在 AlloyDB for PostgreSQL 執行個體上啟用 bigquery_fdw.enabled 旗標。
  2. 熟悉支援的資料類型。
  3. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    10.

  10. 啟用必要的 Cloud API，以便建立及連線至 AlloyDB。

    啟用 API

  11. 在「確認專案」步驟中，點選「下一步」，確認要變更的專案名稱。

  12. 在「啟用 API」步驟中，點選「啟用」來啟用下列項目：

    • AlloyDB API
    • Compute Engine API
    • Cloud Resource Manager API
    • Service Networking API
    • BigQuery Storage API
    • BigQuery API

    如果您打算使用與 AlloyDB 位於相同 Google Cloud 專案的虛擬私有雲網路，設定 AlloyDB 的網路連線，就必須啟用 Service Networking API。

    如要使用位於其他 Google Cloud 專案的虛擬私有雲網路，設定 AlloyDB 的網路連線，則須啟用 Compute Engine API 和 Cloud Resource Manager API。

必要的角色

如要將 BigQuery 資料集的讀取權限授予 AlloyDB 叢集服務帳戶，您必須具備下列權限。詳情請參閱「將 BigQuery 資料集的存取權授予 AlloyDB」。

  • BigQuery 資料檢視者 (roles/bigquery.dataViewer) 或任何具備 bigquery.tables.get 和 bigquery.tables.getData 權限的自訂角色。如果授予資料表或檢視表，這個角色可提供讀取資料表或檢視表資料和中繼資料的權限。
  • BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)，或具備 bigquery.readsessions.create 和 bigquery.readsessions.getData 權限的任何自訂角色。可建立及使用讀取工作階段。
  • BigQuery 工作使用者 (roles/bigquery.jobUser) 或任何具備 bigquery.jobs.create 權限的自訂角色。提供權限，可使用 BigQuery API 在專案中執行工作，包括查詢。這個角色只能授予 Resource Manager 資源 (專案、資料夾和組織)。如果提供獨立的執行階段專案，工作就會在該專案中執行，而非在資料專案中執行。也就是說，您必須在執行階段專案中授予「工作使用者」角色。

如要存取 BigLake Metastore 資料表，請按照下列步驟操作：

  • BigLake 檢視者 (roles/biglake.viewer)，或具備 biglake.catalogs.get、biglake.namespaces.get、biglake.tables.get 和 biglake.tables.getData 權限的任何自訂角色。提供讀取 BigLake Metastore 目錄、命名空間和資料表的權限。
  • Storage 物件檢視者 (roles/storage.objectViewer) 或任何具備 storage.objects.get 權限的自訂角色。提供存取 BigQuery 外部資料表的權限，以及讀取 BigLake 和 BigLake Metastore 資料表基礎 Cloud Storage 物件的權限。必須在專案或 bucket 層級授予。

授予 AlloyDB 存取 BigQuery 資料集的權限

為 Lakehouse 聯合查詢啟用必要角色和權限後，您必須將 BigQuery 資料集的存取權授予 AlloyDB 叢集服務帳戶。

使用 AlloyDB Studio 連結 BigQuery 資料表時， Google Cloud 控制台會自動將必要權限授予叢集服務帳戶。

如要使用 gcloud CLI 授予存取權，請按照下列步驟操作：

gcloud

如要使用 gcloud CLI，您可以安裝並初始化 Google Cloud CLI，也可以使用 Cloud Shell。

  1. 開啟 gcloud CLI。如果尚未安裝 gcloud CLI，請安裝並初始化 gcloud CLI，或使用 Cloud Shell。

  2. 請執行 gcloud beta alloydb clusters describe 指令。

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

    更改下列內容：

    • CLUSTER：AlloyDB 叢集 ID。
    • REGION：AlloyDB 叢集的位置，例如 asia-east1、us-east1。如要查看完整的區域清單，請前往「AlloyDB 位置」。

    輸出內容包含 serviceAccountEmail 欄位，也就是這個叢集的服務帳戶。您也可以在「Cluster overview」(叢集總覽) 頁面中找到服務帳戶。

  3. 授予必要權限。詳情請參閱「使用 IAM 控管資源存取權」。

    如果叢集服務帳戶不具備必要權限，對 BigQuery 資料表執行查詢時，會出現下列錯誤：

    • The user does not have bigquery.readsessions.create permissions
    • Permission bigquery.tables.get denied on table
    • Permission bigquery.tables.getData denied on table

設定擴充功能

如要設定擴充功能，請按照下列步驟操作：

控制台

  1. 前往「Clusters」(叢集) 頁面。

    前往叢集

  2. 按一下要使用的叢集 ID。

  3. 在導覽選單中，點選「AlloyDB Studio」。

  4. 登入資料庫。

  5. 在「Explorer」窗格中，展開相關結構定義。

  6. 按一下「BigQuery Tables」(BigQuery 資料表) 旁的「Actions」(動作) 選單 ，然後點選「Connect BigQuery table」(連結 BigQuery 資料表)。

  7. 在「Connect BigQuery table」(連結 BigQuery 資料表) 窗格中，選擇來源專案、來源資料集和資料表。

  8. 「Review and select columns」(查看及選取資料欄) 表格會顯示所選資料表的資料欄。選取要對應的資料欄。

  9. 在「Table name」(資料表名稱) 欄位中，輸入外部資料表的名稱。

  10. 選用：按一下「查看 SQL 指令」，即可查看生成的指令。

  11. 按一下「連結資料表」。對話方塊會顯示進度。程序完成後，您就能像查詢 AlloyDB 中的任何資料表一樣，查詢這個資料表。

psql

  1. 建立擴充功能。

    1. 按照「將 psql 用戶端連線至執行個體」中的操作說明，使用 psql 用戶端連線至 AlloyDB 執行個體。您也可以使用 AlloyDB Studio。詳情請參閱「使用 Google Cloud 控制台管理資料」。

    2. 執行下列指令：

      CREATE EXTENSION bigquery_fdw;

  2. 建立外部伺服器，定義遠端 BigQuery 資料集的連線參數。

    CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw
  OPTIONS (runtime_project 'RUNTIME_PROJECT_ID');

    更改下列內容：

    • BIGQUERY_SERVER_NAME：外部伺服器的專屬 ID。在特定資料庫中定義一次即可。您可以將 BIGQUERY_SERVER_NAME 替換為伺服器名稱。
    • RUNTIME_PROJECT_ID：選用。處理查詢並產生運算費用的 Google Cloud專案 ID。如果省略這個 ID，查詢費用會計入儲存資料的專案。

  3. 執行 CREATE USER MAPPING 指令，建立使用者對應，將要連線至外部伺服器的本機 PostgreSQL 使用者對應至外部伺服器。

    CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;

    更改下列內容：

    • USERNAME：資料庫使用者名稱或存取外部資料表的 IAM 使用者。
    • BIGQUERY_SERVER_NAME：您建立的外部伺服器專屬 ID。

  4. 使用 CREATE FOREIGN TABLE 指令，定義與您要在 BigQuery 中存取的資料表相對應的外部資料表。這個指令可讓您定義遠端資料表的結構。外部資料表可以包含 BigQuery 來源資料表中的所有資料欄，也可以只包含部分資料欄。

    CREATE FOREIGN TABLE TABLENAME (
  COLUMN1_NAME DATA_TYPE,
  COLUMN2_NAME DATA_TYPE,
  ...
) SERVER BIGQUERY_SERVER_NAME OPTIONS (
  project 'BIGQUERY_PROJECT_ID',
  dataset 'BIGQUERY_DATASET_NAME',
  table 'BIGQUERY_TABLE_NAME',
  runtime_project 'RUNTIME_PROJECT_ID'
);

    更改下列內容：

    • TABLENAME：本機 AlloyDB 資料庫中的外部資料表名稱。
    • COLUMNX_NAME：AlloyDB 資料欄名稱。資料欄名稱必須與 BigQuery 來源資料表中的對應資料欄名稱完全一致。X 表示可以建立多個資料欄。名稱的大小寫也必須與 BigQuery 資料欄完全一致。如果 BigQuery 資料欄名稱包含大寫字母 (例如 employeeID)，AlloyDB 識別碼必須以雙引號括住 (例如 "employeeID")，才能保留混合或大寫字母。
    • DATA_TYPE：資料欄的資料類型。為外部資料表的各欄定義 DATA_TYPE 時，請確認該類型與 PostgreSQL 相容。如要進一步瞭解 BigQuery 類型的轉換方式，請參閱「資料類型對應」。
    • BIGQUERY_SERVER_NAME：您建立的外部伺服器專屬 ID。
    • BIGQUERY_PROJECT_ID：BigQuery 資料集所在的專案 ID。
    • BIGQUERY_DATASET_NAME：資料表的 BigQuery 資料集名稱。
    • BIGQUERY_TABLE_NAME：BigQuery 資料表的名稱。
    • RUNTIME_PROJECT_ID：選用。要支付查詢執行費用的 Google Cloud專案 ID。在資料表層級設定這項屬性，會覆寫伺服器層級定義的執行階段專案。

    建立外部資料表後，您就能像查詢 AlloyDB 中的任何資料表一樣，查詢這個資料表。

資料類型對應關係

請參閱下表，瞭解 BigQuery 和 AlloyDB 之間的資料類型對應關係。詳情請參閱「聯合查詢的資料類型注意事項」。

下表列出 BigQuery 和 AlloyDB 之間的資料類型對應關係。

BigQuery 資料表資料類型 建議的 PostgreSQL 外部資料表資料類型

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

詳情請參閱 PostGIS_Geography。

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N 是向量的維度。您必須在工作階段中設定 bigquery_fdw.enable_vector_downcasting 旗標。由於 AlloyDB 中的 VECTOR 類型使用 float4 類型，因此這項轉換可能會導致精確度降低。

詳情請參閱 pgvector 擴充功能。

後續步驟