Gerenciar trocas de dados

É possível usar as trocas de dados no compartilhamento do BigQuery para compartilhar conjuntos de dados com segurança entre projetos, organizações ou com o público. Como administrador de compartilhamento do BigQuery, você pode realizar as seguintes tarefas:

  • Criar, atualizar, visualizar, compartilhar e excluir trocas de dados.
  • Gerenciar permissões de acesso e papéis para trocas de dados.
  • Tornar as trocas de dados publicamente detectáveis.

Para gerenciar listagens em uma troca de dados, consulte Gerenciar listagens.

Por padrão, uma troca de dados é particular. Somente usuários ou grupos que têm acesso a uma troca podem visualizar ou se inscrever nas listagens dela. Você pode tornar sua troca de dados pública. Ao tornar sua troca de dados pública, os usuários doGoogle Cloud (allAuthenticatedUsers) podem descobrir e assinar listagens.

Antes de começar

Para começar a usar o BigQuery Sharing (antigo Analytics Hub), ative a API Analytics Hub no seu projeto Google Cloud .

Para ativar a API Analytics Hub, você precisa das seguintes permissões de gerenciamento de identidade e acesso (IAM):

  • serviceUsage.services.get
  • serviceUsage.services.list
  • serviceUsage.services.enable

O papel predefinido do IAM a seguir inclui as permissões necessárias para ativar a API Analytics Hub:

Para ativar a API Analytics Hub, selecione uma das seguintes opções:

Console

Acesse a página da API Analytics Hub e ative a API para seu Google Cloud projeto.

Ativar a API Analytics Hub

gcloud

Execute o comando gcloud services enable:

gcloud services enable analyticshub.googleapis.com

Funções exigidas

Para receber as permissões necessárias para gerenciar trocas de dados, peça ao administrador para conceder a você o papel do IAM Administrador do Analytics Hub (roles/analyticshub.admin) 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 usando papéis personalizados ou outros papéis predefinidos.

Criar uma troca de dados

Você pode criar uma troca de dados para compartilhar conjuntos de dados com pessoas, grupos ou o público em geral. Ao criar uma troca de dados, você especifica o projeto, a região, o nome de exibição e as configurações opcionais, como o registro de e-mails de assinantes e a capacidade de descoberta pública.

Para criar uma troca de dados, siga estas etapas:

Console

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Clique em Criar troca.

  3. Na caixa de diálogo Criar troca, selecione um Projeto e uma Região para a troca de dados. Não é possível mudar o projeto e a região depois de criar a troca de dados.

  4. No campo Nome de exibição, insira um nome para sua troca de dados.

  5. Opcional: insira valores nos campos a seguir:

    • Contato principal: insira o URL ou o endereço de e-mail do contato principal da troca de dados.
    • Descrição: insira uma descrição para a troca de dados.

  6. Para registrar os identificadores principais de todos os usuários que executam jobs e consultas em conjuntos de dados vinculados, clique no botão Registro de e-mails de assinantes para ativar. Quando você ativa essa configuração, todas as futuras listagens na troca de dados têm a geração de registros de e-mails de assinantes ativada. Os dados registrados estão disponíveis no campo job_principal_subject da visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE.

  7. Para tornar a troca publicamente detectável, clique no botão Detecção pública para ativar. Quando uma troca pode ser descoberta publicamente, todas as listagens nela aparecem e podem ser pesquisadas no catálogo. Considere os seguintes fatores ao ativar a capacidade de descoberta pública:

    • Herança de listagem: por padrão, todas as listagens herdam a configuração de descoberta pública da troca de dados. As trocas públicas não podem ter listagens privadas, mas as trocas privadas podem ter listagens públicas. É possível configurar o tipo de descoberta pública no nível da listagem individual.
    • Permissões: se você ativar a descoberta pública, configure as permissões de troca para conceder o papel de Leitor do Analytics Hub (roles/analyticshub.viewer) a allUsers ou allAuthenticatedUsers.
    • Requisitos do projeto: o projeto em que você cria a troca de dados precisa ter uma organização e uma conta de faturamento associadas.

  8. Para criar a troca de dados, clique em Criar troca.

  9. Opcional: na seção Permissões de troca, siga estas etapas:

    1. Nos campos a seguir, insira os endereços de e-mail para conceder papéis do Identity and Access Management (IAM):

    2. Para salvar permissões, clique em Definir permissões.

  10. Se você não tiver definido permissões para a troca de dados, clique em Pular.

API

Para criar uma troca de dados, use o método projects.locations.dataExchanges.create:

POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges?dataExchangeId=DATAEXCHANGE_ID

