Gerenciar conexões

Neste documento, descrevemos como visualizar, listar, compartilhar, editar, excluir e resolver problemas em uma conexão do BigQuery.

Como administrador do BigQuery, é possível criar e gerenciar conexões usadas para se conectar a serviços e fontes de dados externas. Os analistas do BigQuery usam essas conexões para enviar consultas de fontes de dados externas sem mover ou copiar dados para o BigQuery. É possível criar os seguintes tipos de conexões:

Conexões do Amazon S3
Conexões do Apache Spark
Conexões de armazenamento de blobs
Conexões de recursos do Cloud para se conectar a dados do Cloud Storage e implementar funções remotas.
Conexões do Spanner
Conexões do Cloud SQL
Conexões do AlloyDB (pré-lançamento)

Antes de começar

Verifique se você tem uma conexão funcional. As conexões são específicas do tipo e dependem da fonte de dados externa conectada.
Ative a API BigQuery Connection.

Ativar a API
Verifique se é possível ver uma lista de contas de serviço no projeto. O BigQuery cria e usa uma conta de serviço para se conectar à sua fonte de dados externa. Quando você cria uma conexão, uma conta de serviço do Identity and Access Management (IAM) gerenciada pelo Google Cloud é criada em seu nome. Para ver a conta de serviço anexada a uma conexão específica, veja os detalhes da conexão.

Funções exigidas

Para conseguir as permissões necessárias para gerenciar conexões, peça ao administrador para conceder a você os papéis do IAM a seguir:

Conferir detalhes da conexão: Usuário de conexão do BigQuery (roles/bigquery.connectionUser) no seu conjunto de dados
Listar todas as conexões: Usuário de conexão do BigQuery (roles/bigquery.connectionUser) no seu conjunto de dados
Compartilhar uma conexão: Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin) na sua conexão
Editar uma conexão: Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin) na sua conexão
Excluir uma conexão: Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin) na sua conexão

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

Ver detalhes da conexão: bigquery.connections.get
Listar todas as conexões: bigquery.connections.list
Editar e excluir uma conexão: bigquery.connections.update
Compartilhar uma conexão: bigquery.connections.setIamPolicy

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Listar todas as conexões

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do projeto > Conexões externas para ver uma lista de todas as conexões.

bq

Digite o comando bq ls e especifique a sinalização --connection Se quiser, especifique as flags --project_id e --location para identificar o projeto e o local das conexões a serem listadas.

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

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud
REGION: a região de conexão

API

Use o método projects.locations.connections.list na seção de referência da API REST.

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Ver detalhes da conexão

Depois de criar uma conexão, é possível receber informações sobre a configuração da conexão. A configuração inclui os valores que você forneceu quando criou a transferência.

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Conexões externas > conexão.

bq

Digite o comando bq show e especifique a sinalização --connection. Se quiser, qualifique o ID da conexão com o ID do projeto e a região da conexão.

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud
REGION: a região de conexão
CONNECTION_I: o ID da conexão.

API

Use o método projects.locations.connections.get na seção de referência da API REST.

Java

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Você pode conceder os seguintes papéis para permitir que os usuários consultem dados e gerenciem conexões:

roles/bigquery.connectionUser: permite aos usuários usar conexões para se conectar a fontes de dados externas e executar consultas nelas.
roles/bigquery.connectionAdmin: permite que os usuários gerenciem conexões.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Conexões externas > conexão.
No painel Detalhes, clique em Compartilhar para compartilhar uma conexão. Em seguida, siga estas etapas:
1. Na caixa de diálogo Permissões de conexão, compartilhe a conexão com outros principais adicionando ou editando principais.
2. Clique em Save.

bq

Não é possível compartilhar uma conexão com a ferramenta de linha de comando bq. Para compartilhar um recurso de conexão, use o console do Google Cloud ou o método da API BigQuery Connections para compartilhar uma conexão.

API

Consulte o método projects.locations.connections.setIAM na seção de referência da API REST BigQuery Connections e forneça uma instância do recurso policy.

Java

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Editar uma conexão

Uma conexão usa as credenciais do usuário que a criou. Se você precisar alterar o usuário vinculado a uma conexão, atualize as credenciais dele. Isso será útil se o usuário que criou a conexão não estiver mais em sua organização.

Não é possível editar os seguintes elementos de uma conexão:

Tipo de conexão
ID da conexão
Local

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Conexões externas > conexão.
No painel Detalhes, clique em Editar detalhes para editar os detalhes. Em seguida, siga estas etapas:
1. Na caixa de diálogo Editar conexão, edite os detalhes da conexão, incluindo as credenciais do usuário.
2. Clique em Atualizar conexão.

bq

Insira o comando bq update e forneça a flag de conexão: --connection. O connection_id totalmente qualificado é obrigatório.

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

Substitua:

INSTANCE: a instância do Cloud SQL
DATABASE: o nome do banco de dados
USERNAME: o nome de usuário do banco de dados do Cloud SQL
PASSWORD: a senha do banco de dados do Cloud SQL
PROJECT: o ID do projeto do Google Cloud
REGION: a região de conexão
CONNECTION_ID: o ID da conexão.

Por exemplo, o comando a seguir atualiza a conexão em um projeto com o ID federation-test e o ID de conexão 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

Consulte o método projects.locations.connections.patch na seção de referência da API REST e forneça uma instância de connection.

Java

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Excluir uma conexão

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Conexões externas > conexão.
No painel Detalhes, clique em Excluir para excluir a conexão.
Na caixa de diálogo Excluir conexão?, digite delete para confirmar a exclusão.
Clique em Excluir.

bq

Insira o comando bq rm e forneça a sinalização de conexão: --connection. O connection_id totalmente qualificado é obrigatório.

bq rm --connection PROJECT_ID.REGION.CONNECTION_ID

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud
REGION: a região de conexão
CONNECTION_ID: o ID da conexão.

API

Consulte o método projects.locations.connections.delete na seção de referência da API REST.

Java

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

A seguir

Saiba como usar funções remotas.
Saiba como usar procedimentos armazenados para o Apache Spark.

Gerenciar conexões

Antes de começar

Funções exigidas

Permissões necessárias

Listar todas as conexões

Console

bq

API

Java

Ver detalhes da conexão

Console

bq

API

Java

Compartilhar uma conexão com os usuários

Console

bq

API

Java

Editar uma conexão

Console

bq

API

Java

Excluir uma conexão

Console

bq

API

Java

A seguir