管理连接

本文档介绍了如何查看、列出、共享、修改、删除 BigQuery 连接以及排查 BigQuery 连接问题。

作为 BigQuery 管理员，您可以创建和管理用于连接到服务和外部数据源的连接。BigQuery 分析师使用这些连接提交针对外部数据源的查询，而无需将数据移动或复制到 BigQuery 中。您可以创建以下类型的连接：

Amazon S3 连接
Apache Spark 连接
Blob Storage 连接
Cloud 资源连接（用于连接到 Cloud Storage 数据并实现远程函数）
Spanner 连接
Cloud SQL 连接
AlloyDB 连接

准备工作

确保您的连接正常。连接类型各异，具体取决于所连接的外部数据源。
启用 BigQuery Connection API。

启用该 API
确保您可以查看项目中的服务账号列表。BigQuery 会创建并使用服务账号连接到外部数据源。创建连接时，系统会代表您创建 Google Cloud 管理的 Identity and Access Management (IAM) 服务账号。如需查看关联到特定连接的服务账号，请查看连接详细信息。

所需的角色

如需获得管理连接所需的权限，请让您的管理员为您授予以下 IAM 角色：

查看连接详细信息：针对数据集的 BigQuery Connection User (roles/bigquery.connectionUser)
列出所有连接：针对数据集的 BigQuery Connection User (roles/bigquery.connectionUser)
共享连接：针对连接的 BigQuery Connection Admin (roles/bigquery.connectionAdmin)
修改连接：针对连接的 BigQuery Connection Admin (roles/bigquery.connectionAdmin)
删除连接：针对连接的 BigQuery Connection Admin (roles/bigquery.connectionAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

这些预定义角色包含执行本文档中的任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

查看连接详细信息：bigquery.connections.get
列出所有连接：bigquery.connections.list
修改和删除连接：bigquery.connections.update
共享连接：bigquery.connections.setIamPolicy

您也可以使用自定义角色或其他预定义角色来获取这些权限。

列出所有连接

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

连接列在项目的外部连接组中。
在探索器窗格中，点击您的项目名称 > 外部连接，查看所有连接的列表。

bq

输入 bq ls 命令并指定 --connection 标志。（可选）指定 --project_id 和 --location 标志，以标识要列出的连接的项目和位置。

bq ls --connection --project_id=PROJECT_ID --location=REGION

请替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID
REGION：连接区域

API

使用 REST API 参考文档部分中的 projects.locations.connections.list 方法。

Java

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

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

import com.google.cloud.bigquery.connection.v1.ListConnectionsRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to get list of connections
public class ListConnections {

  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";
    listConnections(projectId, location);
  }

  static void listConnections(String projectId, String location) throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      LocationName parent = LocationName.of(projectId, location);
      int pageSize = 10;
      ListConnectionsRequest request =
          ListConnectionsRequest.newBuilder()
              .setParent(parent.toString())
              .setPageSize(pageSize)
              .build();
      client
          .listConnections(request)
          .iterateAll()
          .forEach(con -> System.out.println("Connection Id :" + con.getName()));
    }
  }
}

查看连接详细信息

创建连接后，您可以获取有关连接配置的信息。配置包含您在创建转移作业时提供的值。

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

连接列在项目的外部连接组中。
在探索器窗格中，点击您的项目名称 > 外部连接 > 连接。

bq

输入 bq show 命令并指定 --connection 标志。（可选）使用连接的项目 ID 和区域限定连接 ID。

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

请替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID
REGION：连接区域
CONNECTION_I：连接 ID

API

使用 REST API 参考文档部分中的 projects.locations.connections.get 方法。

Java

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

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

import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.GetConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to get connection
public class GetConnection {

  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";
    getConnection(projectId, location, connectionId);
  }

  static void getConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionId);
      GetConnectionRequest request =
          GetConnectionRequest.newBuilder().setName(name.toString()).build();
      Connection response = client.getConnection(request);
      System.out.println("Connection info retrieved successfully :" + response.getName());
    }
  }
}

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

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

修改连接