Substitua:

  • PROJECT_ID: o ID do projeto em que você quer criar a troca de dados.
  • LOCATION: o local da troca de dados. Para mais informações sobre regiões que aceitam o compartilhamento do BigQuery, consulte Regiões compatíveis.
  • DATAEXCHANGE_ID: o ID da sua troca de dados.

No corpo da solicitação, forneça os detalhes da troca de dados.

Se a solicitação for bem-sucedida, o corpo da resposta vai conter os detalhes da troca de dados.

Se você ativar o registro de e-mails de assinantes com o campo logLinkedDatasetQueryUserEmail, a resposta da troca de dados vai conter log_linked_dataset_query_user_email: true. Os dados registrados estão disponíveis no campo job_principal_subject da visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE.

Para mais informações sobre as tarefas que podem ser executadas em trocas de dados usando APIs, consulte Métodos projects.locations.dataExchanges.

Atualizar uma troca de dados

É possível atualizar a configuração de uma troca de dados atual, como o nome de exibição, a descrição, o contato principal e as configurações de capacidade de descoberta pública. Não é possível mudar o projeto ou a região de uma troca de dados.

Para atualizar uma troca de dados, siga estas etapas:

Console

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, selecione a que você quer atualizar.

  3. Clique na guia Detalhes.

  4. Clique em Editar troca.

  5. Na caixa de diálogo Editar troca, atualize os seguintes campos:

    • Nome de exibição: insira um novo nome de exibição.
    • Contato principal: insira um URL ou endereço de e-mail atualizado.
    • Descrição: insira uma descrição atualizada.

    • Descoberta pública: ative ou desative a descoberta pública.

      • Se você ativar a descoberta pública, conceda o papel de leitor do Analytics Hub (roles/analyticshub.viewer) para allUsers ou allAuthenticatedUsers.
      • Se você desativar a descoberta pública, remova o papel de Leitor do Analytics Hub (roles/analyticshub.viewer) de allUsers ou allAuthenticatedUsers. As trocas públicas não podem ter listagens privadas, mas as trocas privadas podem ter listagens públicas.

    • Geração de registros de e-mails de assinantes: ative ou desative essa opção.

  6. Para aplicar as alterações, clique em Salvar.

API

Para atualizar uma troca de dados, use o método projects.locations.dataExchanges.patch:

PATCH https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/DATAEXCHANGE_ID?updateMask=UPDATEMASK

Substitua:

  • PROJECT_ID: o ID do projeto que contém a troca de dados.
  • LOCATION: o local da troca de dados.
  • DATAEXCHANGE_ID: o ID da sua troca de dados.
  • UPDATEMASK: uma lista separada por vírgulas de campos que você quer atualizar (por exemplo, displayName,primaryContact).

No corpo da solicitação, especifique os valores atualizados de qualquer um dos seguintes campos:

  • displayName
  • description
  • primaryContact
  • documentation
  • icon
  • discoveryType
  • logLinkedDatasetQueryUserEmail

Para mais informações sobre esses campos, consulte Recurso: DataExchange.

Para mais informações sobre as tarefas que podem ser executadas em trocas de dados usando APIs, consulte Métodos projects.locations.dataExchanges.

Ver trocas de dados

É possível conferir a lista de trocas de dados no seu projeto ou organização do Google Cloud a que você tem permissão de acesso.

Para conferir as trocas de dados, siga estas etapas:

Console

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, confira as trocas mostradas para seu projetoGoogle Cloud . Se você tiver a permissão resourcemanager.organizations.get, também poderá ver as trocas de dados na sua organização do Google Cloud .

API

Para conferir as trocas de dados no seu projeto, use o método projects.locations.dataExchanges.list:

GET https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges

Substitua:

  • PROJECT_ID: o ID do projeto em que você quer listar trocas de dados.
  • LOCATION: o local em que você quer listar as trocas de dados.

Para ver as trocas de dados na sua organização, use o método organizations.locations.dataExchanges.list:

GET https://analyticshub.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/LOCATION/dataExchanges

Substitua:

Compartilhar uma troca de dados

Se um editor de compartilhamento do BigQuery pertencer a uma organização diferente da organização que contém a troca de dados, ele não poderá navegar nem ver sua troca de dados no compartilhamento do BigQuery. Para permitir que o editor acesse a troca de dados, copie e compartilhe um link direto.

Para compartilhar um link para uma troca de dados, siga estas etapas:

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, encontre a que você quer compartilhar e clique em Mais opções.

  3. Para copiar o link para a área de transferência, clique em Copiar link de compartilhamento.

Conceder aos usuários acesso a uma troca de dados

Para conceder aos usuários acesso a uma troca de dados, defina a política do IAM para essa troca. Para mais informações sobre os papéis de usuário predefinidos do IAM, consulte Papéis do IAM de compartilhamento do BigQuery.

