Usar a linhagem de dados com os sistemas do Google Cloud

Consulte a linhagem de dados para entender as relações entre os recursos do projeto e os processos que os criaram. Essas relações mostram como os recursos de dados, como tabelas e conjuntos de dados, são transformados por processos como consultas e pipelines. Neste guia, descrevemos como acessar gráficos de linhagem no catálogo universal do Dataplex, no BigQuery e na Vertex AI.

É possível conferir os detalhes da linhagem de dados no console Google Cloud ou recuperá-los usando a API Data Lineage.

Papéis e permissões

A linhagem de dados rastreia informações de linhagem automaticamente quando você ativa a API Data Lineage. Não é necessário ter funções de administrador ou editor para capturar a linhagem dos seus recursos de dados.

Para ver a linhagem de dados, você precisa de permissões específicas do Identity and Access Management (IAM). As informações de linhagem são capturadas em vários projetos, então você precisa de permissões em vários deles.

Ao visualizar a linhagem no Dataplex Universal Catalog, no BigQuery ou na Vertex AI, você precisa de permissões para acessar as informações de linhagem no projeto em que está visualizando.
Ao visualizar a linhagem registrada em outros projetos, você precisa de permissões para acessar as informações de linhagem nos projetos em que ela foi registrada.

Para receber as permissões necessárias para visualizar a linhagem de dados, peça ao administrador para conceder a você os seguintes papéis do IAM:

Leitor da linhagem de dados (roles/datalineage.viewer) no projeto em que a linhagem é registrada e no projeto em que ela é visualizada
Acessar detalhes da tabela do BigQuery: Leitor de dados do BigQuery (roles/bigquery.dataViewer) no projeto de armazenamento da tabela
Ver detalhes do job do BigQuery: Leitor de recursos do BigQuery (roles/bigquery.resourceViewer) no projeto de computação do job
Confira detalhes de outros recursos catalogados: Leitor do Dataplex Catalog (roles/dataplex.catalogViewer) no projeto em que as entradas do catálogo são armazenadas

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para ver a linhagem de dados. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para ver a linhagem de dados:

Confira os detalhes da tabela do BigQuery: bigquery.tables.get: o projeto de armazenamento da tabela
Ver detalhes do job do BigQuery: bigquery.jobs.get: o projeto de computação do job

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Tipos de visualizações de linhagem de dados

É possível conferir as informações de linhagem como um gráfico ou uma lista. O gráfico de linhagem mostra a linhagem no nível da tabela por padrão. Para jobs do BigQuery, é possível conferir a linhagem no nível da coluna nas visualizações em gráfico e em lista.

Os seguintes tipos de visualização estão disponíveis:

Visualização em gráfico: mostra a linhagem como um gráfico interativo, permitindo que você explore as relações entre recursos e colunas de dados ao expandir os nós.
Visualização em lista: mostra a linhagem em formato tabular, fornecendo representações simplificadas e detalhadas da linhagem no nível da tabela e da coluna. É possível personalizar colunas e exportar dados de linhagem dessa visualização.

Os principais elementos do gráfico são descritos da seguinte forma:

Nós: representam as entidades de dados. Na visualização no nível da tabela, um nó mostra o nome da tabela e as colunas dela. Na visualização no nível da coluna, cada nó representa uma tabela específica e as colunas dela que têm linhagem.
Bordas: as linhas que conectam nós e representam os processos que ocorrem entre eles. As bordas podem apresentar ícones ou rótulos para fornecer mais informações sobre a transformação:
- Icons: na visualização no nível da tabela, os ícones aparecem nas bordas para representar o processo de transformação. Ao analisar o gráfico manualmente, os ícones nas arestas representam o sistema de origem do processo (por exemplo, BigQuery ou Vertex AI). Se vários processos estiverem envolvidos, um ícone "vários processos" será mostrado. Se o sistema de origem do processo for desconhecido, um ícone de engrenagem será usado. Quando você aplica filtros, um ícone de engrenagem é usado para todos os processos.
- Rótulos: na visualização no nível da coluna, as arestas são rotuladas para descrever o tipo de dependência entre colunas, como Exact copy ou Other.

Ativar a linhagem de dados

Ative a linhagem de dados para começar a rastrear automaticamente as informações de linhagem dos sistemas compatíveis. Por padrão, ativar a API ativa o rastreamento de linhagem para a maioria dos serviços compatíveis. Para controlar a ingestão de linhagem do Dataproc, consulte Controlar a ingestão de linhagem de um serviço.

É necessário ativar a API Data Lineage no projeto em que você vê a linhagem e nos projetos em que ela é registrada. Para mais informações, consulte Tipos de projetos.

Para capturar informações de linhagem, siga estas etapas:
1. No console do Google Cloud , na página Seletor de projetos, selecione o projeto em que você quer registrar a linhagem.
  
  Acessar o Seletor de Projetos
