Como trabalhar com conexões

Visão geral

A federação BigQuery Cloud SQL permite que o BigQuery consulte dados que residem no Cloud SQL em tempo real, sem copiar ou mover dados. A federação de consulta aceita instâncias do MySQL (segunda geração) e do PostgreSQL no Cloud SQL.

Após a configuração inicial realizada uma única vez para criar um recurso de conexão no BigQuery, execute as seguintes tarefas:

Criar um recurso de conexão

Consulte instruções detalhadas para configurar um recurso de conexão em Como configurar conexões de banco de dados do Cloud SQL.

Consultar um recurso de conexão

Depois de estabelecer conexão com uma instância do Cloud SQL, é possível executar consultas federadas com uma nova função: EXTERNAL_QUERY(). Consulte Sintaxe da consulta federada para mais informações e exemplos de consultas.

Consultar outro banco de dados por meio do mesmo recurso de conexão

Ao criar uma conexão com uma instância do Cloud SQL, você especifica um banco de dados, um nome de usuário e uma senha nessa instância. Se as mesmas credenciais de usuário forem válidas para outros bancos de dados na instância do Cloud SQL, esse usuário poderá consultar esses bancos de dados por meio do mesmo recurso de conexão.

Receber informações sobre um recurso de conexão

Depois de criar um recurso de conexão, será possível receber informações sobre a configuração do recurso de conexão. A configuração inclui os valores que você forneceu quando criou a transferência.

Permissões exigidas

Para receber informações sobre um recurso de conexão, é necessário ter a permissão bigquery.connections.get. Os seguintes papéis predefinidos de gerenciamento de identidade e acesso (IAM) já incluem a permissão bigquery.connections.get:

  • bigquery.admin
  • bigquery.connection.admin
  • bigquery.connection.user

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

Como visualizar um recurso de conexão

Console

  1. Para ver o status dos recursos de conexão, acesse a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. Os recursos de conexão serão listados no nível superior do projeto, em um grupo denominado Conexões externas. Clique em uma conexão para ver informações sobre esse recurso de conexão, como connection ID e Cloud SQL instance ID.

    Ver recursos de conexão

bq

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

    bq show --connection project.location.connection_id

Por exemplo, o comando a seguir recebe informações sobre um recurso de conexão chamado my_new_connection em um projeto com o ID federation-test localizado na região us.

    bq show --connection federation-test.us.my_new_connection

API

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

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

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

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

Listar todos os recursos de conexão

Permissões exigidas

Para listar todos os recursos de conexão em um projeto, é preciso ter as permissões bigquery.connections.list. Os seguintes papéis predefinidos do Cloud IAM já incluem a permissão bigquery.connections.list:

  • bigquery.admin
  • bigquery.connection.admin
  • bigquery.connection.user

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

Como listar recursos de conexão

Para listar todos os recursos de conexão em um projeto:

Console

  1. Para visualizar o status de um recurso de conexão, acesse a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. Os recursos de conexão serão listados no nível superior do projeto, em um grupo denominado Conexões externas.

    Ver recursos de conexão

bq

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

    bq ls --connection --project_id=[project_id] --location=[location]

Por exemplo, o comando a seguir lista os recursos de conexão em um projeto com o ID federation-test localizado na região us.

    bq ls --connection --project_id=bigquery-federation-test --location=us

API

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

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

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

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

Compartilhar um recurso de conexão

Permissões necessárias

Para permitir que outro usuário utilize um recurso de conexão para consultas federadas do Cloud SQL, o usuário bigquery.admin pode conceder os dois papéis diferentes no IAM.

Usuário de conexão do BigQuery

O papel bigquery.connection.user é voltado a usuários que precisam executar consultas com o recurso de conexão.

Esse papel do IAM inclui as permissões a seguir:

  • bigquery.connections.get
  • bigquery.connections.list
  • bigquery.connections.use
  • bigquery.connections.getIamPolicy

Administrador de conexão do BigQuery

O papel bigquery.connection.admin é destinado a usuários que precisam gerenciar recursos de conexão.

