Exportar metadados

É possível exportar metadados do Dataplex Universal Catalog para uso em sistemas externos executando um job de exportação de metadados.

Convém exportar metadados nos seguintes cenários:

  • Consultar e analisar metadados com o BigQuery ou outras ferramentas de análise de dados
  • Processar programaticamente grandes volumes de metadados, que podem ser importados de volta para o Dataplex Universal Catalog
  • Integrar metadados a aplicativos personalizados ou ferramentas de terceiros

Um job de exportação de metadados exporta um snapshot dos metadados do Dataplex Universal Catalog. Os metadados do Dataplex Universal Catalog consistem em entradas e seus aspectos. As etapas nesta página pressupõem que você conhece os conceitos de metadados do Dataplex Universal Catalog, incluindo grupos de entrada, tipos de entrada e tipos de aspecto.

Escopo do job

O escopo do job define os metadados a serem exportados. É necessário fornecer um dos seguintes escopos de job para cada job de exportação de metadados:

  • Organização: exporta os metadados que pertencem à sua organização.
  • Projetos: exporta os metadados dos projetos especificados.
  • Grupos de entradas: exporta os metadados que pertencem aos grupos de entradas especificados.

É possível restringir ainda mais o escopo especificando os tipos de entrada ou de aspecto a serem incluídos no job. O job exporta apenas as entradas e os aspectos que pertencem a esses tipos.

VPC Service Controls

O Dataplex Universal Catalog usa o VPC Service Controls para oferecer mais segurança aos jobs de exportação de metadados. O projeto a que o job pertence determina o perímetro do VPC Service Controls, da seguinte maneira:

  • Se você definir o escopo do job no nível da organização, as seguintes ações vão acontecer:
    • O escopo da exportação é a organização a que o job pertence.
    • Somente as entradas que estão dentro do perímetro do VPC Service Controls são exportadas.
    • Todos os projetos que estão dentro da organização do job, mas fora do perímetro do VPC Service Controls, são excluídos.
  • Se você definir o escopo do job como projetos ou grupos de entradas, eles precisarão estar no mesmo perímetro do VPC Service Controls que o job. Se algum dos projetos ou grupos de entradas violar as regras do VPC Service Controls, o job vai falhar.

Antes de começar

Antes de exportar metadados, conclua as tarefas desta seção.

Funções necessárias para usuários finais

Para receber as permissões necessárias para gerenciar jobs de exportação de metadados, peça ao administrador para conceder a você os papéis do IAM a seguir:

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 gerenciar jobs de exportação de metadados. Para conferir 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 gerenciar jobs de exportação de metadados:

  • Exportar metadados:
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • Acesse os resultados exportados: storage.objects.get

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

Papéis necessários para a conta de serviço do Dataplex Universal Catalog

Para garantir que a conta de serviço do Dataplex Universal Catalog tenha as permissões necessárias para acessar o bucket do Cloud Storage, peça ao administrador para conceder à conta de serviço do Dataplex Universal Catalog as seguintes permissões no bucket: storage.buckets.get, storage.objects.get e storage.objects.create.

Configurar recursos Google Cloud

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Crie um bucket do Cloud Storage para armazenar os resultados exportados.

    O bucket precisa estar no mesmo local e no mesmo perímetro do VPC Service Controls que o job de metadados.

Executar um job de exportação de metadados

As seções a seguir mostram como exportar metadados com diferentes escopos de job.

Exportar 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 os dados da solicitação abaixo, faça as substituições a seguir:

  • JOB_PROJECT: o projeto Google Cloud em que você executa o job de metadados. Informe um número ou ID do projeto.
  • LOCATION_ID: o Google Cloud local, como us-central1.
  • METADATA_JOB_ID: opcional. O ID do job de metadados.

  • BUCKET: o bucket do Cloud Storage para exportar os metadados.

    Também é possível incluir um prefixo personalizado depois do nome do bucket, no formato gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 caracteres.

Método HTTP e URL: 

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

Corpo JSON da solicitação:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

Para enviar a solicitação, expanda uma destas opções:

A resposta identifica uma operação de longa duração. Os metadados exportados são salvos em um bucket do Cloud Storage.

Exportar metadados de projetos específicos

Para exportar metadados de um ou mais projetos, use o método metadataJobs.create e forneça uma lista de projetos.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • JOB_PROJECT: o projeto Google Cloud em que você executa o job de metadados. Informe um número ou ID do projeto.
  • LOCATION_ID: o Google Cloud local, como us-central1.
  • METADATA_JOB_ID: opcional. O ID do job de metadados.

  • BUCKET: o bucket do Cloud Storage para exportar os metadados.

    Também é possível incluir um prefixo personalizado depois do nome do bucket, no formato gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 caracteres.

  • METADATA_SOURCE_PROJECT: um projeto cujos metadados você quer exportar. Informe um número ou ID do projeto. O projeto precisa estar na mesma organização e no mesmo perímetro do VPC Service Controls que o job 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 da solicitação:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

Para enviar a solicitação, expanda uma destas opções:

A resposta identifica uma operação de longa duração. Os metadados exportados são salvos em um bucket do Cloud Storage.