2. Ative a API Data Lineage.
  
  Ativar a API Data Lineage
3. Repita as etapas anteriores para cada projeto em que você quer registrar a linhagem.
No projeto em que você vê a linhagem, ative a API Data Lineage e a API Dataplex.

Ativar as APIs

Controlar a ingestão de linhagem de dados para um serviço

Depois de ativar a API Data Lineage, o serviço inicia o rastreamento automático de linhagem para a maioria dos serviços compatíveis. Em seguida, é possível ativar ou desativar seletivamente a ingestão de linhagem para integrações específicas no nível do projeto, da pasta ou da organização. Durante o pré-lançamento, esse recurso só permite configurar a ingestão para o Dataproc. Se você desativar a ingestão de linhagem para o Dataproc, ela também será desativada para o Dataproc Serverless para Apache Spark.

A configuração é hierárquica. A configuração mais específica tem precedência. Por exemplo, uma configuração no nível do projeto substitui uma configuração no nível da pasta. Se nenhuma configuração for definida, o comportamento padrão do serviço será usado. Para o Dataproc, o padrão é Ativado.

As mudanças na configuração podem levar até 24 horas para serem propagadas, mas geralmente entram em vigor em até duas horas.

Para o Dataproc e o Dataproc sem servidor para Apache Spark, os dados de linhagem só são enviados se a linhagem também estiver ativada no Dataproc. Para mais informações, consulte Linha de execução do Spark do Dataproc e Linha de execução de dados do Dataproc sem servidor para Apache Spark.

Para mais informações sobre como controlar a ingestão de linhagem, incluindo como a configuração é aplicada de maneira hierárquica, consulte Controlar a ingestão de linhagem.

Pré-requisitos

Para controlar a ingestão de linhagem, use a API Data Lineage. Verifique se você tem um projeto de cliente configurado para faturamento e cota, já que a API Data Lineage é uma API baseada em cliente.

Ative a API datalineage.googleapis.com no projeto do cliente. Para mais informações, consulte Ativar a linhagem de dados.
Defina o projeto do cliente. Para os exemplos a seguir, use o cabeçalho X-Goog-User-Project. Para mais informações, consulte Parâmetros do sistema.

Receber configuração atual

Para conferir a configuração de linhagem de dados atual, use o método projects.locations.config.get. É possível recuperar a configuração de um projeto, uma pasta ou uma organização.

O exemplo a seguir mostra como receber a configuração de um projeto:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X GET \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config"

Substitua estes valores:

CLIENT_PROJECT_ID: o ID do projeto do cliente usado para faturamento ou cotas.
PROJECT_ID: o ID do projeto cuja configuração você quer ver.

Para receber a configuração de uma pasta ou organização, substitua projects/PROJECT_ID por folders/FOLDER_ID ou organizations/ORGANIZATION_ID.

O comando retorna uma das seguintes saídas:

Se nenhuma configuração for definida, você vai receber uma saída com um objeto ingestion vazio:
```
  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {}
  }
  
```
Nesse caso, a ingestão de linhagem do Dataproc usa a configuração padrão, que é enabled.

Se a ingestão de linhagem do Dataproc estiver ativada explicitamente, você vai receber a seguinte saída:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": true
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

Se a ingestão de linhagem do Dataproc estiver desativada, você vai receber a seguinte saída:

  {
    "name": "projects/123456789012/locations/global/config",
    "ingestion": {
      "rules": [
        {
          "integrationSelector": {
            "integration": "DATAPROC"
          },
          "lineageEnablement": {
            "enabled": false
          }
        }
      ]
    },
    "etag": "Wb35wDxTTLd6Z+QAL+Yd4g=="
  }

O campo etag na resposta é um checksum gerado pelo servidor com base no valor atual da configuração. Ao atualizar uma configuração usando o método patch, inclua o valor etag retornado de uma solicitação get recente no corpo da solicitação. Se você fornecer o etag, o Dataplex Universal Catalog o usará para verificar se a configuração não mudou desde sua última solicitação de leitura. Se houver uma incompatibilidade, a solicitação de atualização vai falhar. Isso evita que você substitua sem querer as configurações feitas por outros usuários em cenários de leitura-modificação-gravação. Se você não fornecer um etag na solicitação patch, o Dataplex Universal Catalog vai substituir a configuração incondicionalmente.

Desativar a ingestão de linhagem para um serviço

Para desativar a ingestão de linhagem de dados em um serviço específico, use o método projects.locations.config.patch com uma regra de ingestão que define lineageEnablement.enabled como false para o integration específico.

Para evitar a substituição acidental de configurações feitas por outros usuários em cenários de leitura-modificação-gravação, inclua o campo etag no corpo da solicitação. Para mais informações, consulte Receber a configuração atual.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": false
      }
    }]
  },
  "etag": "ETAG"
}
EOF

