Exportar metadatos

Puedes exportar metadatos de Dataplex Universal Catalog para usarlos en sistemas externos ejecutando un trabajo de exportación de metadatos.

Te recomendamos que exportes metadatos en los siguientes casos:

  • Consultar y analizar metadatos con BigQuery o con otras herramientas de análisis de datos
  • Procesa grandes volúmenes de metadatos de forma programática, que luego puedes importar de nuevo a Dataplex Universal Catalog.
  • Integrar metadatos en aplicaciones personalizadas o herramientas de terceros

Un trabajo de exportación de metadatos exporta una instantánea de los metadatos de tu Dataplex Universal Catalog. Los metadatos de Dataplex Universal Catalog constan de entradas y sus aspectos. En los pasos de esta página, se supone que conoces los conceptos de metadatos de Dataplex Universal Catalog, incluidos los grupos de entradas, los tipos de entradas y los tipos de aspectos.

Alcance del trabajo

El alcance del trabajo define los metadatos que se exportarán. Debes proporcionar uno de los siguientes permisos de trabajo para cada trabajo de exportación de metadatos:

  • Organización: Exporta los metadatos que pertenecen a tu organización.
  • Proyectos: Exporta los metadatos que pertenecen a los proyectos especificados.
  • Grupos de entrada: Exporta los metadatos que pertenecen a los grupos de entrada especificados.

Puedes restringir aún más el alcance especificando los tipos de entrada o los tipos de aspectos que se incluirán en el trabajo. El trabajo solo exporta las entradas y los aspectos que pertenecen a estos tipos de entrada y tipos de aspecto.

Controles del servicio de VPC

El catálogo universal de Dataplex usa los Controles del servicio de VPC para proporcionar seguridad adicional a los trabajos de exportación de metadatos. El proyecto al que pertenece el trabajo determina el perímetro de los Controles del servicio de VPC, de la siguiente manera:

  • Si estableces el alcance del trabajo a nivel de la organización, sucederá lo siguiente:
    • El alcance de la exportación es la organización a la que pertenece el trabajo.
    • Solo se exportan las entradas que se encuentran dentro del perímetro de los Controles del servicio de VPC.
    • Se excluyen todos los proyectos que se encuentran dentro de la organización del trabajo, pero fuera del perímetro de los Controles del servicio de VPC.
  • Si configuras el alcance del trabajo en proyectos o grupos de entradas, estos deben estar en el mismo perímetro de Controles del servicio de VPC que el trabajo. Si alguno de los proyectos o grupos de entrada incumple las reglas de los Controles del servicio de VPC, el trabajo fallará.

Antes de comenzar

Antes de exportar metadatos, completa las tareas de esta sección.

Roles obligatorios para los usuarios finales

Para obtener los permisos que necesitas para administrar trabajos de exportación de metadatos, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para administrar los trabajos de exportación de metadatos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para administrar los trabajos de exportación de metadatos:

  • Exportar metadatos:
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • Accede a los resultados exportados: storage.objects.get

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Roles necesarios para la cuenta de servicio de Dataplex Universal Catalog

Para asegurarte de que la cuenta de servicio de Dataplex Universal Catalog tenga los permisos necesarios para acceder al bucket de Cloud Storage, pídele a tu administrador que le otorgue los siguientes permisos en el bucket: storage.buckets.get, storage.objects.get y storage.objects.create.

Configura 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. Crea un bucket de Cloud Storage para almacenar los resultados exportados.

    El bucket debe estar en la misma ubicación y en el mismo perímetro de los Controles del servicio de VPC que el trabajo de metadatos.

Ejecuta un trabajo de exportación de metadatos

En las siguientes secciones, se muestra cómo exportar metadatos con diferentes alcances de trabajo.

Exporta metadatos de tu organización

