Conecte-se ao Cloud SQL

Como administrador do BigQuery, é possível criar uma conexão para acessar dados do Cloud SQL. Com essa conexão, os analistas de dados podem consultar dados no Cloud SQL. Para se conectar ao Cloud SQL, siga estas etapas:

  1. Criar uma conexão do Cloud SQL
  2. Conceda acesso ao agente de serviço de conexão do BigQuery.

Antes de começar

  1. Selecione o projeto que contém o banco de dados do Cloud SQL.

    Acessar o seletor de projetos

  2. Ative a API BigQuery Connection.

    Ativar a API

  3. Verifique se a instância do Cloud SQL tem uma conexão IP pública ou uma conexão particular:

    • Para proteger as instâncias do Cloud SQL, adicione a conectividade do IP público sem um endereço autorizado. Isso torna a instância inacessível na Internet pública, mas acessível para consultas do BigQuery.

    • Para permitir que o BigQuery acesse dados do Cloud SQL por uma conexão particular, configure a conectividade do IP privado para uma instância nova ou atual do Cloud SQL e marque a caixa de seleção Caminho particular para serviços do Google Cloud. Esse serviço usa um caminho direto interno em vez do endereço IP particular dentro da nuvem privada virtual.

  4. Para receber as permissões necessárias para criar uma conexão do Cloud SQL, peça ao administrador para conceder a você o papel do IAM 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 Cloud SQL

Como prática recomendada, use conexões para gerenciar as credenciais do banco de dados ao se conectar com o Cloud SQL. As conexões são criptografadas e armazenadas com segurança no serviço de conexão do BigQuery. Se as credenciais do usuário forem válidas para outros dados na origem, a conexão poderá ser reutilizada. Por exemplo, você pode usar uma conexão para consultar vários bancos de dados que residem na mesma instância do Cloud SQL.

Selecione uma das seguintes opções para criar uma conexão do Cloud SQL:

Console

  1. Acessar a página do BigQuery.

    Ir para o BigQuery

  2. No painel Explorer, clique em Adicionar.

  3. Na caixa de diálogo Adicionar, clique em Conexões com fontes de dados externas:

  4. No painel Fonte de dados externa, insira as seguintes informações:

    • Em Tipo de conexão, selecione o tipo de origem, por exemplo, MySQL ou Postgres.
    • Em ID da conexão, insira um identificador para o recurso de conexão. Letras, números e sublinhados são permitidos. Por exemplo, bq_sql_connection.
    • Em Local da conexão, selecione um local (ou região) do BigQuery 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.
    • Opcional: Criptografia. Se você quiser usar uma chave de criptografia gerenciada pelo cliente (CMEK) para criptografar suas credenciais, selecione Chave de criptografia gerenciada pelo cliente (CMEK) e selecione uma chave desse tipo. Caso contrário, suas credenciais estarão protegidas pela chave padrão gerenciada pelo Google.
    • Se você escolheu MySQL ou Postgres do Cloud SQL no tipo de conexão, em Nome da conexão do Cloud SQL, digite por completo o Nome da instância do Cloud SQL, geralmente no formato project-id:location-id:instance-id. Encontre o ID da instância na página de detalhes da instância do Cloud SQL que você quer consultar.
    • Em Nome do banco de dados, insira o nome do banco de dados.
    • Em Nome de Usuário do banco de dados, insira o nome de usuário para o banco de dados.

    • Em Senha do banco de dados, insira a senha do banco de dados.

      • Opcional: para ver a senha, clique em Mostrar senha.

  5. Clique em Criar conexão.

  6. Clique em Ir para conexão.

  7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa seguinte.

bq

Insira o comando bq mk e forneça a sinalização de conexão: --connection. As sinalizações abaixo também são obrigatórias:

  • --connection_type
  • --properties
  • --connection_credential
  • --project_id
  • --location

As sinalizações a seguir são opcionais:

  • --display_name O nome amigável da conexão.
  • --description Uma descrição da conexão.

O connection_id é um parâmetro opcional que pode ser adicionado como o último argumento do comando usado internamente para armazenamento. Se um ID de conexão não for fornecido, um ID exclusivo será gerado automaticamente. O connection_id pode conter letras, números e sublinhados.

    bq mk --connection --display_name='friendly name' --connection_type=TYPE \
      --properties=PROPERTIES --connection_credential=CREDENTIALS \
      --project_id=PROJECT_ID --location=LOCATION \
      CONNECTION_ID

