连接到 AlloyDB for PostgreSQL

作为 BigQuery 管理员，您可以创建一个连接来访问 AlloyDB 数据。借助此连接，数据分析师可以查询 AlloyDB 中的数据。

如需连接到 AlloyDB，您必须执行以下步骤：

创建 AlloyDB 连接。
向服务账号授予访问权限。

准备工作

启用 BigQuery Connection API。

启用 API
如需获得创建 AlloyDB 连接所需的权限，请让您的管理员为您授予项目的 BigQuery Connection Admin (roles/bigquery.connectionAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建 AlloyDB 连接

最佳做法是连接到 AlloyDB 时使用连接处理数据库凭据。在 BigQuery 连接服务中，连接将会被加密并安全地存储。如果用户凭据对来源中的其他数据有效，则可以重复使用该连接。例如，您可以使用一个连接多次查询 AlloyDB 实例中的同一数据库。

选择以下选项之一来创建 AlloyDB 连接：

控制台

转到 BigQuery 页面。

转到 BigQuery
在浏览器窗格中，点击 添加数据。
在添加数据对话框中，点击与外部数据源的连接：
在外部数据源对话框中，输入以下信息：
- 对于连接类型，选择 AlloyDB。
- 对于连接 ID，输入连接资源的标识符。允许使用字母、数字和下划线。例如 bq_alloydb_connection。
- 对于数据位置，选择与您的外部数据源区域兼容的 BigQuery 位置（或区域）。
- 可选：对于易记名称，输入方便用户使用的连接名称，例如 My connection resource。易记名称可以是任何容易辨识的值，让您以后在需要修改连接资源时能够轻松识别。
- 可选：对于说明，输入此连接资源的说明。
- 可选：加密。如果要使用客户管理的加密密钥 (CMEK) 来加密凭据，请选择客户管理的加密密钥 (CMEK)，然后选择客户管理的密钥。否则，您的凭据受 Google 拥有且 Google 管理的默认密钥保护。
- 对于数据库名称，输入数据库的名称。
- 对于数据库用户名，输入数据库的用户名。
- 对于数据库密码，输入数据库的密码。
  - 可选：如需看到密码，请点击 显示密码。
- 对于 AlloyDB 实例，输入前缀为 //alloydb.googleapis.com 的 AlloyDB 主实例或读取实例的连接 URI。
  - 示例 URI：//alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID
  注意：如果同一用户凭据对外部数据源中的其他数据库有效，则该用户可以通过同一连接资源查询这些数据库。
点击创建连接。
点击转到连接。
在连接信息窗格中，复制服务账号 ID 以在下一步中使用，进而授予正确的 IAM 权限。

bq

输入带有以下标志的 bq mk 命令：

  bq mk \
  --connection \
  --location=LOCATION \
  --project_id=PROJECT_ID \
  --connector_configuration '{
    "connector_id": "google-alloydb",
    "asset": {
      "database": "DATABASE",
      "google_cloud_resource": "RESOURCE_PATH"
    },
    "authentication": {
      "username_password": {
        "username": "USERNAME",
        "password": {
          "plaintext": "PASSWORD"
        }
      }
    }
  }' \
  CONNECTION_ID

请替换以下内容：

LOCATION：指定要与 AlloyDB 中的数据组合的 BigQuery 数据集的区域。使用此连接的查询必须从此区域运行。
PROJECT_ID：输入您的 Google Cloud 项目 ID。
DATABASE：输入数据库名称。
RESOURCE_PATH：输入前缀为 //alloydb.googleapis.com 的 AlloyDB 主实例或读取实例的连接 URI。
- 示例 URI：//alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID
USERNAME：输入数据库用户的名称。
PASSWORD：输入数据库用户的密码。
CONNECTION_ID：输入连接 ID 以标识此连接。

API

通过 BigQuery Connection API，您可以在 ConnectionService 中调用 CreateConnection 来实例化连接。如需了解详情，请参阅客户端库页面。

向服务账号授予访问权限

当您在项目中创建第一个连接时，系统会自动创建服务账号。服务账号的名称为 BigQuery Connection Service Agent。服务账号 ID 的格式如下：

service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com。

如需连接到 AlloyDB，您必须向新的连接授予对 AlloyDB 的访问权限，以便 BigQuery 能够代表用户访问数据。该服务账号必须具有以下权限：

alloydb.instances.connect

您可以向与连接关联的服务账号授予 AlloyDB Client IAM 角色，该角色已分配此权限。如果服务账号已具有所需的权限，则可以省略此步骤。

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 授予访问权限。

系统随即会打开添加主账号对话框。
在新的主账号字段中输入服务账号名称 BigQuery Connection Service Agent 或从连接信息中提取的服务账号 ID。
在选择角色字段中选择 AlloyDB，然后选择 AlloyDB Client。
点击保存。

gcloud

使用 gcloud projects add-iam-policy-binding 命令：

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_ACCOUNT_ID --role=roles/alloydb.client

请提供以下值：

PROJECT_ID：您的 Google Cloud 项目 ID。
SERVICE_ACCOUNT_ID：替换 service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com 中的项目编号并使用它。

与用户共享连接

您可以授予以下角色，以使用户可以查询数据并管理连接：

roles/bigquery.connectionUser：允许用户使用连接与外部数据源建立连接，并对其运行查询。
roles/bigquery.connectionAdmin：允许用户管理连接。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

连接列在项目的外部连接组中。
在探索器窗格中，点击您的项目名称 > 外部连接 > 连接。
在详细信息窗格中，点击共享以共享连接。之后，执行以下操作：
1. 在连接权限对话框中，通过添加或修改主账号与其他主账号共享连接。
2. 点击保存。

bq

使用以下 set-iam-policy 命令：

  bq set-iam-policy RESOURCE FILE_NAME

请替换以下内容：

RESOURCE：以 project_id.region.connection_id 或 region.connection_id 格式输入资源名称。
FILE_NAME：以 JSON 格式输入包含 IAM 政策的文件名。

如需详细了解 set-iam-policy 命令，请参阅使用 IAM 控制对资源的访问权限。

API

使用 BigQuery Connections REST API 参考文档部分中的 projects.locations.connections.setIAM 方法，并提供一个 policy 资源的实例。

后续步骤

了解不同的连接类型。
了解如何管理连接。
了解联合查询。
了解如何查询 AlloyDB 数据。