Para exportar los metadatos de tu organización, usa el método metadataJobs.create y establece el valor booleano organizationLevel en true.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • JOB_PROJECT: El proyecto Google Cloud en el que ejecutas el trabajo de metadatos. Proporciona un número o ID del proyecto.
  • LOCATION_ID: La ubicación Google Cloud , como us-central1.
  • METADATA_JOB_ID: es opcional. Es el ID del trabajo de metadatos.

  • BUCKET: Es el bucket de Cloud Storage al que se exportarán los metadatos.

    De manera opcional, puedes incluir un prefijo personalizado después del nombre del bucket, con el formato gs://BUCKET/PREFIX/. La longitud máxima del prefijo personalizado es de 128 caracteres.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un bucket de Cloud Storage.

Exporta metadatos de proyectos específicos

Para exportar metadatos de uno o más proyectos, usa el método metadataJobs.create y proporciona una lista de proyectos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • JOB_PROJECT: El proyecto Google Cloud en el que ejecutas el trabajo de metadatos. Proporciona un número o ID del proyecto.
  • LOCATION_ID: La ubicación Google Cloud , como us-central1.
  • METADATA_JOB_ID: es opcional. Es el ID del trabajo de metadatos.

  • BUCKET: Es el bucket de Cloud Storage al que se exportarán los metadatos.

    De manera opcional, puedes incluir un prefijo personalizado después del nombre del bucket, con el formato gs://BUCKET/PREFIX/. La longitud máxima del prefijo personalizado es de 128 caracteres.

  • METADATA_SOURCE_PROJECT: Es un proyecto cuyos metadatos deseas exportar. Proporciona un número o ID del proyecto. El proyecto debe estar en la misma organización y perímetro de Controles del servicio de VPC que el trabajo de metadatos.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un bucket de Cloud Storage.

Exporta metadatos de grupos de entrada específicos

Para exportar metadatos de grupos de entradas específicos, usa el método metadataJobs.create y proporciona una lista de grupos de entradas.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • JOB_PROJECT: El proyecto Google Cloud en el que ejecutas el trabajo de metadatos. Proporciona un número o ID del proyecto.
  • LOCATION_ID: La ubicación Google Cloud , como us-central1.
  • METADATA_JOB_ID: es opcional. Es el ID del trabajo de metadatos.

  • BUCKET: Es el bucket de Cloud Storage al que se exportarán los metadatos.

    De manera opcional, puedes incluir un prefijo personalizado después del nombre del bucket, con el formato gs://BUCKET/PREFIX/. La longitud máxima del prefijo personalizado es de 128 caracteres.

  • ENTRY_GROUP: Es el nombre del recurso relativo de un grupo de entradas que está dentro del alcance del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. El grupo de entrada debe estar en el mismo proyecto que el trabajo de metadatos.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un bucket de Cloud Storage.

Exporta metadatos de tipos de entrada o tipos de aspectos específicos

Para exportar metadatos de tipos de entrada o tipos de aspectos específicos, establece el alcance principal del trabajo, como a nivel de la organización, como se muestra en el siguiente ejemplo. Luego, proporciona una lista de tipos de entrada, tipos de aspectos o ambos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • ENTRY_TYPE: es opcional. Nombre del recurso relativo de un tipo de entrada que está dentro del alcance del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ASPECT_TYPE: es opcional. Nombre de recurso relativo de un tipo de aspecto que está dentro del alcance del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un bucket de Cloud Storage.

Obtén detalles sobre un trabajo de metadatos

Para obtener información sobre un trabajo de metadatos, como el estado del trabajo y la cantidad de entradas que se exportaron, usa el método metadataJobs.get.

Resultados de la exportación de metadatos

El trabajo de exportación de metadatos exporta una instantánea de los metadatos de tu catálogo universal de Dataplex en el momento en que se creó el trabajo de metadatos.

Cómo exportar el contenido de un archivo

El contenido del archivo de salida sigue el mismo formato que el archivo de importación de metadatos que se usa para los trabajos de importación de metadatos. Puedes usar el archivo de salida directamente como entrada para un trabajo de importación de metadatos.

Ubicación del archivo de exportación

Dataplex Universal Catalog guarda los archivos de resultados de la exportación en un bucket de Cloud Storage como objetos.