Console

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Clique no nome da troca de dados para que você quer definir permissões.

  3. Clique na guia Detalhes.

  4. Clique em Definir permissões.

  5. Para adicionar principais, clique em Adicionar principal.

  6. No campo Novos participantes, digite o endereço de e-mail do principal a quem você quer conceder acesso. Você também pode usar allUsers para tornar um recurso público e acessível a todos na Internet ou allAuthenticatedUsers para torná-lo acessível apenas a usuários conectados do Google.

  7. Na lista Selecionar um papel, mantenha o ponteiro sobre o Analytics Hub e selecione um dos seguintes papéis do IAM:

    • Administrador do Analytics Hub
    • Administrador de listagens do Analytics Hub
    • Editor do Analytics Hub
    • Assinante do Analytics Hub
    • Proprietário de assinatura do Analytics Hub
    • Leitor do Analytics Hub

  8. Clique em Salvar.

API

  1. Para ler a política atual, use o método projects.locations.dataExchanges.getIamPolicy:

    POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/DATAEXCHANGE_ID:getIamPolicy

    Substitua:

    • PROJECT_ID: o ID do projeto, por exemplo, my-project-1
    • LOCATION: o local da troca de dados. Use letras minúsculas.
    • DATAEXCHANGE_ID: o ID da troca de dados.

    O compartilhamento do BigQuery retorna a política atual.

  2. Para adicionar ou remover membros e os papéis do IAM associados, edite a política com um editor de texto. Use o seguinte formato para adicionar membros:

    • user:test-user@gmail.com
    • group:admins@googlegroups.com
    • serviceAccount:server@example.gserviceaccount.com
    • domain:example.com

    Por exemplo, para conceder o papel roles/analyticshub.subscriber a group:subscribers@googlegroups.com, adicione a seguinte vinculação à política:

    {
 "members": [
   "group:subscribers@googlegroups.com"
 ],
 "role":"roles/analyticshub.subscriber"
}

  3. Para definir a política de troca de dados, use o método projects.locations.dataExchanges.setIamPolicy. No corpo da solicitação, forneça a política de IAM atualizada da etapa anterior:

    POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/DATAEXCHANGE_ID:setIamPolicy

Criar administradores de BigQuery Sharing

Para delegar o gerenciamento da troca de dados, crie administradores concedendo aos usuários o papel de administrador do Analytics Hub (roles/analyticshub.admin) no nível do projeto ou da troca de dados.

Tornar uma troca de dados pública

Por padrão, uma troca de dados é particular. Somente usuários ou grupos que têm acesso a uma troca podem visualizar ou se inscrever nas listagens dela. É possível tornar uma troca de dados pública, o que permite que usuários doGoogle Cloud (allAuthenticatedUsers) descubram e assinem as listagens dela.

Para tornar uma troca de dados pública, siga estas etapas:

  1. Para permitir que allAuthenticatedUsers veja as listagens, conceda a ele o papel de Leitor do Analytics Hub (roles/analyticshub.viewer) no nível da troca de dados.

  2. Para permitir que allAuthenticatedUsers se inscrevam nas listagens, conceda a eles o papel de assinante do Analytics Hub (roles/analyticshub.subscriber) no nível da troca de dados.

  3. Ao criar ou atualizar uma troca de dados, clique no botão Detecção pública para ativar.

Excluir uma troca de dados

Quando você exclui uma troca de dados, todas as listagens nela também são excluídas. Os conjuntos de dados compartilhados e vinculados não são excluídos. A exclusão de um projeto não exclui automaticamente as trocas de dados dele. Portanto, é necessário excluir todas as trocas de dados antes de encerrar o projeto. Não é possível desfazer a exclusão de uma troca de dados.

Antes de excluir uma troca de dados, conclua os seguintes pré-requisitos com base na configuração da troca de dados:

Para excluir uma troca de dados, siga estas etapas:

Console

  1. No console Google Cloud , acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, selecione a que você quer excluir.

  3. Clique na guia Detalhes.

  4. Clique em Excluir troca.

  5. Na caixa de diálogo Excluir troca?, confirme a exclusão digitando delete.

  6. Para excluir permanentemente a troca de dados, clique em Excluir.

API

Para excluir uma troca de dados, use o método projects.locations.dataExchanges.delete:

DELETE https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/DATAEXCHANGE_ID

Substitua:

  • PROJECT_ID: o ID do projeto que contém a troca de dados.
  • LOCATION: o local da troca de dados. Para mais informações sobre regiões que aceitam o compartilhamento do BigQuery, consulte Regiões compatíveis.
  • DATAEXCHANGE_ID: o ID da sua troca de dados.

Para mais informações sobre as tarefas que podem ser executadas em trocas de dados usando APIs, consulte Métodos projects.locations.dataExchanges.

A seguir