Este documento descreve como pesquisar linhagem de dados multirregional e de vários níveis usando a API searchLineageStreaming.
A API
searchLineageStreaming
realiza uma pesquisa em largura em uma direção especificada (upstream ou
downstream) começando 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 subgrafos e links de linhagem à medida que são descobertos pelo sistema de back-end. Isso é altamente eficiente para gráficos de linhagem amplos ou profundos e evita tempos limite de solicitação.
Traversal em vários locais e projetos: embora você especifique apenas um projeto de faturamento no caminho da solicitação, a API descobre e percorre automaticamente os links de linhagem em vários projetos do Google Cloud e locais geográficos, desde que você tenha as permissões necessárias.
Linhagem refinada no nível da coluna: permite pesquisar dependências no nível da coluna entre recursos.
Pesquisas com caractere curinga: permite recuperar toda a linhagem no nível da coluna de uma entidade específica adicionando o sufixo
*ao nome totalmente qualificado (FQN).Insights do pipeline: recupera opcionalmente 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 receber as permissões necessárias
para pesquisar links de linhagem de dados,
peça ao administrador para conceder a você o papel do IAM
Leitor da linhagem de dados (roles/datalineage.viewer) 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 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.getno projeto em que o link está armazenado -
Pesquisar linhagem no nível da coluna:
datalineage.events.getFieldsno projeto em que o link está armazenado -
Recupere os detalhes completos do processo do pipeline:
datalineage.processes.getno 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 principal de faturamento: o caminho
parentna solicitação de URL precisa usar o formatoprojects/project/locations/location. Esse par específico de projeto e local é 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 backend verifique na matriz
locationsdentro do corpo da solicitação.
Configuração da autenticação
Inicialize uma variável de ambiente com um token de acesso Google Cloud para
autenticar seus comandos curl:
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 de vários projetos
Para executar uma pesquisa de linhagem detalhada que percorre várias profundidades do gráfico e verifica diferentes projetos Google Cloud , defina as seguintes variáveis:
Defina
limits.maxDepthcomo a profundidade de navegação desejada (aceita valores de1a100).Preencha a matriz
locationscom as regiões de destino que você quer que o back-end compare (por exemplo,["us", "us-east1"]).
C#
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog C#.
Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Java.
Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente.
Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Python.
Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Ruby.
Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
REST
Para pesquisar linhagem de dados, use o
método searchLineageStreaming.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID: o ID do seu Google Cloud projeto usado para faturamento administrativo e avaliação de cota.LOCATION_ID: o local Google Cloud , comous-central1.SOURCE_PROJECT_ID: o ID do projeto Google Cloud em que a tabela de origem está localizada.DATASET_ID: o ID do conjunto de dados do BigQuery.TABLE_ID: o ID da tabela do BigQuery.
Método HTTP e URL:
POST https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming
Corpo JSON da solicitação:
{
"parent": "projects/PROJECT_ID/locations/LOCATION_ID",
"locations": [
"LOCATION_ID",
"us-east1",
"us-central1"
],
"rootCriteria": {
"entities": {
"entities": [
{
"fullyQualifiedName": "bigquery:SOURCE_PROJECT_ID.DATASET_ID.TABLE_ID"
}
]
}
},
"direction": "DOWNSTREAM",
"limits": {
"maxDepth": 10,
"maxResults": 5000
}
}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{
"links": [
{
"source": {
"fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
},
"target": {
"fullyQualifiedName": "bigquery:project-prod.dataset.target_table"
},
"depth": 1,
"location": "us"
}
]
}
Pesquisar várias localizações geográficas
É possível limitar ou expandir a verificação do gráfico de linhagem modificando as regiões geográficas transmitidas no campo de matriz repetida 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"
}'
Recuperar nomes de processos para links de linhagem
Por padrão, a API omite as informações do processo (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 fluxo 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 uma API FieldMask:
Forneça um valor diferente de zero para
limits.maxProcessPerLink.Adicione um parâmetro de consulta
fieldsao caminho do URL, especificandolinks.processes.processe 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 pesquisar 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 específicos de dependência, 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 à linhagem somente de 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 período
É 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 uma data/hora específica, 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 faz verificações em 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
Saiba mais sobre a pesquisa de linhagem multirregional.
Saiba mais sobre a linhagem de dados.
Saiba mais sobre a visualização de linhagem.