连接会使用创建它的用户的凭据。如果您需要更改与连接关联的用户，可以更新用户的凭据。如果创建连接的用户不再与贵组织合作，这种做法非常有用。

您无法修改连接的以下元素：

连接类型
连接 ID
位置

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

连接列在项目的外部连接组中。
在探索器窗格中，点击您的项目名称 > 外部连接 > 连接。
在详细信息窗格中，要修改详细信息，请点击 修改详细信息。之后，执行以下操作：
1. 在修改连接对话框中，修改连接详细信息，包括用户凭据。
2. 点击更新连接。

bq

输入 bq update 命令并提供连接标志：--connection。您必须提供完全限定的 connection_id。

  bq update --connection --connection_type='CLOUD_SQL'
      --properties='{"instanceId" : "INSTANCE",
      "database" : "DATABASE", "type" : "MYSQL" }'
      --connection_credential='{"username":"USERNAME", "password":"PASSWORD"}'
      PROJECT.REGION.CONNECTION_ID

请替换以下内容：

INSTANCE：Cloud SQL 实例
DATABASE：数据库名称
USERNAME：Cloud SQL 数据库的用户名
PASSWORD：Cloud SQL 数据库的密码
PROJECT：Google Cloud 项目 ID
REGION：连接区域
CONNECTION_ID：连接 ID

例如，以下命令会更新 ID 为 federation-test 的项目中连接 ID 为 test-mysql 的连接。

bq update --connection --connection_type='CLOUD_SQL'
    --properties='{"instanceId" : "federation-test:us-central1:new-mysql",
    "database" : "imdb2", "type" : "MYSQL" }'
    --connection_credential='{"username":"my_username",
    "password":"my_password"}' federation-test.us.test-mysql

API

请参阅 REST API 参考文档部分中的 projects.locations.connections.patch 方法，并提供一个 connection 实例。

Java

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

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

import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.UpdateConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update connection
public class UpdateConnection {

  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";
    String description = "MY_DESCRIPTION";
    Connection connection = Connection.newBuilder().setDescription(description).build();
    updateConnection(projectId, location, connectionId, connection);
  }

  static void updateConnection(
      String projectId, String location, String connectionId, Connection connection)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionId);
      FieldMask updateMask = FieldMaskUtil.fromString("description");
      UpdateConnectionRequest request =
          UpdateConnectionRequest.newBuilder()
              .setName(name.toString())
              .setConnection(connection)
              .setUpdateMask(updateMask)
              .build();
      Connection response = client.updateConnection(request);
      System.out.println("Connection updated successfully :" + response.getDescription());
    }
  }
}

删除连接

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery

连接列在项目的外部连接组中。
在探索器窗格中，点击您的项目名称 > 外部连接 > 连接。
在详细信息窗格中，点击删除以删除该连接。
在要删除连接吗？对话中，输入 delete 以确认删除。
点击删除。

bq

输入 bq rm 命令并提供连接标志：--connection。您必须提供完全限定的 connection_id。

bq rm --connection PROJECT_ID.REGION.CONNECTION_ID

请替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID
REGION：连接区域
CONNECTION_ID：连接 ID

API

请参阅 REST API 参考文档部分中的 projects.locations.connections.delete 方法。

Java

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

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

import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.DeleteConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to delete a connection
public class DeleteConnection {

  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 connectionName = "MY_CONNECTION_NAME";
    deleteConnection(projectId, location, connectionName);
  }

  static void deleteConnection(String projectId, String location, String connectionName)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionName);
      DeleteConnectionRequest request =
          DeleteConnectionRequest.newBuilder().setName(name.toString()).build();
      client.deleteConnection(request);
      System.out.println("Connection deleted successfully");
    }
  }
}

后续步骤

了解如何使用远程函数。
了解如何使用 Apache Spark 的存储过程。

管理连接

准备工作

所需的角色

所需权限

列出所有连接

控制台

bq

API

Java

查看连接详细信息

控制台

bq

API

Java

与用户分享连接

控制台

bq

API

Java

修改连接

控制台

bq

API

Java

删除连接

控制台

bq

API

Java

后续步骤