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

本文档介绍了如何实现 湖仓联邦，借助此功能，您可以直接从 AlloyDB 查询 BigQuery 中的实时数据，而无需执行复杂的 ETL（提取、转换、加载）迁移。湖仓联邦统一了您的运营和分析数据存储区，无需使用复杂且容易出错的数据流水线。如需了解详情，请参阅实时数据访问概览。

通过集成 AlloyDB 和 BigQuery，您可以在事务型数据库和数据仓库之间实现无缝数据流，从而支持实时分析并帮助您构建强大的交互式应用。

您可以使用此集成在 AlloyDB 中运行实时访问 BigQuery 数据的查询。您可以在 AlloyDB 中的表与引用 BigQuery 数据集的外部表之间执行联接。当您需要 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.

    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.

    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 资源（项目、文件夹和组织）上授予。
  • Storage Object Viewer (roles/storage.objectViewer) 或具有 storage.objects.get 权限的任何自定义角色。提供访问 BigQuery 外部表的权限。必须在项目级层或存储桶级层授予。

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

为湖仓联邦启用所需角色和权限后，您必须为 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;

    替换以下内容：

    • BIGQUERY_SERVER_NAME：外部服务器的唯一标识符。在给定数据库中定义一次。您可以将 BIGQUERY_SERVER_NAME 替换为您的服务器名称。

  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);

    替换以下内容：

    • 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 表的名称。

    创建外部表后，您可以按照与查询 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 扩展程序。

后续步骤