Gerenciar trocas de dados no compartilhamento do BigQuery

Como administrador do BigQuery Sharing, você pode fazer o seguinte no BigQuery Sharing (antigo Analytics Hub):

  • Criar, atualizar, visualizar, compartilhar e excluir trocas de dados.
  • Criar, atualizar, excluir e compartilhar listagens.
  • Gerenciar administradores do BigQuery Sharing, administradores das listagens, editores, assinantes e leitores.

Por padrão, uma troca de dados é particular e somente usuários ou grupos que têm acesso a ela podem visualizar ou se inscrever nos dados. No entanto, se você quiser que as listagens sejam descobertas e assinadas por usuários doGoogle Cloud (allAuthenticatedUsers), solicite a que sua troca de dados se torne pública.

Antes de começar

Para começar a usar o BigQuery Sharing (antigo Analytics Hub), ative a API Analytics Hub no 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 de 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

Para criar uma troca de dados, siga estas etapas:

Console

  1. 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 atualizar o projeto e a região depois de criar a troca de dados.

  4. Em 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 na chave Registro de e-mails de assinantes. Quando você ativa essa opção, todas as listagens futuras 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 ativar a detecção pública, clique na opção Detecção pública. Quando uma troca pode ser descoberta publicamente, todas as listagens na troca são exibidas e pesquisáveis no catálogo. Se você ativar a descoberta pública, é necessário configurar as permissões de troca. Devido à herança de permissões, todos as listagens serão definidas, por padrão, com o mesmo tipo de descoberta pública da troca. Portanto, as trocas públicas não podem ter listagens privadas, mas as trocas privadas podem ter listagens públicas (por exemplo, é possível definir o tipo de descoberta pública no nível de listagem individual). O projeto em que você está criando a troca de dados precisa ter uma organização e uma conta de faturamento associadas.

  8. Clique em Criar troca.

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

    1. Insira os endereços de e-mail nos seguintes campos para conceder os 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

Use o método projects.locations.dataExchanges.create.

POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/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 locais que aceitam o compartilhamento do BigQuery (antigo Analytics Hub), 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

Para atualizar uma troca de dados, siga estas etapas:

Console

  1. Acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, clique em uma troca de dados que você quer atualizar.

  3. Acesse a guia Detalhes.

  4. Clique em Editar troca.

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

    • Nome de exibição
    • Contato principal
    • Descrição
    • 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

  6. Clique em Salvar.

API

Use o método projects.locations.dataExchanges.patch.

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

Substitua UPDATEMASK pela lista de campos que você quer atualizar. Para atualizar vários valores, use uma lista separada por vírgulas. Por exemplo, para atualizar o nome de exibição e o contato principal de uma troca de dados, insira displayName,primaryContact.

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

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

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

Para ver as trocas de dados no seu projeto ou organização a que você tem acesso, siga estas etapas:

Console

  1. Acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Confira a lista de trocas de dados no seu projeto Google Cloud . Se você tiver a permissão resourcemanager.organizations.get, também poderá conferir a lista de trocas de dados na sua organização Google Cloud .

API

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

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

Substitua:

  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local para o qual 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/location/LOCATION/dataExchanges

Substitua:

  • ORGANIZATION_ID: o ID da organização. Para mais informações, consulte Como conseguir o ID da organização.
  • LOCATION: o local para o qual você quer listar as trocas de dados.

Compartilhar uma troca de dados

Se o editor de compartilhamento do BigQuery pertencer a uma organização diferente da organização que contém a troca de dados, o editor não poderá ver sua troca de dados no Compartilhamento. Você precisa compartilhar um link para a troca de dados com o editor.

  1. Acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, clique em Mais opções.

  3. 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, é preciso definir a política do IAM para essa troca. Para mais informações sobre os papéis do usuário do IAM predefinidas, consulte Papéis do IAM de compartilhamento do BigQuery. Para fazer isso, siga estas etapas:

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. Acesse a guia Detalhes.

  4. Clique em Definir permissões.

  5. Para adicionar principais, clique em Adicionar principal.

  6. No campo Novos participantes, adicione os IDs de e-mail 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. No menu Selecionar um papel, escolha Analytics Hub e selecione um dos seguintes papéis do Identity and Access Management (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. Leia a política atual com o método getIamPolicy da ficha da empresa usando 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 BigQuery Sharing (antigo Analytics Hub) retorna a política atual.

  2. Para adicionar ou remover membros e os papéis do Identity and Access Management (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@example.com
    • serviceAccount:test123@example.domain.com
    • domain:example.domain.com

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

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

  3. Grave a política atualizada usando 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

    No corpo da solicitação, forneça os detalhes da ficha. Se a solicitação for bem-sucedida, o corpo da resposta conterá detalhes da ficha.

Criar administradores de compartilhamento do BigQuery

Para gerenciar trocas 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.

Se você quiser que os administradores gerenciem todas as trocas de dados em um projeto, conceda o papel de administrador do Analytics Hub nesse projeto.

Se você quiser que os administradores gerenciem uma troca de dados específica, conceda o papel de administrador do Analytics Hub para essa troca de dados.

Tornar uma troca de dados pública

Por padrão, uma troca de dados é particular e somente usuários ou grupos que têm acesso a essa troca podem visualizar ou se inscrever nas listagens. No entanto, é possível optar por tornar pública uma troca de dados. As listagens em trocas de dados públicos podem ser descobertas e assinadas por usuários doGoogle Cloud (allAuthenticatedUsers).

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

  1. Para permitir que allAuthenticatedUsers visualize as listagens, conceda aos usuários o papel de Leitor do Analytics Hub (roles/analyticshub.viewer) no nível da troca de dados.

  2. Para permitir que allAuthenticatedUsers se inscreva nas listagens, conceda aos usuários o papel de assinante do Analytics Hub (roles/analyticshub.subscriber) no nível da troca de dados.

  3. Ative a descoberta pública ao criar ou atualizar uma troca de dados. Especifique as configurações quando você torna pública uma troca de dados.

Excluir uma troca de dados

Quando uma troca de dados é excluída, todas as listagens nela também são excluídas. No entanto, os conjuntos de dados compartilhados e vinculados não são excluídos. Além disso, quando um projeto é excluído, as trocas de dados nele não são excluídas. É necessário excluir essas trocas de dados antes de excluir o projeto. Se você excluir uma troca de dados, não poderá desfazer essa ação.

Antes de excluir uma troca de dados, siga estas etapas com base na configuração dela:

Para excluir uma troca de dados, siga estas etapas:

Console

  1. Acesse a página Compartilhamento (Analytics Hub).

    Acessar Compartilhamento (Analytics Hub)

  2. Na lista de trocas de dados, clique na troca de dados que você quer excluir.

  3. Acesse a guia Detalhes.

  4. Clique em Excluir troca.

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

  6. Clique em Excluir.

API

Use o método projects.locations.dataExchanges.delete.

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

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