Pesquisar linhagem multirregional usando automação do lado do servidor

Este documento descreve como pesquisar a linhagem de dados multirregional e multinível usando a API searchLineageStreaming.

A searchLineageStreaming API realiza uma pesquisa em largura na direção especificada (upstream ou downstream) a partir de um conjunto definido de entidades raiz e retorna um gráfico de linhagem unificado como uma resposta de streaming em tempo real.

Para mais informações, consulte Sobre a pesquisa de linhagem multirregional.

Principais recursos

A API searchLineageStreaming inclui os seguintes recursos:

  • Pesquisa em largura: percorre o gráfico de linhagem camada por camada, calculando com precisão a profundidade de cada recurso conectado.

  • Resposta de streaming: retorna subgráficos e links de linhagem à medida que são descobertos pelo sistema de back-end. Isso é muito eficiente para gráficos de linhagem amplos ou profundos e evita tempos limite de solicitação.

  • Traversal multilocais e multiprojetos: embora você especifique apenas um projeto de faturamento no caminho da solicitação, a API descobre e percorre automaticamente links de linhagem em vários Google Cloud projetos e locais geográficos, desde que você tenha as permissões necessárias.

  • Linhagem refinada no nível da coluna: oferece suporte à pesquisa de dependências no nível da coluna entre recursos.

  • Pesquisas com caracteres curinga: permite recuperar toda a linhagem no nível da coluna de uma entidade específica, adicionando o nome totalmente qualificado (FQN) com *.

  • Insights de pipeline: opcionalmente, recupera metadados sobre os pipelines de transformação (processos) que criaram os links de linhagem.

Antes de começar

Antes de fazer solicitações à API, verifique se você atende aos seguintes pré-requisitos de segurança e ambiente:

Funções exigidas

Para ter as permissões necessárias para buscar links de linhagem de dados, peça ao administrador para conceder a você o papel Leitor de linhagem de dados (roles/datalineage.viewer) do IAM nos projetos em que os links e processos de linhagem estão armazenados. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para pesquisar links de linhagem de dados. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

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

  • Pesquisar linhagem no nível da entidade: datalineage.events.get no projeto em que o link está armazenado
  • Pesquisar linhagem no nível da coluna: datalineage.events.getFields no projeto em que o link está armazenado
  • Recuperar detalhes completos do processo de pipeline: datalineage.processes.get no projeto em que o processo está armazenado

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

Escopo de recursos

Ao configurar a solicitação de API, é necessário distinguir entre o recurso usado para faturamento administrativo e os locais reais verificados pela API:

  • Caminho pai de faturamento: o caminho parent na solicitação de URL precisa usar o formato projects/project/locations/location. Esse par de projeto-local específico é usado exclusivamente para avaliar cotas de faturamento e limites de taxa de API.

  • Locais de destino: defina explicitamente as regiões que você quer que o back-end verifique na matriz locations dentro do corpo da solicitação.

Configuração da autenticação

Inicialize uma variável de ambiente com um Google Cloud token de acesso para autenticar seus curl comandos:

export ACCESS_TOKEN=$(gcloud auth print-access-token)

Exemplos de uso

Os exemplos a seguir usam o endpoint datalineage.googleapis.com.

Pesquisar linhagem multinível e multiprojeto

Para executar uma pesquisa de linhagem profunda que percorre várias profundidades do gráfico e verifica projetos distintos, Google Cloud defina as seguintes variáveis:

  • Defina limits.maxDepth como a profundidade de traversal de destino (aceita valores de 1 a 100).

  • Preencha a matriz locations com as regiões de destino que você quer que o back-end compare (por exemplo, ["us", "us-east1"]).

Exemplo:

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "us-east1", "us-central1"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      }]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}'

Pesquisar vários locais geográficos

É possível limitar ou expandir a verificação do gráfico de linhagem modificando as regiões geográficas transmitidas no campo de matriz repetido locations.

Exemplo:

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "europe-west1", "asia-south2"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.global_table"
      }]
    }
  },
  "direction": "DOWNSTREAM"
}'

Por padrão, a API deixa as informações do processo omitidas (maxProcessPerLink é definido como 0). Para recuperar os nomes de recursos dos pipelines que criaram seus links de dados, configure limits.maxProcessPerLink como um número inteiro positivo diferente de zero.

Exemplo:

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

Comportamento da resposta: o stream resultante preenche o campo links[].processes com mensagens de processo que contêm apenas o nome absoluto do recurso do sistema (como projects/my-project/locations/us/processes/my-process).

Recuperar detalhes completos do processo usando um FieldMask

Se você precisar de metadados estruturais completos sobre um pipeline (como displayName, attributes do sistema ou origin de execução) em vez de apenas o nome do recurso, use um FieldMask da API:

  1. Forneça um valor diferente de zero para limits.maxProcessPerLink.

  2. Anexe um parâmetro de consulta fields ao caminho do URL, especificando links.processes.process junto com outros campos obrigatórios.

Exemplo:

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST "https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming?fields=links.processes.process,links.source,links.target,links.depth" \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

Pesquisar linhagem no nível da tabela e da coluna

É possível pesquisar a linhagem no nível da tabela (recurso) e da coluna (campo) em uma única solicitação, fornecendo várias entidades na lista rootCriteria.entities.entities:

  • Para linhagem no nível da tabela, omita a matriz field.

  • Para linhagem no nível da coluna, especifique uma única coluna na matriz field.

Exemplo:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_a"
             },
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_b",
               "field": ["email"]
             }
           ]
         }
       },
       "direction": "DOWNSTREAM"
     }'

Usar caracteres curinga para linhagem no nível da coluna

Para buscar toda a linhagem disponível no nível da coluna de uma tabela específica sem listar cada coluna individualmente, use o caractere curinga * como o único valor na matriz field.

Exemplo:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table",
             "field": ["*"]
           }]
         }
       },
       "direction": "DOWNSTREAM"
     }'

Filtrar resultados de linhagem

É possível refinar os resultados da pesquisa de linhagem usando o bloco filters no corpo da solicitação.

Filtrar por tipo de dependência

Para restringir os resultados a tipos de dependência específicos, como cópias diretas (EXACT_COPY) ou transformações como filtragem e agrupamento (OTHER), use o filtro dependencyTypes.

Exemplo:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "dependencyTypes": ["EXACT_COPY"]
       }
     }'

Restringir a linhagem somente da tabela

Para garantir que a pesquisa retorne apenas a linhagem no nível da tabela e exclua completamente a linhagem no nível da coluna, defina o filtro entitySet como ENTITIES.

Exemplo:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "entitySet": "ENTITIES"
       }
     }'

Filtrar por intervalo de tempo

É possível restringir os resultados da pesquisa de linhagem a um intervalo de tempo específico.

Por exemplo, para pesquisar dados de linhagem criados após um carimbo de data/hora específico, use a seguinte solicitação:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "timeRange": {
           "startTime": "2026-01-01T00:00:00Z"
         }
       }
     }'

Processar locais inacessíveis (resultados parciais)

Como a API de streaming verifica um conjunto distribuído de projetos e locais simultaneamente, algumas regiões remotas podem ficar temporariamente inativas, sem comunicação ou mal configuradas durante a execução.

Para proteger a integridade dos dados, o stream searchLineageStreamingResponse contém um campo de diagnóstico dedicado chamado unreachable:

  • Nome do campo: unreachable (representado como uma string repetida)

  • Formato do valor: projects/PROJECT_NUMBER/locations/LOCATION (por exemplo, projects/123456789/locations/us-east1)

A seguir