连接到 Spanner

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

准备工作

创建 Spanner 连接

从下列选项中选择一项:

控制台

  1. 转到 BigQuery 页面。

    转到 BigQuery

  2. 添加数据菜单中,选择连接到外部数据源

  3. 外部数据源窗格中,输入以下信息:

    • 对于连接类型,选择 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 BoostData Boost 使您可以执行分析查询和数据导出操作,且对预配的 BigQuery 实例上的现有工作负载几乎没有影响。如需启用 Data Boost,请选择 Data Boost并行读取数据
  4. 点击创建连接

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.adminroles/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 角色和权限,请参阅预定义的角色和权限

从下列选项中选择一项:

控制台

  1. 转到 BigQuery 页面。

    转到 BigQuery

    连接列在项目的外部连接组中。

  2. 探索器窗格中,点击您的项目名称 > 外部连接 > 连接

  3. 详细信息窗格中,点击共享以共享连接。之后,执行以下操作:

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

后续步骤