Exportar metadados de grupos de entrada 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 os dados da solicitação abaixo, faça as substituições a seguir:

  • JOB_PROJECT: o projeto Google Cloud em que você executa o job de metadados. Informe um número ou ID do projeto.
  • LOCATION_ID: o Google Cloud local, como us-central1.
  • METADATA_JOB_ID: opcional. O ID do job de metadados.

  • BUCKET: o bucket do Cloud Storage para exportar os metadados.

    Também é possível incluir um prefixo personalizado depois do nome do bucket, no formato gs://BUCKET/PREFIX/. O comprimento máximo do prefixo personalizado é de 128 caracteres.

  • ENTRY_GROUP: o nome do recurso relativo de um grupo de entradas no escopo do job, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. O grupo de entradas precisa estar no mesmo projeto que o job 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 da solicitação:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

Para enviar a solicitação, expanda uma destas opções:

A resposta identifica uma operação de longa duração. Os metadados exportados são salvos em um bucket do Cloud Storage.

Exportar metadados de tipos de entradas ou aspectos específicos

Para exportar metadados de tipos de entrada ou aspectos específicos, defina o escopo principal do job, como no nível da organização, conforme mostrado no exemplo a seguir. Em seguida, forneça uma lista de tipos de entrada, tipos de aspectos ou ambos.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • ENTRY_TYPE: opcional. O nome do recurso relativo de um tipo de entrada que está no escopo do job, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ASPECT_TYPE: opcional. O nome do recurso relativo de um tipo de aspecto no escopo do job, no formato projects/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 da solicitação:

{
  "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 a solicitação, expanda uma destas opções:

A resposta identifica uma operação de longa duração. Os metadados exportados são salvos em um bucket do Cloud Storage.

Receber detalhes sobre um job de metadados

Para receber informações sobre um job de metadados, como o status dele e o número de entradas exportadas, use o método metadataJobs.get.

Resultados da exportação de metadados

O job de exportação de metadados exporta um snapshot dos metadados do Dataplex Universal Catalog no momento em que o job de metadados foi criado.

Exportar o conteúdo do arquivo

O conteúdo do arquivo de saída segue o mesmo formato do arquivo de importação de metadados usado para jobs de importação de metadados. É possível usar o arquivo de saída diretamente como entrada para um job de importação de metadados.

Local do arquivo de exportação

O Dataplex Universal Catalog salva os arquivos de resultado da exportação em um bucket do Cloud Storage como objetos.

O caminho do objeto para cada arquivo de saída é construído usando o nome do bucket e o prefixo personalizado especificados no job de exportação, seguidos por um caminho gerado pelo sistema. O caminho gerado pelo sistema foi projetado para 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

Observe o seguinte:

  • O caminho gerado pelo sistema começa com o formato padrão de partição do Hive para a data de criação do job de exportação. Esse formato é compatível com o BigQuery. Para mais informações, consulte Como carregar dados particionados externamente.
  • O parâmetro consumer_project é o projeto em que você executa o job de exportação de metadados. O parâmetro project é o projeto que contém os metadados que você está exportando.
  • É possível reutilizar um ID de job de metadados se o job anterior foi excluído. No entanto, quando você exclui um job, os arquivos exportados por ele não são excluídos. Isso significa que, se você reutilizar um ID de job excluído, poderá ver IDs de job duplicados nos caminhos de arquivo de saída.

  • Cada arquivo de saída recebe um número inteiro começando em 1.

    Se um job de exportação de metadados tiver um grande número de entradas, ele vai dividir os resultados em vários arquivos para limitar o tamanho de cada arquivo de saída. O número máximo de entradas em cada arquivo de saída é 1.000.000.

Exemplos de arquivos de saída

Confira exemplos de arquivos de saída para um job 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

Confira exemplos de arquivos de saída para um job de exportação de metadados que continha um grande grupo de entradas. Os resultados do grupo de entradas foram divididos em vários arquivos.

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

Analisar os metadados exportados no BigQuery

Se quiser analisar os metadados exportados no BigQuery, crie uma tabela externa para eles. Ao criar uma tabela externa, você pode consultar os dados exportados sem precisar carregar ou transformar mais dados. Por exemplo, é possível contar o número de entradas por grupo, encontrar entradas com aspectos específicos ou realizar outras análises no BigQuery.

Faça o seguinte:

  • Crie uma tabela externa para dados particionados do Hive. Forneça as seguintes informações:

    • Selecionar arquivo do bucket do Cloud Storage: informe o caminho para a pasta do Cloud Storage que contém os arquivos de metadados exportados. Para incluir todos os arquivos no bucket, use o caractere curinga asterisco (*). Por exemplo, gs://export-bucket/example-folder/*.
    • Formato do arquivo: selecione JSONL (JSON delimitado por nova linha).
    • Marque a caixa de seleção Particionamento de dados de origem e, em Selecionar prefixo de URI de origem, forneça o prefixo de URI do Cloud Storage para a tabela do BigQuery definir partições. Por exemplo, gs://export-bucket/example-folder/.
    • Modo de inferência de partição: selecione a opção Inferir tipos automaticamente.
    • Tipo de tabela: selecione a opção Tabela externa.

    • Esquema: clique na opção Editar como texto e insira a seguinte definição de esquema para os arquivos 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"
          }
        ]
      }
    ]
  }
]

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 arquivo de exportação, conforme descrito na seção Local do arquivo de exportação deste documento.

Depois de criar a tabela externa, você pode consultá-la usando a sintaxe do GoogleSQL. Por exemplo, para consultar quais tipos de entradas foram exportados, use a seguinte instrução:

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

A seguir