Pode exportar metadados do catálogo universal do Dataplex para utilização em sistemas externos através da execução de uma tarefa de exportação de metadados.
É recomendável exportar metadados nos seguintes cenários:
- Consultar e analisar metadados com o BigQuery ou outras ferramentas de estatísticas de dados
- Processar programaticamente grandes volumes de metadados, que pode posteriormente importar novamente para o Dataplex Universal Catalog
- Integre metadados em aplicações personalizadas ou ferramentas de terceiros
Uma tarefa de exportação de metadados exporta um instantâneo dos metadados do catálogo universal do Dataplex. Os metadados do Dataplex Universal Catalog consistem em entradas e respetivos aspetos. Os passos nesta página pressupõem que está familiarizado com os conceitos de metadados do catálogo universal do Dataplex, incluindo grupos de entradas, tipos de entradas e tipos de aspetos.
Âmbito do trabalho
O âmbito da tarefa define os metadados a exportar. Tem de fornecer um dos seguintes âmbitos de tarefas para cada tarefa de exportação de metadados:
- Organização: exporta os metadados que pertencem à sua organização.
- Projetos: exporta os metadados pertencentes aos projetos especificados.
- Grupos de entradas: exporta os metadados pertencentes aos grupos de entradas especificados.
Pode restringir ainda mais o âmbito especificando os tipos de entrada ou os tipos de aspeto a incluir na tarefa. A tarefa exporta apenas as entradas e os aspetos que pertencem a estes tipos de entradas e tipos de aspetos.
VPC Service Controls
O catálogo universal do Dataplex usa os VPC Service Controls para oferecer segurança adicional para tarefas de exportação de metadados. O projeto ao qual a tarefa pertence determina o perímetro dos VPC Service Controls, da seguinte forma:
- Se definir o âmbito da tarefa ao nível da organização, ocorrem as seguintes situações:
- O âmbito da exportação é a organização à qual a tarefa pertence.
- Apenas as entradas que estão dentro do perímetro do VPC Service Controls são exportadas.
- Todos os projetos que estejam na organização da tarefa, mas fora do perímetro dos VPC Service Controls, são excluídos.
- Se definir o âmbito da tarefa para projetos ou grupos de entradas, os projetos ou os grupos de entradas têm de estar no mesmo perímetro do VPC Service Controls que a tarefa. Se algum dos projetos ou grupos de entradas violar as regras dos VPC Service Controls, a tarefa falha.
Antes de começar
Antes de exportar metadados, conclua as tarefas nesta secção.
Funções necessárias para utilizadores finais
Para receber as autorizações de que precisa para gerir tarefas de exportação de metadados, peça ao seu administrador que lhe conceda as seguintes funções do IAM:
-
Criar tarefas de exportação de metadados:
-
Dataplex Entry Group Exporter (
roles/dataplex.entryGroupExporter) na organização, nos projetos ou nos grupos de entradas a exportar -
Proprietário da tarefa de metadados do Dataplex (
roles/dataplex.metadataJobOwner) no projeto em que executa a tarefa de metadados
-
Dataplex Entry Group Exporter (
-
Aceda aos resultados exportados:
Storage Object Viewer (
roles/storage.objectViewer) no projeto ou no contentor -
Ver tarefas de metadados:
Visualizador de tarefas de metadados do Dataplex (
roles/dataplex.metadataJobViewer) no projeto
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Estas funções predefinidas contêm as autorizações necessárias para gerir tarefas de exportação de metadados. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para gerir tarefas de exportação de metadados:
-
Exportar metadados:
-
dataplex.metadataJobs.create -
dataplex.entryGroups.export -
dataplex.entryGroups.get -
resourcemanager.projects.get -
resourcemanager.projects.list
-
-
Aceda aos resultados exportados:
storage.objects.get
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Funções necessárias para a conta de serviço do catálogo universal do Dataplex
Para garantir que a
conta de serviço do Dataplex Universal Catalog
tem as autorizações necessárias para aceder ao contentor do Cloud Storage, peça ao
seu administrador para conceder à conta de serviço do Dataplex Universal Catalog as
seguintes autorizações no contentor: storage.buckets.get,
storage.objects.get e storage.objects.create.
Configure Google Cloud recursos
Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando:
gcloud initSe estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
Crie um contentor do Cloud Storage para armazenar os resultados exportados.
O contentor tem de estar na mesma localização e no mesmo perímetro do VPC Service Controls que a tarefa de metadados.
Execute uma tarefa de exportação de metadados
As secções seguintes mostram como exportar metadados com diferentes âmbitos de tarefas.
Exporte metadados da sua organização
Para exportar os metadados da sua organização, use o
método metadataJobs.create
e defina o booleano organizationLevel como true.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
JOB_PROJECT: o Google Cloud projeto no qual executa a tarefa de metadados. Indique um número ou um ID do projeto.LOCATION_ID: a localização Google Cloud , comous-central1.METADATA_JOB_ID: opcional. O ID da tarefa de metadados.BUCKET: o contentor do Cloud Storage para o qual exportar os metadados.Opcionalmente, pode incluir um prefixo personalizado após o nome do contentor, no formato
gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 carateres.
Método HTTP e URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
Corpo JSON do pedido:
{
"type": EXPORT,
"export_spec": {
"output_path": "gs://BUCKET/",
"scope": {
"organizationLevel": true,
},
}
}
Para enviar o seu pedido, expanda uma destas opções:
A resposta identifica uma operação de longa duração. Os metadados exportados são guardados num contentor do Cloud Storage.
Exporte metadados de projetos específicos
Para exportar metadados de um ou mais projetos, use o método metadataJobs.create e faculte uma lista de projetos.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
JOB_PROJECT: o Google Cloud projeto no qual executa a tarefa de metadados. Indique um número ou um ID do projeto.LOCATION_ID: a localização Google Cloud , comous-central1.METADATA_JOB_ID: opcional. O ID da tarefa de metadados.BUCKET: o contentor do Cloud Storage para o qual exportar os metadados.Opcionalmente, pode incluir um prefixo personalizado após o nome do contentor, no formato
gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 carateres.METADATA_SOURCE_PROJECT: um projeto cujos metadados quer exportar. Indique um número ou um ID do projeto. O projeto tem de estar na mesma organização e perímetro do VPC Service Controls que a tarefa de metadados.
Método HTTP e URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
Corpo JSON do pedido:
{
"type": EXPORT,
"export_spec": {
"output_path": "gs://BUCKET/",
"scope": {
"projects": [
"projects/METADATA_SOURCE_PROJECT",
# Additional projects
],
},
}
}
Para enviar o seu pedido, expanda uma destas opções:
A resposta identifica uma operação de longa duração. Os metadados exportados são guardados num contentor do Cloud Storage.
Exporte metadados de grupos de entradas específicos
Para exportar metadados de grupos de entradas específicos, use o
método metadataJobs.create
e forneça uma lista de grupos de entradas.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
JOB_PROJECT: o Google Cloud projeto no qual executa a tarefa de metadados. Indique um número ou um ID do projeto.LOCATION_ID: a localização Google Cloud , comous-central1.METADATA_JOB_ID: opcional. O ID da tarefa de metadados.BUCKET: o contentor do Cloud Storage para o qual exportar os metadados.Opcionalmente, pode incluir um prefixo personalizado após o nome do contentor, no formato
gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 carateres.ENTRY_GROUP: o nome do recurso relativo de um grupo de entradas no âmbito da tarefa, no formatoprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. O grupo de entradas tem de estar no mesmo projeto que a tarefa de metadados.
Método HTTP e URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
Corpo JSON do pedido:
{
"type": EXPORT,
"export_spec": {
"output_path": "gs://BUCKET/",
"scope": {
"entryGroups": [
"ENTRY_GROUP",
# Additional entry groups
],
},
}
}
Para enviar o seu pedido, expanda uma destas opções:
A resposta identifica uma operação de longa duração. Os metadados exportados são guardados num contentor do Cloud Storage.
Exporte metadados de tipos de entradas ou tipos de aspetos específicos
Para exportar metadados de tipos de entradas ou tipos de aspetos específicos, defina o âmbito da tarefa principal, como ao nível da organização, conforme mostrado no exemplo seguinte. Em seguida, faculte uma lista de tipos de entradas, tipos de aspetos ou ambos.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
ENTRY_TYPE: opcional. O nome do recurso relativo de um tipo de entrada que está no âmbito da tarefa, no formatoprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.ASPECT_TYPE: opcional. O nome do recurso relativo de um tipo de aspeto que está no âmbito da tarefa, no formatoprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.
Método HTTP e URL:
POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID
Corpo JSON do pedido:
{
"type": EXPORT,
"export_spec": {
"output_path": "gs://BUCKET/",
"scope": {
"organizationLevel": true,
"entry_types": [
"ENTRY_TYPE",
# Additional entry types
],
"aspect_types": [
"ASPECT_TYPE",
# Additional aspect types
]
},
}
}
Para enviar o seu pedido, expanda uma destas opções:
A resposta identifica uma operação de longa duração. Os metadados exportados são guardados num contentor do Cloud Storage.
Veja detalhes sobre uma tarefa de metadados
Para obter informações sobre uma tarefa de metadados, como o estado da tarefa e o número de entradas exportadas, use o método metadataJobs.get.
Resultados da exportação de metadados
A tarefa de exportação de metadados exporta um resumo dos metadados do catálogo universal do Dataplex no momento em que a tarefa de metadados foi criada.
Exporte o conteúdo do ficheiro
O conteúdo do ficheiro de saída segue o mesmo formato que o ficheiro de importação de metadados usado para tarefas de importação de metadados. Pode usar o ficheiro de saída diretamente como entrada para uma tarefa de importação de metadados.
Localização do ficheiro de exportação
O catálogo universal do Dataplex guarda os ficheiros de resultados da exportação num contentor do Cloud Storage como objetos.
O caminho do objeto para cada ficheiro de saída é construído através do nome do contentor e do prefixo personalizado que especificou na tarefa de exportação, seguido de um caminho gerado pelo sistema. O caminho gerado pelo sistema foi concebido para a integração com o BigQuery. O caminho do objeto usa o seguinte formato:
gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl
Tenha em conta o seguinte:
- O caminho gerado pelo sistema começa com o formato de partição Hive padrão para a data de criação da tarefa de exportação. Este formato é suportado pelo BigQuery. Para mais informações, consulte o artigo Carregar dados particionados externamente.
- O parâmetro
consumer_projecté o projeto onde executa a tarefa de exportação de metadados. O parâmetroprojecté o projeto que contém os metadados que está a exportar. - Pode reutilizar um ID de tarefa de metadados se a tarefa anterior tiver sido eliminada. No entanto, quando elimina uma tarefa, não elimina os ficheiros que foram exportados por essa tarefa. Isto significa que, se reutilizar um ID de tarefa eliminado, pode ver IDs de tarefas duplicados nos caminhos dos ficheiros de saída.
Cada ficheiro de saída tem um número de ficheiro, que é um número inteiro a começar em
1.Se uma tarefa de exportação de metadados contiver um grande número de entradas, a tarefa divide os resultados em vários ficheiros para limitar o tamanho de cada ficheiro de saída. O número máximo de entradas em cada ficheiro de saída é de 1 000 000.
Exemplos de ficheiros de saída
Seguem-se exemplos de ficheiros de saída para uma tarefa de exportação de metadados que incluiu vários projetos:
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl
Seguem-se exemplos de ficheiros de saída para uma tarefa de exportação de metadados que continha um grupo de entradas grande. Os resultados do grupo de entradas foram divididos em vários ficheiros.
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl
Analise os metadados exportados no BigQuery
Se quiser analisar os metadados exportados no BigQuery, pode criar uma tabela externa para os metadados exportados. A criação de uma tabela externa permite-lhe consultar os dados exportados sem carregamento nem transformação de dados adicionais. Por exemplo, pode contar o número de entradas por grupo de entradas, encontrar entradas com aspetos específicos ou realizar uma análise adicional no BigQuery.
Faça o seguinte:
Crie uma tabela externa para dados particionados do Hive. Forneça as seguintes informações:
- Selecionar ficheiro do contentor do Cloud Storage: indique o caminho para a pasta do Cloud Storage que contém os ficheiros de metadados exportados. Para incluir todos os ficheiros no contentor, use o caráter universal asterisco (
*). Por exemplo,gs://export-bucket/example-folder/*. - Formato de ficheiro: selecione JSONL (JSON delimitado por Newline).
- Selecione a caixa de verificação Particionamento de dados de origem e, de seguida, para Selecionar prefixo de URI de origem, indique o prefixo de URI do Cloud Storage para a tabela do BigQuery para definir partições. Por exemplo,
gs://export-bucket/example-folder/. - Modo de inferência de partições: selecione a opção Inferir tipos automaticamente.
- Tipo de tabela: selecione a opção Tabela externa.
Esquema: clique no botão Editar como texto e, de seguida, introduza a seguinte definição de esquema para os ficheiros de exportação:
[ { "name": "entry", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "mode": "NULLABLE", "name": "name", "type": "STRING" }, { "mode": "NULLABLE", "name": "entryType", "type": "STRING" }, { "mode": "NULLABLE", "name": "createTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "updateTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "aspects", "type": "JSON" }, { "mode": "NULLABLE", "name": "parentEntry", "type": "STRING" }, { "mode": "NULLABLE", "name": "fullyQualifiedName", "type": "STRING" }, { "mode": "NULLABLE", "name": "entrySource", "type": "RECORD", "fields": [ { "mode": "NULLABLE", "name": "resource", "type": "STRING" }, { "mode": "NULLABLE", "name": "system", "type": "STRING" }, { "mode": "NULLABLE", "name": "platform", "type": "STRING" }, { "mode": "NULLABLE", "name": "displayName", "type": "STRING" }, { "mode": "NULLABLE", "name": "description", "type": "STRING" }, { "mode": "NULLABLE", "name": "labels", "type": "JSON" }, { "mode": "REPEATED", "name": "ancestors", "type": "RECORD", "fields": [ { "mode": "NULLABLE", "name": "name", "type": "STRING" }, { "mode": "NULLABLE", "name": "type", "type": "STRING" } ] }, { "mode": "NULLABLE", "name": "createTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "updateTime", "type": "STRING" }, { "mode": "NULLABLE", "name": "location", "type": "STRING" } ] } ] } ]
- Selecionar ficheiro do contentor do Cloud Storage: indique o caminho para a pasta do Cloud Storage que contém os ficheiros de metadados exportados. Para incluir todos os ficheiros no contentor, use o caráter universal asterisco (
O BigQuery cria uma tabela externa que contém os metadados exportados. O esquema da tabela inclui uma coluna de esquema entry, em que cada linha
representa uma entrada. Para mais informações sobre os campos de uma entrada, consulte
ImportItem.
O esquema da tabela também contém as partições do ficheiro de exportação, conforme descrito na secção
Localização do ficheiro de exportação deste documento.
Depois de criar a tabela externa, pode consultar a tabela através da sintaxe do GoogleSQL. Por exemplo, para consultar que tipos de entradas foram exportados, use a seguinte declaração:
SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000
O que se segue?
- Saiba como consultar tabelas do BigQuery através da sintaxe do GoogleSQL.
- Importe metadados para o Dataplex Universal Catalog através de um pipeline de conetividade gerido.