Puedes exportar metadatos de Dataplex Universal Catalog para usarlos en sistemas externos ejecutando una tarea de exportación de metadatos.
Puede que le interese exportar metadatos en los siguientes casos:
- Consultar y analizar metadatos con BigQuery u otras herramientas de análisis de datos
- Procesar grandes volúmenes de metadatos de forma programática, que puedes importar posteriormente a Dataplex Universal Catalog
- Integrar metadatos en aplicaciones personalizadas o herramientas de terceros
Una tarea de exportación de metadatos exporta una vista general de los metadatos de Dataplex Universal Catalog. Los metadatos de Dataplex Universal Catalog se componen de entradas y sus aspectos. En los pasos de esta página se da por hecho que conoces los conceptos de metadatos de Dataplex Universal Catalog, como los grupos de entradas, los tipos de entradas y los tipos de aspectos.
Ámbito de la tarea
El ámbito del trabajo define los metadatos que se van a exportar. Debes proporcionar uno de los siguientes ámbitos de trabajo para cada tarea 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 entradas: exporta los metadatos que pertenecen a los grupos de entradas especificados.
Puede restringir aún más el ámbito especificando los tipos de entrada o los tipos de aspecto que se incluirán en el trabajo. La tarea solo exporta las entradas y los aspectos que pertenecen a estos tipos de entrada y de aspecto.
Controles de Servicio de VPC
Dataplex Universal Catalog usa Controles de Servicio de VPC para proporcionar seguridad adicional a las tareas de exportación de metadatos. El proyecto al que pertenece el trabajo determina el perímetro de Controles de Servicio de VPC de la siguiente manera:
- Si defines el ámbito de la tarea en el nivel de organización, ocurrirá lo siguiente:
- El ámbito de exportación es la organización a la que pertenece el trabajo.
- Solo se exportan las entradas que están dentro del perímetro de Controles de Servicio de VPC.
- Se excluyen los proyectos que estén dentro de la organización del trabajo, pero fuera del perímetro de Controles de Servicio de VPC.
- Si defines el ámbito del trabajo en proyectos o grupos de entradas, estos deben estar en el mismo perímetro de Controles de Servicio de VPC que el trabajo. Si alguno de los proyectos o grupos de entradas infringe las reglas de Controles de Servicio de VPC, el trabajo fallará.
Antes de empezar
Antes de exportar metadatos, completa las tareas de esta sección.
Roles necesarios para los usuarios finales
Para obtener los permisos que necesitas para gestionar los trabajos de exportación de metadatos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:
-
Crea tareas de exportación de metadatos:
-
Exportador de grupos de entradas de Dataplex (
roles/dataplex.entryGroupExporter
) en la organización, los proyectos o los grupos de entradas que quieras exportar -
Propietario de la tarea de metadatos de Dataplex (
roles/dataplex.metadataJobOwner
) en el proyecto en el que ejecutas la tarea de metadatos
-
Exportador de grupos de entradas de Dataplex (
-
Accede a los resultados exportados:
Lector de objetos de Storage (
roles/storage.objectViewer
) en el proyecto o el segmento -
Ver trabajos de metadatos:
Visor de trabajos de metadatos de Dataplex (
roles/dataplex.metadataJobViewer
) en el proyecto
Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.
Estos roles predefinidos contienen los permisos necesarios para gestionar los trabajos de exportación de metadatos. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:
Permisos obligatorios
Para gestionar las tareas de exportación de metadatos, se necesitan los siguientes permisos:
-
Metadatos de exportación:
-
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 u 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 tiene los permisos necesarios para acceder al bucket de Cloud Storage, pide a tu administrador que le conceda los siguientes permisos en el bucket: storage.buckets.get
, storage.objects.get
y storage.objects.create
.
Configurar recursos de Google Cloud
Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando:
gcloud init
Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.
Crea un segmento de Cloud Storage para almacenar los resultados exportados.
El segmento debe estar en la misma ubicación y en el mismo perímetro de Controles de Servicio de VPC que el trabajo de metadatos.
Ejecutar una tarea de exportación de metadatos
En las siguientes secciones se muestra cómo exportar metadatos con diferentes ámbitos de trabajo.
Exportar metadatos de tu organización
Para exportar los metadatos de tu organización, usa el
método metadataJobs.create
y asigna el valor true
al booleano organizationLevel
.
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
JOB_PROJECT
: el Google Cloud proyecto en el que ejecutas el trabajo de metadatos. Proporciona un número o un ID de proyecto.LOCATION_ID
: la Google Cloud ubicación, comous-central1
.METADATA_JOB_ID
: opcional. El ID de la tarea de metadatos.BUCKET
: el segmento de Cloud Storage al que se exportarán los metadatos.Si quieres, puedes incluir un prefijo personalizado después del nombre del segmento 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, despliega una de estas opciones:
La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un segmento de Cloud Storage.
Exportar metadatos de proyectos específicos
Para exportar metadatos de uno o varios proyectos, usa el método metadataJobs.create
y proporciona una lista de proyectos.
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
JOB_PROJECT
: el Google Cloud proyecto en el que ejecutas el trabajo de metadatos. Proporciona un número o un ID de proyecto.LOCATION_ID
: la Google Cloud ubicación, comous-central1
.METADATA_JOB_ID
: opcional. El ID de la tarea de metadatos.BUCKET
: el segmento de Cloud Storage al que se exportarán los metadatos.Si quieres, puedes incluir un prefijo personalizado después del nombre del segmento con el formato
gs://BUCKET/PREFIX/
. La longitud máxima del prefijo personalizado es de 128 caracteres.METADATA_SOURCE_PROJECT
: proyecto cuyos metadatos quieres exportar. Proporciona un número o un ID de proyecto. El proyecto debe estar en la misma organización y en el mismo perímetro de Controles de 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, despliega una de estas opciones:
La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un segmento de Cloud Storage.
Exportar metadatos de grupos de entradas 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 los datos de la solicitud, haz las siguientes sustituciones:
JOB_PROJECT
: el Google Cloud proyecto en el que ejecutas el trabajo de metadatos. Proporciona un número o un ID de proyecto.LOCATION_ID
: la Google Cloud ubicación, comous-central1
.METADATA_JOB_ID
: opcional. El ID de la tarea de metadatos.BUCKET
: el segmento de Cloud Storage al que se exportarán los metadatos.Si quieres, puedes incluir un prefijo personalizado después del nombre del segmento con el formato
gs://BUCKET/PREFIX/
. La longitud máxima del prefijo personalizado es de 128 caracteres.ENTRY_GROUP
: el nombre de recurso relativo de un grupo de entradas que está en el ámbito del trabajo, con el formatoprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID
. El grupo de entradas 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, despliega una de estas opciones:
La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un segmento de Cloud Storage.
Exportar metadatos de tipos de entrada o de aspecto específicos
Para exportar metadatos de tipos de entrada o de aspecto específicos, defina el ámbito de trabajo principal, como el nivel de organización, tal como se muestra en el siguiente ejemplo. A continuación, proporciona una lista de tipos de entrada, tipos de aspecto o ambos.
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
ENTRY_TYPE
: opcional. Nombre de recurso relativo de un tipo de entrada que está en el ámbito del trabajo, con el formatoprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID
.ASPECT_TYPE
: opcional. Nombre de recurso relativo de un tipo de aspecto que está en el ámbito del trabajo, con el formatoprojects/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, despliega una de estas opciones:
La respuesta identifica una operación de larga duración. Los metadatos exportados se guardan en un segmento de Cloud Storage.
Obtener detalles sobre un trabajo de metadatos
Para obtener información sobre un trabajo de metadatos, como el estado del trabajo y el número de entradas que se han exportado, utiliza el método metadataJobs.get
.
Resultados de la exportación de metadatos
La tarea 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ó la tarea de metadatos.
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 en los trabajos de importación de metadatos. Puede 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 segmento de Cloud Storage como objetos.
La ruta del objeto de cada archivo de salida se crea usando el nombre del contenedor y el prefijo personalizado que especificaste en el trabajo de exportación, seguidos de una ruta generada por el sistema. La ruta generada por el sistema se ha diseñado para integrarse con BigQuery. La ruta del objeto tiene 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 generada por el sistema empieza con el formato de partición de Hive estándar para la fecha de creación de la tarea de exportación. BigQuery admite este formato. Para obtener más información, consulta Cargar datos con particiones externas.
- El parámetro
consumer_project
es el proyecto en el que ejecutas la tarea de exportación de metadatos. El parámetroproject
es el proyecto que contiene los metadatos que quieres exportar. - Puedes reutilizar un ID de trabajo de metadatos si el trabajo anterior se ha eliminado. Sin embargo, cuando eliminas un trabajo, no se eliminan los archivos que se exportaron con ese trabajo. Esto significa que, si reutilizas un ID de trabajo eliminado, es posible que veas IDs de trabajo duplicados en las rutas de los archivos de salida.
Cada archivo de salida se denomina con un número de archivo, que es un número entero que empieza por
1
.Si un trabajo de exportación de metadatos contiene un gran número de entradas, el trabajo dividirá los resultados en varios archivos para limitar el tamaño de cada archivo de salida. El número máximo de entradas de cada archivo de salida es 1.000.000.
Archivos de salida de ejemplo
A continuación, se muestran ejemplos de archivos de salida de 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 de un trabajo de exportación de metadatos que contenía un grupo de entradas grande. Los resultados del grupo de entradas se han dividido 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
Analizar los metadatos exportados en BigQuery
Si quiere analizar los metadatos exportados en BigQuery, puede crear una tabla externa para ellos. Crear una tabla externa te permite consultar los datos exportados sin tener que cargar ni transformar datos adicionales. Por ejemplo, puedes contar el número de entradas por grupo de entradas, buscar entradas que tengan aspectos específicos o hacer análisis adicionales en BigQuery.
Sigue estos pasos:
Crea una tabla externa para los datos con particiones de Hive. Introduce la información siguiente:
- Seleccionar archivo del segmento de Cloud Storage: proporciona la ruta a la carpeta de Cloud Storage que contiene los archivos de metadatos exportados. Para incluir todos los archivos del contenedor, usa el comodín asterisco (
*
). Por ejemplo,gs://export-bucket/example-folder/*
. - Formato de archivo: selecciona JSONL (JSON delimitado por líneas nuevas).
- Selecciona la casilla Partición de datos de origen y, en Seleccionar prefijo del URI de origen, proporciona el prefijo del URI de Cloud Storage de la tabla de BigQuery para definir las particiones. Por ejemplo,
gs://export-bucket/example-folder/
. - Modo de inferencia de particiones: selecciona la opción Tipos de inferencias automáticas.
- Tipo de tabla: selecciona la opción Tabla externa.
Esquema: haz clic en el botón Editar como texto y, a continuación, introduce 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" } ] } ] } ]
- Seleccionar archivo del segmento de Cloud Storage: proporciona la ruta a la carpeta de Cloud Storage que contiene los archivos de metadatos exportados. Para incluir todos los archivos del contenedor, usa el comodín asterisco (
BigQuery crea una tabla externa que contiene los metadatos exportados. El esquema de la tabla incluye una columna de esquema entry
, donde 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, tal 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 entradas se han exportado, utiliza la siguiente instrucción:
SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000
Siguientes pasos
- Consulta cómo consultar tablas de BigQuery con la sintaxis de GoogleSQL.
- Importa metadatos a Dataplex Universal Catalog mediante una pipeline de conectividad gestionada.