Substitua:

CLIENT_PROJECT_ID: o ID do projeto do cliente usado para faturamento ou cotas.
PROJECT_ID: o ID do projeto cuja configuração você quer atualizar.
ETAG: o valor etag retornado de uma solicitação get recente.

Para desativar a ingestão de linhagem de um serviço em uma pasta ou organização, substitua projects/PROJECT_ID por folders/FOLDER_ID ou organizations/ORGANIZATION_ID.

Ativar a ingestão de linhagem para um serviço

Para ativar a ingestão de linhagem em um serviço específico, use o método projects.locations.config.patch com uma regra de ingestão que define lineageEnablement.enabled como true para o integration específico.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: CLIENT_PROJECT_ID" \
     -X PATCH \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/global/config" \
     --data-binary @- << EOF
{
  "ingestion": {
    "rules": [{
      "integrationSelector": {
        "integration": "DATAPROC"
      },
      "lineageEnablement": {
        "enabled": true
      }
    }]
  },
  "etag": "ETAG"
}
EOF

Substitua:

CLIENT_PROJECT_ID: o ID do projeto do cliente usado para faturamento ou cotas.
PROJECT_ID: o ID do projeto cuja configuração você quer atualizar.
ETAG: o valor etag retornado de uma solicitação get recente.

Para ativar a ingestão de linhagem de um serviço em uma pasta ou organização, substitua projects/PROJECT_ID por folders/FOLDER_ID ou organizations/ORGANIZATION_ID.

Visualizar a linhagem no catálogo universal do Dataplex

É possível conferir informações de linhagem de dados na interface da Web do Dataplex Universal Catalog.

Para conferir a linhagem, siga estas instruções:

No console Google Cloud , acesse a página Pesquisa do Universal Catalog do Dataplex.

Acesse Pesquisar
Selecione Dataplex Universal Catalog como o modo de pesquisa.
Pesquise e clique na entrada que você quer visualizar. Para mais informações, consulte Pesquisar recursos no Dataplex Universal Catalog.
Clique na guia Linhagem.

A visualização Gráfico padrão é aberta, mostrando a linhagem no nível da tabela em sistemas e regiões. Para mais informações, consulte Visualização do gráfico de linhagem.
Para explorar manualmente o gráfico de linhagem, clique em Expandir ao lado de um nó para carregar mais cinco nós por vez.

Para mais informações, consulte Como analisar manualmente o gráfico de linhagem.
Clique em um nó na visualização Gráfico.

O painel Detalhes é aberto com informações sobre o recurso, como nome e tipo totalmente qualificados. Para mais informações, consulte Detalhes do nó.
Clique em uma aresta com um ícone de processo na visualização Gráfico.

O painel Consulta é aberto. Para mais informações, consulte Inspecionar a lógica de transformação e Auditoria e histórico de execuções.
- Para inspecionar a lógica de transformação, clique na guia Detalhes.
- Para ver a auditoria e o histórico de execuções, clique na guia Execuções.
No painel Explorador de linhagem, selecione critérios de filtro, por exemplo, Direção, Tipo de dependência ou Período, e clique em Aplicar.

Isso abre uma visualização focada em uma região específica (prévia). Essa visualização expande automaticamente o gráfico em até três níveis de nós. Para mais informações, consulte Aplicar filtros para uma visualização de linhagem focada.
Na visualização Gráfico focada, selecione um nó e, no painel de detalhes dele, clique em Visualizar caminho para ver o caminho de linhagem do nó selecionado de volta à entrada raiz (somente na visualização focada).

Para mais informações, consulte Visualização do caminho de linhagem.
Para ver a linhagem no nível da coluna (somente para jobs do BigQuery), faça o seguinte:
- Em uma visualização Gráfico focada, clique no ícone de coluna em uma tabela.
  
  Ícone de coluna
- No painel Análise de linhagem, filtre por nome da coluna e clique em Aplicar.
Para mais informações, consulte Linhagem no nível da coluna.
Clique em Redefinir.

Essa ação remove todos os filtros aplicados e leva você ao início da visualização de gráfico.
Clique em Lista para mudar para a visualização em lista.

A visualização em lista oferece representações tabulares simplificadas e detalhadas da linhagem no nível da tabela e da coluna, sincronizadas com a visualização em gráfico. Por padrão, a visualização simplificada em lista é mostrada, e você pode alternar para a visualização detalhada em lista para analisar as relações individuais de origem-destino. É possível configurar quais colunas serão mostradas e exportar dados de linhagem. Para mais informações, consulte Visualização em lista da linhagem.

Ver linhagem no BigQuery

É possível conferir informações de linhagem de dados na interface da Web do BigQuery.