连接到 Spanner

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

准备工作

启用 BigQuery Connection API。

启用 API
如需获得连接到 Spanner 所需的权限，请让您的管理员为您授予项目的 BigQuery Connection Admin (roles/bigquery.connectionAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

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

创建 Spanner 连接

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery
在 添加数据菜单中，选择连接到外部数据源。
在外部数据源窗格中，输入以下信息：
- 对于连接类型，选择 Spanner。
- 对于连接 ID，输入连接资源的标识符。允许使用字母、数字和下划线。
- 对于数据位置，选择与您的外部数据源区域兼容的 BigQuery 位置（或区域）。
- （可选）：对于易记名称，输入方便用户使用的连接名称，例如 My connection resource。易记名称可以是任何容易辨识的值，让您以后在需要修改连接资源时能够轻松识别。
- 可选：对于说明，输入此连接资源的说明。
- 对于数据库名称，请输入 Spanner 数据库的名称，格式如下： "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
- 可选：要执行并行读取，请选择并行读取数据。Spanner 可以将某些查询划分为较小部分（即分区），然后并行提取分区。如需了解详情，请参阅 Spanner 文档中的并行读取数据。此选项仅限于执行计划中第一个运算符为分布式联合运算符的查询。其他查询会返回错误。如需查看 Spanner 查询的查询执行计划，请参阅了解 Spanner 如何执行查询。
- 可选：对于数据库角色，输入 Spanner 数据库角色的名称。如果不为空，则此连接在默认情况下使用此数据库角色查询 Spanner。通过此连接提交查询的 Spanner 精细访问权限控制用户必须获得其管理员授予的此角色的访问权限，并且数据库角色必须具有外部查询中指定的所有架构对象的 SELECT 特权。如需了解精细访问权限控制，请参阅精细访问权限控制简介。
- 可选：如需启用 Data Boost，请选择 Data Boost。Data Boost 使您可以执行分析查询和数据导出操作，且对预配的 BigQuery 实例上的现有工作负载几乎没有影响。如需启用 Data Boost，请选择 Data Boost 和并行读取数据。
点击创建连接。

bq

如需创建连接，请使用带有 --connection 标志的 bq mk 命令。

bq mk --connection \
    --connection_type=CLOUD_SPANNER \
    --properties='PROPERTIES' \
    --location=LOCATION \
    --display_name='FRIENDLY_NAME' \
    --description 'DESCRIPTION' \
    CONNECTION_ID

请替换以下内容：

PROPERTIES：包含以下字段的 JSON 对象：
- "database"：连接的 Spanner 数据库
  
  指定为具有以下格式的字符串："projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"。
- "use_parallelism"：（可选）如果为 true，则此连接会执行并行读取
  
  默认值为 false。Spanner 可以将某些查询划分为较小部分（即分区），然后并行提取分区。如需了解详情，请参阅 Spanner 文档中的并行读取数据。此选项仅限于执行计划中第一个运算符为分布式联合运算符的查询。其他查询会返回错误。如需查看 Spanner 查询的查询执行计划，请参阅了解 Spanner 如何执行查询。
- "database_role"：（可选）如果不为空，则此连接在默认情况下使用此数据库角色查询 Spanner。通过此连接提交查询的 Spanner 精细访问权限控制用户必须获得其管理员授予的此角色的访问权限，并且数据库角色必须具有外部查询中指定的所有架构对象的 SELECT 特权。
  
  如果未指定，则连接会针对 Spanner 的 IAM 预定义角色进行身份验证，并且使用此连接运行查询的主账号必须具有 roles/spanner.databaseReader IAM 角色。
  
  如需了解精细访问权限控制，请参阅精细访问权限控制简介。
- "useDataBoost"：（可选）如果为 true，则此连接允许用户使用 Data Boost。借助 Data Boost，用户可以在与预配实例不同的独立计算容量中运行联合查询，以避免影响现有工作负载。如需启用 Data Boost，请将 "useDataBoost" 设置为 true，并将 "use_parallelism" 设置为 true。
  
  为了使用 Data Boost，使用此连接运行查询的主账号必须具有 spanner.databases.useDataBoost 权限。roles/spanner.admin 和 roles/spanner.databaseAdmin 角色默认包含此权限。
LOCATION：与您的外部数据源区域兼容的 BigQuery 位置。

CONNECTION_ID：连接资源的标识符。

连接 ID 可以包含字母、数字和下划线。如果您不提供连接 ID，BigQuery 会自动生成一个唯一 ID。

以下示例会创建一个名为 my_connection_id 的新连接资源。

bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

在 ConnectionService 服务中调用 CreateConnection 方法。

与用户共享连接

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

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

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

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

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

bq

您不能使用 bq 命令行工具共享连接。如需共享连接，请使用 Google Cloud 控制台或 BigQuery Connections API 方法共享连接。

API

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

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

后续步骤

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