La ruta del objeto para cada archivo de salida se construye con el nombre del bucket y el prefijo personalizado que especificaste en el trabajo de exportación, seguido de una ruta generada por el sistema. La ruta generada por el sistema está diseñada para la integración con BigQuery. La ruta del objeto usa el siguiente 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

Ten en cuenta lo siguiente:

  • La ruta de acceso generada por el sistema comienza con el formato estándar de partición de Hive para la fecha de creación del trabajo de exportación. BigQuery admite este formato. Para obtener más información, consulta Carga datos con particiones externas.
  • El parámetro consumer_project es el proyecto en el que ejecutas el trabajo de exportación de metadatos. El parámetro project es el proyecto que contiene los metadatos que exportas.
  • Puedes volver a usar un ID de trabajo de metadatos si se borró el trabajo anterior. Sin embargo, cuando borras un trabajo, no se borran los archivos que se exportaron con ese trabajo. Esto significa que, si reutilizas un ID de trabajo borrado, es posible que veas IDs de trabajo duplicados en las rutas de acceso de los archivos de salida.

  • Cada archivo de salida se denomina con un número de archivo, que es un número entero que comienza en 1.

    Si un trabajo de exportación de metadatos contiene una gran cantidad de entradas, el trabajo divide los resultados en varios archivos para limitar el tamaño de cada archivo de salida. La cantidad máxima de entradas en cada archivo de salida es de 1,000,000.

Ejemplos de archivos de salida

A continuación, se muestran archivos de salida de ejemplo para un trabajo de exportación de metadatos que incluía varios proyectos:

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

A continuación, se muestran ejemplos de archivos de salida para un trabajo de exportación de metadatos que contenía un grupo de entradas grande. Los resultados del grupo de entradas se dividieron en varios archivos.

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

Analiza los metadatos exportados en BigQuery

Si deseas analizar los metadatos exportados en BigQuery, puedes crear una tabla externa para los metadatos exportados. Crear una tabla externa te permite consultar los datos exportados sin necesidad de cargar ni transformar datos adicionales. Por ejemplo, puedes contar la cantidad de entradas por grupo, buscar las que tienen aspectos específicos o realizar análisis adicionales en BigQuery.

Haz lo siguiente:

  • Crea una tabla externa para los datos con particiones de Hive. Proporciona la siguiente información:

    • Seleccionar archivo del bucket de Cloud Storage: Proporciona la ruta de acceso a la carpeta de Cloud Storage que contiene los archivos de metadatos exportados. Para incluir todos los archivos del bucket, usa el comodín de asterisco (*). Por ejemplo, gs://export-bucket/example-folder/*.
    • Formato de archivo: Selecciona JSONL (JSON delimitado por saltos de línea).
    • Selecciona la casilla de verificación Partición de datos de origen y, luego, para Seleccionar prefijo de URI de origen, proporciona el prefijo de URI de Cloud Storage para que la tabla de BigQuery defina particiones. Por ejemplo, gs://export-bucket/example-folder/.
    • Modo de inferencia de partición: Selecciona la opción Inferir tipos automáticamente.
    • Tipo de tabla: Selecciona la opción Tabla externa.

    • Esquema: Haz clic en el botón de activación Editar como texto y, luego, ingresa la siguiente definición de esquema para los archivos de exportación:

      [
  {
    "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"
          }
        ]
      }
    ]
  }
]

BigQuery crea una tabla externa que contiene los metadatos exportados. El esquema de la tabla incluye una columna de esquema entry, en la que cada fila representa una entrada. Para obtener más información sobre los campos de una entrada, consulta ImportItem. El esquema de la tabla también contiene las particiones del archivo de exportación, como se describe en la sección Ubicación del archivo de exportación de este documento.

Después de crear la tabla externa, puedes consultarla con la sintaxis de GoogleSQL. Por ejemplo, para consultar qué tipos de entrada se exportaron, usa la siguiente instrucción:

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

¿Qué sigue?