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, você poderá executar 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, na sigla em inglês) 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 visualizar o status de seus recursos de conexão, acesse a IU da Web do BigQuery.

    Acesse a IU da Web 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.

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 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 IU da Web do BigQuery.

    Acesse a IU da Web 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.

Compartilhar um recurso de conexão

Permissões exigidas

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 IU da Web do BigQuery.

    Acesse a IU da Web 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 Done.

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 a IU da Web do BigQuery 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.

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 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 IU da Web do BigQuery.

    Acesse a IU da Web 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 Save.

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.

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 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 IU da Web do BigQuery.

    Acesse a IU da Web 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.