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

Criar conexões do Spanner

Selecione uma das seguintes opções:

Console

  1. Acessar a página do BigQuery.

    Acessar o BigQuery

  2. No painel Explorer, clique em Adicionar e, em seguida, selecione Conexões com fonte de dados externa.

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

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

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

  2. No painel Explorer, clique no nome do seu projeto > Conexões externas > conexão.

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

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