配置 AlloyDB 对 BigQuery 中实时数据的访问权限

如需直接从 AlloyDB for PostgreSQL 查询 BigQuery 中的实时分析数据，而无需运行提取、转换和加载 (ETL) 迁移，您可以配置湖仓一体联邦。湖仓一体联合可统一您的运营数据库和分析型数据仓库，让您无需维护单独的数据流水线，即可支持实时分析和交互式应用。如需了解详情，请参阅实时数据访问权限概览。

通过此集成，您可以在 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. 启用创建和连接到 AlloyDB 所需的 Cloud API。

    启用 API

  11. 在确认项目步骤中，点击下一步以确认您要更改的项目的名称。

  12. 在启用 API 步骤中，点击启用以启用以下内容：

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

    如果您计划使用与 AlloyDB 位于同一 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Service Networking API。

    如果您计划使用位于其他 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Compute Engine API 和 Cloud Resource Manager API。

所需的角色

如需向 AlloyDB 集群服务账号授予对 BigQuery 数据集的读取权限，您需要拥有以下权限。如需了解详情，请参阅为 AlloyDB 授予对 BigQuery 数据集的访问权限。

  • BigQuery Data Viewer (roles/bigquery.dataViewer) 或具有 bigquery.tables.get 和 bigquery.tables.getData 权限的任何自定义角色。针对表或视图授予此角色后，可提供从表或视图中读取数据和元数据的权限。
  • BigQuery Read Session User (roles/bigquery.readSessionUser) 或具有 bigquery.readsessions.create 和 bigquery.readsessions.getData 权限的任何自定义角色。提供创建和使用读取会话的功能。
  • BigQuery Job User (roles/bigquery.jobUser) 或具有 bigquery.jobs.create 权限的任何自定义角色。提供使用 BigQuery API 在项目中运行作业（包括查询）的权限。此角色只能在 Resource Manager 资源（项目、文件夹和组织）上授予。如果您提供单独的运行时项目，则作业会在该项目中运行，而不是在数据项目中运行。这意味着您必须在运行时项目中授予 Job User 角色。

如需访问 BigLake Metastore 表，请执行以下操作：

  • BigLake Viewer (roles/biglake.viewer) 或具有 biglake.catalogs.get、biglake.namespaces.get、biglake.tables.get 和 biglake.tables.getData 权限的任何自定义角色。提供读取 BigLake Metastore 目录、命名空间和表的权限。
  • Storage Object Viewer (roles/storage.objectViewer) 或具有 storage.objects.get 权限的任何自定义角色。提供访问 BigQuery 外部表以及读取支持 BigLake 和 BigLake Metastore 表的基础 Cloud Storage 对象的权限。必须在项目级层或存储桶级层授予。

为 AlloyDB 授予对 BigQuery 数据集的访问权限

为 Lakehouse 联合启用所需的角色和权限后，您必须向 AlloyDB 集群服务账号授予对 BigQuery 数据集的访问权限。

当您使用 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 字段，该字段是此集群的服务账号。您还可以在集群概览页面上找到服务账号。

  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. 前往集群页面。

    转到集群

  2. 点击您要使用的集群的 ID。

  3. 在导航菜单中，点击 AlloyDB Studio。

  4. 登录您的数据库。

  5. 在探索器窗格中，展开相关架构。

  6. 点击 BigQuery 表旁边的 操作菜单，然后点击连接 BigQuery 表。

  7. 在连接 BigQuery 表窗格中，选择来源项目、来源数据集和表。

  8. 查看并选择列表格会显示所选表中的列。选择要映射的列。

  9. 在表名称字段中，输入外部表的名称。

  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：外部服务器的唯一标识符。在给定数据库中定义一次。您可以将 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：您创建的外部服务器的唯一标识符。

  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：您创建的外部服务器的唯一标识符。
    • 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 扩展程序。

后续步骤