Conectar-se ao AlloyDB para PostgreSQL

Como administrador do BigQuery, é possível criar uma conexão para acessar dados do AlloyDB. Essa conexão permite que os analistas de dados consultem os dados no AlloyDB.

Para se conectar ao AlloyDB, siga estas etapas:

  1. Crie uma conexão do AlloyDB.

  2. Conceder acesso à conta de serviço

Antes de começar

  1. Ative a API BigQuery Connection.

    Ativar a API

  2. Para receber as permissões necessárias para criar uma conexão do AlloyDB, 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 uma conexão do AlloyDB

Como prática recomendada, use conexões para processar credenciais de banco de dados ao se conectar ao AlloyDB. 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, é possível usar uma conexão para consultar o mesmo banco de dados em uma instância do AlloyDB várias vezes.

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

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 AlloyDB.
    • 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_alloydb_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.
    • 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.

    • Em Instância do AlloyDB, insira o URI de conexão da instância principal ou de leitura do AlloyDB com o prefixo //alloydb.googleapis.com.

      • URI de amostra: //alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID

  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 no próxima etapa para conceder as permissões de IAM corretas.

bq

Insira o comando bq mk com as seguintes sinalizações:

  bq mk \
  --connection \
  --location=LOCATION \
  --project_id=PROJECT_ID \
  --connector_configuration '{
    "connector_id": "google-alloydb",
    "asset": {
      "database": "DATABASE",
      "google_cloud_resource": "RESOURCE_PATH"
    },
    "authentication": {
      "username_password": {
        "username": "USERNAME",
        "password": {
          "plaintext": "PASSWORD"
        }
      }
    }
  }' \
  CONNECTION_ID

Substitua:

  • LOCATION: especifique uma região do conjunto de dados do BigQuery a ser combinado com os dados do AlloyDB. As consultas que usam essa conexão precisam ser executadas nessa região.
  • PROJECT_ID: insira o ID do projeto do Google Cloud.
  • DATABASE: insira o nome do banco de dados.
  • RESOURCE_PATH: insira o URI de conexão da instância primária do AlloyDB ou de leitura com o prefixo //alloydb.googleapis.com.
    • URI de amostra: //alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID
  • USERNAME: insira a senha do usuário do banco de dados.
  • PASSWORD: insira a senha do usuário do banco de dados.
  • CONNECTION_ID: insira um ID de conexão para identificar essa conexão.

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.

Conceder acesso à conta de serviço

Uma conta de serviço é criada automaticamente quando você cria a primeira conexão em um projeto. O nome da conta de serviço é BigQuery Connection Service Agent. O ID da conta de serviço tem o seguinte formato:

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

Para se conectar ao AlloyDB, você precisa conceder à nova conexão acesso ao AlloyDB para que o BigQuery possa acessar os dados em nome dos usuários. A conta de serviço precisa ter a seguinte permissão:

  • alloydb.instances.connect

Você pode conceder à conta de serviço associada à conexão o papel do IAM de cliente do AlloyDB, que já tem essa permissão atribuída. É possível omitir esta etapa se a conta de serviço já tem a permissão necessária.

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 da conta de serviço Agente de serviço de conexão do BigQuery ou o ID da conta de serviço retirado das informações de conexão.

  4. No campo Selecionar papel, escolha AlloyDB e, em seguida, Cliente AlloyDB.

  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_ACCOUNT_ID --role=roles/alloydb.client

Forneça os valores a seguir:

  • PROJECT_ID pelo ID do projeto do Google Cloud.
  • SERVICE_ACCOUNT_ID: substitua o número do projeto em service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com e use-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

Use o comando set-iam-policy a seguir:

  bq set-iam-policy RESOURCE FILE_NAME

Substitua:

  • RESOURCE: digite o nome do recurso no formato project_id.region.connection_id ou region.connection_id.
  • FILE_NAME: insira o nome de arquivo que contém a política do IAM em um formato JSON.

Para mais informações sobre o comando set-iam-policy, consulte Controlar o acesso a recursos com o IAM.

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.

A seguir