Esta página foi traduzida pela API Cloud Translation.

Conectar ao Spanner

Como administrador do BigQuery, é possível criar uma conexão para acessar dados do Spanner. Com essa conexão, os analistas de dados podem consultar dados no Spanner.

Antes de começar

Ative a API BigQuery Connection.

Ativar a API
Para receber as permissões necessárias para se conectar ao Spanner, peça ao administrador para conceder a você o papel do IAM de Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

Criar conexões do Spanner

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Acessar o BigQuery
No painel Explorer, clique em Adicionar e, em seguida, selecione Conexões com fonte de dados externa.
No painel Fonte de dados externa, insira as seguintes informações:
- Em Tipo de conexão, selecione Cloud Spanner.
- Em ID da conexão, insira um identificador para o recurso de conexão. Letras, números e sublinhados são permitidos.
- Em Tipo de local, selecione um local (ou região) do BigQuery que seja compatível com a região da fonte de dados externa.
- (Opcional) Em Nome amigável, insira um nome fácil de usar para a conexão, como My connection resource. O nome amigável pode ser qualquer valor que ajude você a identificar o recurso de conexão se precisar modificá-lo mais tarde.
- (Opcional) Em Descrição, insira uma descrição para este recurso de conexão.
- Em Nome do banco de dados, digite o nome do banco de dados do Spanner no seguinte formato: "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
- Opcional: para executar leituras paralelas, selecione Ler dados em paralelo. O Spanner pode dividir algumas consultas em partes menores, ou partições, e buscar as partições em paralelo. Para mais informações, consulte Ler dados em paralelo na documentação do Spanner. Essa opção é restrita a consultas em que o primeiro operador no plano de execução é um operador de união distribuída. Outras consultas retornam um erro. Para acessar o plano de execução de uma consulta do Spanner, consulte Noções básicas sobre como o Spanner executa consultas.
- Opcional: em Papel do banco de dados, insira o nome de um papel do banco de dados do Spanner. Se não estiver vazio, essa conexão consulta o Spanner usando esse papel de banco de dados por padrão. Os usuários do controle de acesso detalhado do Spanner que enviam consultas por essa conexão precisam ter acesso concedido a esse papel pelo administrador, e o papel de banco de dados precisa ter o privilégio SELECT em todos os objetos de esquema especificados em consultas externas. Consulte informações em Sobre controle de acesso detalhado.
- Opcional: para ativar o Data Boost, selecione Usar o Data Boost do Spanner. O Data Boost permite executar consultas de análise e exportações de dados com impacto quase zero nas cargas de trabalho da instância provisionada do BigQuery. Para ativar o Data Boost, selecione Data Boost e Ler dados em paralelo.
Clique em Criar conexão.

bq

Para criar a conexão, use o comando bq mk com a sinalização --connection.

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

Substitua:

PROPERTIES: um objeto JSON com os campos a seguir:
- "database": o banco de dados do Spanner para a conexão
  
  Especifique como uma string com o seguinte formato: "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE".
- "use_parallelism": (Opcional) se true, essa conexão executa leituras paralelas
  
  O valor padrão é false. O Spanner pode dividir algumas consultas em partes menores, ou partições, e buscar as partições em paralelo. Para mais informações, consulte Ler dados em paralelo na documentação do Spanner. Essa opção é restrita a consultas em que o primeiro operador no plano de execução é um operador de união distribuída. Outras consultas retornam um erro. Para acessar o plano de execução de uma consulta do Spanner, consulte Noções básicas sobre como o Spanner executa consultas.
- "database_role" (opcional): se não estiver vazio, essa conexão consulta o Spanner usando esse papel de banco de dados por padrão. Os usuários do controle de acesso detalhado do Spanner que enviam consultas por essa conexão precisam ter acesso concedido a esse papel pelo administrador, e o papel de banco de dados precisa ter o privilégio SELECT em todos os objetos de esquema especificados em consultas externas.
  
  Se não for especificado, a conexão será autenticada com papéis predefinidos do IAM para o Spanner, e as principais consultas em execução com essa conexão precisarão ter o papel roles/spanner.databaseReader do IAM.
  
  Consulte informações em Sobre controle de acesso detalhado.
- "useDataBoost" (opcional): se true, essa conexão permite que os usuários usem o Data Boost. O Data Boost permite que os usuários executem consultas federadas em capacidade de computação separada e independente das instâncias provisionadas para evitar impacto nas cargas de trabalho. Para ativar o Data Boost, defina "useDataBoost" como true e "use_parallelism" como true.
  
  Para usar o Data Boost, a principal consulta em execução com essa conexão precisa ter recebido a permissão spanner.databases.useDataBoost. Por padrão, essa permissão está incluída nos papéis roles/spanner.admin e roles/spanner.databaseAdmin.
LOCATION: um local do BigQuery que é compatível com a região de origem de dados externa.
CONNECTION_ID: um identificador para o recurso de conexão

O código da conexão pode conter letras, números e sublinhados. Se você não fornecer um ID de conexão, o BigQuery gerará automaticamente um ID exclusivo.

O exemplo a seguir cria um novo recurso de conexão chamado 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

Chame o método CreateConnection no serviço ConnectionService.

Compartilhar conexões com os usuários

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 Salvar.

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

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

A seguir

Saiba sobre diferentes tipos de conexão.
Saiba mais sobre como gerenciar conexões.
Saiba mais sobre consultas federadas.
Saiba como consultar dados do Spanner.