Faça a gestão das associações

Este documento descreve como ver, listar, partilhar, editar, eliminar e resolver problemas de uma ligação ao BigQuery.

Como administrador do BigQuery, pode criar e gerir associações que são usadas para estabelecer ligação a serviços e origens de dados externas. Os analistas do BigQuery usam estas ligações para enviar consultas em origens de dados externas sem mover nem copiar dados para o BigQuery. Pode criar os seguintes tipos de associações:

Para criar uma associação predefinida para um projeto, consulte a vista geral da associação predefinida.

Antes de começar

Funções necessárias

Para receber as autorizações de que precisa para gerir as associações, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Para obter informações sobre as funções necessárias para criar e usar uma associação predefinida, consulte o artigo Funções e autorizações necessárias.

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas descritas neste documento. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

  • Veja os detalhes da associação: bigquery.connections.get
  • Listar todas as associações: bigquery.connections.list
  • Edite e elimine uma associação: bigquery.connections.update
  • Partilhe uma associação: bigquery.connections.setIamPolicy

Apresente todas as associações

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

    As associações são apresentadas no seu projeto, num grupo denominado Associações externas.

  2. No painel Explorador, clique no nome do projeto > Ligações externas para ver uma lista de todas as ligações.

bq

Introduza o comando bq ls e especifique a flag --connection. Opcionalmente, especifique as flags --project_id e --location para identificar o projeto e a localização das associações a apresentar.

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

Substitua o seguinte:

API

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

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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()));
    }
  }
}

Veja detalhes da associação

Depois de criar uma associação, pode obter informações sobre a configuração da associação. A configuração inclui os valores que forneceu quando criou a transferência.

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

    As associações são apresentadas no seu projeto, num grupo denominado Associações externas.

  2. No painel Explorador, clique no nome do projeto > Ligações externas > ligação.

bq

Introduza o comando bq show e especifique a flag --connection. Opcionalmente, qualifique o ID da associação com o ID do projeto e a região da associação.

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

Substitua o seguinte:

API

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

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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());
    }
  }
}

Partilhe uma ligação com os utilizadores

Pode conceder as seguintes funções para permitir que os utilizadores consultem dados e geram ligações:

  • roles/bigquery.connectionUser: permite que os utilizadores usem associações para estabelecer ligação a origens de dados externas e executar consultas nas mesmas.

  • roles/bigquery.connectionAdmin: permite que os utilizadores geram associações.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

    As associações são apresentadas no seu projeto, num grupo denominado Associações externas.

  2. No painel Explorador, clique no nome do projeto > Ligações externas > ligação.

  3. No painel Detalhes, clique em Partilhar para partilhar uma associação. Depois, faça o seguinte:

    1. Na caixa de diálogo Autorizações de ligação, partilhe a ligação com outros responsáveis adicionando ou editando responsáveis.

    2. Clique em Guardar.

bq

Não pode partilhar uma ligação com a ferramenta de linhas de comando bq. Para partilhar uma associação, use a Google Cloud consola ou o método da API BigQuery Connections para partilhar uma associação.

API

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

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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");
    }
  }
}

Edite uma associação

Uma associação usa as credenciais do utilizador que a criou. Se precisar de alterar o utilizador associado a uma ligação, pode atualizar as credenciais do utilizador. Isto é útil se o utilizador que criou a associação já não fizer parte da sua organização.

Não pode editar os seguintes elementos de uma associação:

  • Tipo de ligação
  • ID de ligação
  • Localização

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

    As associações são apresentadas no seu projeto, num grupo denominado Associações externas.

  2. No painel Explorador, clique no nome do projeto > Ligações externas > ligação.

  3. No painel Detalhes, para editar detalhes, clique em Editar detalhes. Depois, faça o seguinte:

    1. Na caixa de diálogo Editar associação, edite os detalhes da associação, incluindo as credenciais do utilizador.

    2. Clique em Atualizar associação.

bq

Introduza o comando bq update e forneça a marca de ligaçã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 o seguinte:

  • INSTANCE: a instância do Cloud SQL
  • DATABASE: o nome da base de dados
  • USERNAME: o nome de utilizador da sua base de dados do Cloud SQL
  • PASSWORD: a palavra-passe da sua base de dados do Cloud SQL
  • PROJECT: o Google Cloud ID do projeto
  • REGION: a região de associação
  • CONNECTION_ID: o ID de ligação

Por exemplo, o comando seguinte atualiza a associação num projeto com o ID federation-test e o ID da associaçã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 secção de referência da API REST e forneça uma instância de connection.

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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());
    }
  }
}

Elimine uma associação

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

    As associações são apresentadas no seu projeto, num grupo denominado Associações externas.

  2. No painel Explorador, clique no nome do projeto > Ligações externas > ligação.

  3. No painel Detalhes, clique em Eliminar para eliminar a associação.

  4. Na caixa de diálogo Eliminar ligação?, introduza delete para confirmar a eliminação.

  5. Clique em Eliminar.

bq

Introduza o comando bq rm e forneça a marca de ligação: --connection. O connection_id totalmente qualificado é obrigatório.

bq rm --connection PROJECT_ID.REGION.CONNECTION_ID

Substitua o seguinte:

API

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

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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");
    }
  }
}

O que se segue?