Esse papel do IAM inclui as mesmas permissões de bigquery.connection.user, além de outras permissões para criar, atualizar e excluir recursos de conexão existentes, bem como para definir a política do IAM em recursos de conexão.

  • bigquery.connections.create
  • bigquery.connections.update
  • bigquery.connections.setIamPolicy
  • bigquery.connections.delete

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

Como compartilhar um recurso de conexão

Console

  1. Para compartilhar um recurso de conexão, acesse a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. Os recursos de conexão serão listados no nível superior do projeto, em um grupo denominado Conexões externas. Clique em uma conexão para ver informações sobre esse recurso de conexão.

    Ver recursos de conexão

  3. Clique no botão COMPARTILHAR CONEXÃO para ver o painel de permissões desse recurso de conexão.

    Botão

  4. No painel Permissões de conexão, os usuários com o papel Administrador do BigQuery ou Administrador de conexão do BigQuery podem compartilhar o recurso de conexão com outros usuários. Para isso, precisam adicionar ou editar as permissões desses usuários.

    Compartilhar recursos de conexão

  5. Clique em Concluído.

bq

Atualmente, não é possível compartilhar um recurso com a ferramenta de linha de comando bq. Para compartilhar um recurso de conexão, use o Console do 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 essa amostra, siga as instruções de configuração para 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.

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

  public 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 ou atualizar um recurso de conexão

Depois de adicionar o recurso de conexão, é possível editá-lo. É possível editar a maioria dos campos preenchidos durante a criação do recurso de conexão, incluindo as credenciais de nome de usuário.

Uma conexão usa as credenciais do usuário que a criou. Se você precisar alterar o usuário vinculado a um recurso de 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 um recurso de conexão:

  • Tipo de conexão
  • ID da conexão
  • Local

Permissões exigidas

A atualização de um recurso de conexão requer a permissão bigquery.connections.update.

Os seguintes papéis predefinidos do Cloud IAM já incluem a permissão bigquery.connections.update:

  • bigquery.admin
  • bigquery.connection.admin

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

Como editar um recurso de conexão

Para editar uma conexão:

Console

  1. No Console do Cloud, acesse a página do BigQuery.

    Acesse a página do BigQuery

  2. Os recursos de conexão serão listados no nível superior do projeto, em um grupo denominado Conexões externas. Clique em uma conexão para ver informações sobre esse recurso de conexão.

    Ver recursos de conexão

  3. Clique no botão EDITAR CONEXÃO para ver o painel de edição do recurso de conexão.

    Botão

  4. Edite qualquer um dos campos exibidos, incluindo as credenciais do usuário.

    Editar recurso de conexão

  5. Clique em Salvar.

bq

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

    bq update --connection --connection_type='CLOUD_SQL'
   --properties='{"instanceId" : "instance",
   "database" : "db", "type" : "MYSQL" }'
   --connection_credential='{"username":"u", "password":"p"}'
   project.location.connection_id

Por exemplo, o comando a seguir atualiza os recursos de 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 do recurso connection.

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

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

  public 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 um recurso de conexão

É possível excluir um recurso de conexão se tiver as permissões corretas para fazer isso.

Permissões exigidas

A exclusão de um recurso de conexão requer a permissão bigquery.connections.delete.

Os seguintes papéis predefinidos do Cloud IAM já incluem a permissão bigquery.connections.delete:

  • bigquery.admin
  • bigquery.connection.admin

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

Como excluir um recurso de conexão

Para excluir uma conexão:

Console

  1. No Console do Google Cloud, acesse a página do BigQuery.

    Acesse a página do BigQuery

  2. Os recursos de conexão serão listados no nível superior do projeto, em um grupo denominado Conexões externas. Clique em uma conexão para ver informações sobre esse recurso de conexão.

    Ver recursos de conexão

  3. Clique no botão EXCLUIR CONEXÃO para ver o painel de exclusão desse recurso de conexão.

    Botão

  4. Na caixa de diálogo Excluir conexão?, digite delete para confirmar sua intenção.

    Excluir recurso de conexão

  5. 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.location.connection_id

Por exemplo, o comando a seguir atualiza os recursos de conexão em um projeto com o ID federation-test e o ID de conexão test-mysql.

    bq rm --connection federation-test.us.test-mysql

API

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

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

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

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