Substitua:

  • TYPE: o tipo da fonte de dados externa.
  • PROPERTIES: os parâmetros da conexão criada no formato JSON. Por exemplo, --properties='{"param":"param_value"}'. Para criar um recurso de conexão, é necessário fornecer os parâmetros instanceID, database e type.
  • CREDENTIALS: os parâmetros username e password.
  • PROJECT_ID: o ID do projeto;
  • LOCATION: a região em que a instância do Cloud SQL está localizada.
  • CONNECTION_ID: o identificador de conexão.

Por exemplo, o comando abaixo cria um novo recurso de conexão chamado my_new_connection (nome amigável: "Minha nova conexão") em um projeto com o ID federation-test.

bq mk --connection --display_name='friendly name' --connection_type='CLOUD_SQL' \
  --properties='{"instanceId":"federation-test:us-central1:mytestsql","database":"mydatabase","type":"MYSQL"}' \
  --connection_credential='{"username":"myusername", "password":"mypassword"}' \
  --project_id=federation-test --location=us my_connection_id

API

Na API do BigQuery Connection, é possível invocar CreateConnection no ConnectionService para instanciar uma conexão. Consulte a página da biblioteca de cliente para mais detalhes.

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.CloudSqlCredential;
import com.google.cloud.bigquery.connection.v1.CloudSqlProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to create a connection with cloud MySql database
public class CreateConnection {

  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 database = "MY_DATABASE";
    String instance = "MY_INSTANCE";
    String instanceLocation = "MY_INSTANCE_LOCATION";
    String username = "MY_USERNAME";
    String password = "MY_PASSWORD";
    String instanceId = String.format("%s:%s:%s", projectId, instanceLocation, instance);
    CloudSqlCredential cloudSqlCredential =
        CloudSqlCredential.newBuilder().setUsername(username).setPassword(password).build();
    CloudSqlProperties cloudSqlProperties =
        CloudSqlProperties.newBuilder()
            .setType(CloudSqlProperties.DatabaseType.MYSQL)
            .setDatabase(database)
            .setInstanceId(instanceId)
            .setCredential(cloudSqlCredential)
            .build();
    Connection connection = Connection.newBuilder().setCloudSql(cloudSqlProperties).build();
    createConnection(projectId, location, connectionId, connection);
  }

  static void createConnection(
      String projectId, String location, String connectionId, Connection connection)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      LocationName parent = LocationName.of(projectId, location);
      CreateConnectionRequest request =
          CreateConnectionRequest.newBuilder()
              .setParent(parent.toString())
              .setConnection(connection)
              .setConnectionId(connectionId)
              .build();
      Connection response = client.createConnection(request);
      System.out.println("Connection created successfully :" + response.getName());
    }
  }
}

Conceder acesso ao agente de serviço

Um agente de serviço é criado automaticamente quando você cria a primeira conexão com o Cloud SQL no projeto. O nome do agente de serviço é Agente de serviço de conexão do BigQuery. Para conferir o ID do agente de serviço, confira os detalhes da conexão. O ID do agente de serviço tem o seguinte formato:

service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com

Para se conectar ao Cloud SQL, conceda à nova conexão acesso somente de leitura ao Cloud SQL para que o BigQuery possa acessar arquivos em nome de usuários. O agente de serviço precisa ter as seguintes permissões:

  • cloudsql.instances.connect
  • cloudsql.instances.get

É possível conceder ao agente de serviço associado à conexão o papel do IAM de cliente do Cloud SQL (roles/cloudsql.client), que tem essas permissões atribuídas. Pule as etapas a seguir se o agente de serviço já tiver as permissões necessárias.

Console

  1. Acesse a página IAM e administrador.

    Acessar IAM e administrador

  2. Clique em Conceder acesso.

    A caixa de diálogo Adicionar principais é aberta.

  3. No campo Novos principais, insira o nome do agente de serviço Agente de serviço de conexão do BigQuery ou o ID do agente de serviço retirado das informações de conexão.

  4. No campo Selecionar um papel, selecione Cloud SQL e, em seguida, selecione Cliente do Cloud SQL.

  5. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_AGENT_ID --role=roles/cloudsql.client

Forneça os valores a seguir:

  • PROJECT_ID pelo ID do projeto no Google Cloud.
  • SERVICE_AGENT_ID: o ID do agente de serviço extraído das informações de conexão.

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