Importar metadatos

Puedes importar metadatos de Dataplex Catalog, las entradas y sus aspectos, de un sistema de terceros a Dataplex

Para importar metadatos, sigue estos pasos de alto nivel:

  1. Determinar el alcance del trabajo.

    Comprender cómo Dataplex aplica la lógica de comparación y el modo de sincronización para entradas y aspectos.

  2. Crea uno o más archivos de importación de metadatos que definan los datos que se importarán.

  3. Guardar los archivos de importación de metadatos en un bucket de Cloud Storage

  4. Ejecutar un trabajo de importación de metadatos

En los pasos de esta página, se asume que estás familiarizado conceptos de Dataplex Catalog, incluidos grupos y tipos de entradas, y tipos de aspecto. Para obtener más información, consulta Descripción general del catálogo de Dataplex.

Antes de comenzar

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

Roles obligatorios

Para garantizar que el Cuenta de servicio de Dataplex tenga los permisos necesarios para acceder al bucket de Cloud Storage, pídele tu administrador otorgue la autorización a la cuenta de servicio de Dataplex Rol de IAM de visualizador de objetos de Storage (roles/storage.objectViewer) y el permiso storage.buckets.get en el bucket.

A fin de obtener los permisos que necesitas para administrar los trabajos de metadatos, haz lo siguiente: solicita a tu administrador que te otorgue el los siguientes roles de IAM:

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea recursos de Google Cloud

Prepara los siguientes recursos de Google Cloud:

  1. Crea un grupo de entradas para las entradas que quieres importar.
  2. Crea tipos de aspecto para los aspectos que deseas importar.
  3. Cómo crear tipos de entradas para las entradas que quieres importar.
  4. Crea un bucket de Cloud Storage para almacenar tus archivos de importación de metadatos.

Componentes de un trabajo de metadatos

Cuando importes metadatos, ten en cuenta los siguientes componentes de un trabajo de metadatos:

  • Alcance del trabajo: El grupo de entradas, los tipos de entrada y los tipos de aspecto que se incluirán en el trabajo.
  • Modo de sincronización: si se debe realizar una actualización completa o una sobre las entradas y los aspectos del trabajo.
  • Archivo de importación de metadatos: Es un archivo que define los valores que se deben establecer para las entradas. y aspectos del trabajo. Puedes proporcionar varios archivos de importación de metadatos mismo trabajo de metadatos. Guardas los archivos en Cloud Storage.
  • Lógica de comparación: Cómo determina Dataplex cuáles entradas aspectos a modificar.

Permiso del trabajo

El permiso del trabajo define el grupo de entrada, los tipos de entrada y, opcionalmente, los los tipos de aspectos que quieres incluir en un trabajo de metadatos. Cuando realizas una importación metadatos, modifica las entradas y los aspectos que pertenecen a los recursos dentro del el alcance del trabajo.

Para definir el alcance del trabajo, sigue estas pautas:

  • Grupo de entrada: especifica un solo grupo de entrada para incluir en el trabajo. El trabajo solo modifica las entradas que pertenecen a este grupo de entradas. El grupo de entrada y el trabajo deben estar en la misma región.

  • Tipos de entrada: Especifica uno o más tipos de entrada para incluir en el trabajo. El trabajo modifica solo las entradas que pertenecen a estos tipos de entradas. La ubicación de un tipo de entrada debe coincidir con la ubicación del trabajo. el tipo de entrada debe ser global.

  • Tipos de aspecto: Opcional. Especifica uno o más tipos de aspecto para incluir en el trabajo. Si especificas un alcance para los tipos de aspecto, el trabajo modifica solo los aspectos que pertenecen a estos tipos de aspecto. La ubicación de un tipo de aspecto debe coincidir con la ubicación del trabajo. el tipo de aspecto debe ser global.

El permiso del trabajo se especifica cuando creas un trabajo de metadatos.

Modo de sincronización

El modo de sincronización especifica si se debe realizar una actualización completa o actualización incremental de las entradas y los aspectos de un trabajo de metadatos.

  • FULL: Se admite para las entradas. Todas las entradas en el permiso del trabajo modificado.

    Si una entrada existe en Dataplex, pero no está incluida en la de importación de metadatos, la entrada se borra cuando ejecutas el trabajo de metadatos.

    No se admite la sincronización completa para los aspectos.

  • INCREMENTAL: compatible con aspectos. Un aspecto solo se modifica si el archivo de importación de metadatos incluye una referencia al aspecto en la updateMask y aspectKeys. Para obtener más información estos campos en el archivo de importación de metadatos, consulta la Estructura de un elemento de importación de este documento.

    La sincronización incremental no es compatible con las entradas.

El modo de sincronización se especifica cuando creas un trabajo de metadatos.

Archivo de importación de metadatos

El archivo de importación de metadatos es una colección de las entradas y los aspectos que modificar. Define los valores que se deben establecer para todos los campos que pertenecen a estas entradas y aspectos. Preparas el archivo antes de ejecutar un trabajo de metadatos.

Puedes proporcionar varios archivos de importación de metadatos en el mismo trabajo de metadatos.

Las entradas que proporciones en el archivo reemplazarán por completo todas las entradas entradas para cualquier recurso que está dentro del alcance del trabajo. Esto significa que debe incluir valores para todas las entradas de un trabajo, no solo los valores que que deseas agregar o actualizar. Cómo obtener una lista de las entradas actuales de tu proyecto para usarlos como punto de partida, usa el Método de la API de entries.list.

Todas las entradas y los aspectos que incluyas en el archivo deben pertenecer al grupos de entradas, tipos de entradas y tipos de aspecto que defines en el alcance del trabajo.

Sigue los lineamientos de las siguientes secciones para crear un archivo de importación de metadatos.

Estructura del archivo

Cada línea del archivo de importación de metadatos contiene un objeto JSON que corresponde a un elemento de importación. Un elemento de importación es un objeto que describe los valores que se van a modificar para una entrada y sus aspectos adjuntos.

Puedes proporcionar varios elementos de importación en un solo archivo de importación de metadatos. Sin embargo, no proporcionan el mismo elemento de importación más de una vez en un trabajo de metadatos. Usa un Carácter de salto de línea (0x0a) para separar cada elemento de importación.

Un archivo de importación de metadatos con un carácter de línea nueva entre cada elemento de importación como en el siguiente ejemplo:

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

Estructura de un elemento de importación

Cada elemento de importación en el archivo de importación de metadatos incluye los siguientes campos. El siguiente ejemplo tiene un formato con saltos de línea para facilitar la lectura, pero cuando guardas el archivo, incluye un carácter de línea nueva solo después de cada importación elemento. No incluyas saltos de línea entre los campos de un solo elemento de importación.

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    }
    "aspects": {
      "ASPECT": {
        "data": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

Reemplaza lo siguiente:

  • ENTRY_NAME: Es el nombre del recurso relativo de la entrada. en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID
  • ENTRY_TYPE: Es el nombre del recurso relativo del el tipo de entrada que se usó para crear esta entrada, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID
  • entrySource: Es la información del sistema de origen sobre el recurso de datos que se representa con la entrada:
    • RESOURCE: Es el nombre del recurso en la fuente. en un sistema de archivos.
    • SYSTEM: Es el nombre del sistema de origen.
    • PLATFORM: Es la plataforma que contiene el sistema de origen.
    • DISPLAY_NAME: Es un nombre visible fácil de usar.
    • DESCRIPTION: Es una descripción de la entrada.
    • ENTRY_CREATE_TIMESTAMP: Es la hora en que se creó la entrada. que se crean en el sistema de origen.
    • ENTRY_UPDATE_TIMESTAMP: Es la hora en que se creó la entrada. en el sistema de origen.

  • aspects: Son los aspectos que se adjuntan a la entrada. El objeto aspect y sus datos se denominan mapa de aspecto.

    • ASPECT: Es un aspecto adjunto a la entrada. Según cómo se adjunte el aspecto a la entrada, usa una de las siguientes opciones: formatos:

      • Si el aspecto se adjunta directamente a la entrada, proporciona el recurso relativo nombre de su tipo de aspecto, en el formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID
      • Si el aspecto está adjunto a la ruta de acceso de la entrada, proporciona el atributo de la ruta de acceso, en el formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH

    • KEY y VALUE: El contenido de la aspecto, según su esquema de tipo de aspecto. El contenido se debe codificar como UTF-8. El tamaño máximo del campo es de 120 KB.

    • ASPECT_CREATE_TIMESTAMP: La hora en que se creó el aspecto el sistema fuente.

    • ASPECT_UPDATE_TIMESTAMP: Es la hora en la que se actualizó el aspecto. el sistema fuente.

    • PARENT_ENTRY: Es el nombre del recurso de la entrada superior.

    • FULLY_QUALIFIED_NAME: Es un nombre para la entrada que se puede a las que hace referencia un sistema externo.

  • UPDATE_MASK_FIELDS: Los campos que se actualizarán, en rutas que son en relación con el recurso Entry. Separa cada campo con una coma.

    En el modo de sincronización de entrada de FULL, Dataplex incluye las rutas de todos de los campos de una entrada que se puede modificar, incluidos los aspectos.

    El campo update_mask se ignora cuando se crea o se vuelve a crear una entrada.

  • ASPECT_KEY: Son los aspectos que se modificarán. Admite el las siguientes sintaxis:

    • ASPECT_TYPE_REFERENCE: Coincide con el tipo de aspecto de que están conectados directamente a la entrada.
    • ASPECT_TYPE_REFERENCE@PATH coincida con el tipo de aspecto y la ruta especificada.
    • ASPECT_TYPE_REFERENCE@*: Coincide con el tipo de aspecto. para todas las rutas.

    Reemplaza ASPECT_TYPE_REFERENCE por una referencia al el tipo de aspecto, en el formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID

    Si dejas este campo vacío, se tratará como si se especificaran exactamente aquellos que están presentes en la entrada especificada.

    En el modo de sincronización de entrada FULL, Dataplex agrega implícitamente las claves para todos los aspectos obligatorios de una entrada.

Requisitos de los archivos

El archivo de importación de metadatos tiene los siguientes requisitos:

  • El archivo debe tener el formato de líneas JSON. que es un archivo JSON delimitado por saltos de línea. Usa un carácter de salto de línea (0x0a) para separar cada elemento importado.
  • El archivo debe usar la codificación de caracteres UTF-8.
  • Las extensiones de archivo compatibles son .jsonl y .json.
  • El tamaño del archivo debe ser inferior a 1 GiB.
  • Las entradas y los aspectos que especifiques en el archivo deben ser parte del el permiso del trabajo de importación.
  • El archivo debe subirse a un bucket de Cloud Storage. No guardes en una carpeta llamada CLOUD_STORAGE_URI/deletions/.

Lógica de comparación

Dataplex determina qué entradas y aspectos modificar comparando valores y marcas de tiempo que proporcionas en el archivo de importación de metadatos con los valores y las marcas de tiempo que existen en tu proyecto.

A un alto nivel, Dataplex actualiza los valores de tu proyecto cuando al menos un cambio propuesto en el archivo de importación de metadatos cambiará el estado de tu proyecto cuando se ejecuta el trabajo, sin introducir una versión desactualizada de datos no estructurados. El cambio propuesto se debe hacer referencia en el campo de máscara de actualización o en el aspecto. claves en el archivo de importación de metadatos.

Por cada entrada que forma parte del alcance del trabajo, Dataplex hace una lo siguiente:

  • Crea una entrada y los aspectos adjuntos. Si el archivo de importación de metadatos incluye una entrada que no existe en tu proyecto, Dataplex crea la entrada y los aspectos adjuntos.
  • Borra una entrada y los aspectos adjuntos. Si existe una entrada en tu pero el archivo de importación de metadatos no incluye la entrada, Dataplex borra la entrada y sus aspectos adjuntos de tu en un proyecto final.

  • Actualiza una entrada y los aspectos adjuntos. Si existe una entrada en ambos el archivo de importación de metadatos y, en tu proyecto, Dataplex evalúa las marcas de tiempo de la fuente de entrada y las marcas de tiempo de la fuente de aspecto que se asocian con la entrada para determinar qué valores modificar. Luego, Dataplex realiza una o más de las siguientes tareas:

    • Vuelve a crear la entrada. Si la fuente de entrada crea una marca de tiempo en el de importación de metadatos es más reciente que la marca de tiempo correspondiente en tu proyecto, Dataplex recrea la entrada en tu proyecto.
    • Actualiza la entrada. Si la marca de tiempo de actualización de la fuente de entrada en los metadatos importar archivo sea más reciente que la marca de tiempo correspondiente de tu proyecto, Dataplex actualiza la entrada en tu proyecto.
    • Crea un aspecto. Si se incluye un aspecto en el objeto de entrada en la de importación de metadatos, pero no está incluida en el campo de máscara de actualización, Dataplex crea el aspecto.
    • Borra un aspecto. Si un aspecto no se incluye en el objeto de entrada en el archivo de importación de metadatos, pero está incluido en el campo de máscara de actualización Dataplex borra el aspecto.

    • Actualiza un aspecto. Si la marca de tiempo de actualización de la fuente de aspecto en los metadatos importar archivo sea más reciente que la marca de tiempo correspondiente de tu proyecto, Dataplex actualiza el aspecto de tu proyecto. Dataplex actualiza el aspecto si su entrada adjunta falta una marca de tiempo de actualización de la fuente de entrada o si la marca de tiempo en el archivo de importación de metadatos sea más reciente que la marca de tiempo correspondiente en tu proyecto.

      Sin embargo, si al menos un aspecto del archivo de importación de metadatos tiene un marca de tiempo que la marca de tiempo correspondiente en tu proyecto y, luego, Dataplex no realiza ninguna actualización para la entrada adjunta.

Crea un archivo de importación de metadatos

Antes de importar metadatos, crea un archivo de importación de metadatos para tu trabajo. Sigue estos pasos:

  1. Prepara un archivo de importación de metadatos de la siguiente manera: los lineamientos que se describieron anteriormente en este documento.
  2. Sube el archivo a un bucket de Cloud Storage.

Puedes proporcionar varios archivos de importación de metadatos en el mismo trabajo de metadatos. Para proporcionar varios archivos, guardarlos en el mismo Cloud Storage bucket. Cuando ejecutas el trabajo, especificas un bucket, no un archivo específico. Dataplex transfiere metadatos de todos los archivos guardados en en el bucket, incluidos los archivos que se encuentran en subcarpetas.

Ejecuta un trabajo de importación de metadatos

Después de crear un archivo de importación de metadatos, ejecuta un trabajo de importación de metadatos con el comando en la API de Cloud.

REST

Para importar metadatos, usa el Método metadataJobs.create.

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

  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud. o el ID del proyecto.
  • LOCATION_ID: Es la ubicación de Google Cloud, como us-central1
  • METADATA_JOB_ID: es opcional. El ID de trabajo de metadatos.

  • CLOUD_STORAGE_URI: Es el URI del El bucket o la carpeta de Cloud Storage que contiene los archivos de importación de metadatos. Para ver más sobre los requisitos de los archivos, consulta Archivo de importación de metadatos.

  • ENTRY_GROUP: Es el nombre del recurso relativo del grupo de entrada que está dentro del alcance del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID Proporciona solo un grupo de entrada. Para obtener más información, consulta Alcance del trabajo.

  • ENTRY_TYPE: Es el nombre del recurso relativo de un tipo de entrada que es según el permiso del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID Para obtener más información, consulta Alcance del trabajo.

  • ASPECT_TYPE: es opcional. El nombre de recurso relativo de un aspecto dentro del alcance del trabajo, en el formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID Para obtener más información, consulta Alcance del trabajo.
  • LOG_LEVEL: El nivel de registros que se capturarán, como INFO o DEBUG. Para obtener más información, consulta Visualiza registros de trabajos y soluciona problemas.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

Para enviar tu solicitud, expande una de estas opciones:

La respuesta identifica una operación de larga duración.

Obtén detalles sobre un trabajo de metadatos

Para obtener información sobre un trabajo de metadatos, como el estado del trabajo la cantidad de entradas que se modificaron, sigue estos pasos. Para obtener más información sobre cómo solucionar problemas de un trabajo con errores, consulta el En la sección Visualiza registros de trabajos y soluciona problemas de este documento.

REST

Para obtener información sobre un trabajo de metadatos, usa el Método metadataJobs.get.

Obtener una lista de trabajos de metadatos

Puedes obtener una lista de los trabajos de metadatos más recientes. Trabajos más antiguos que tienen alcanzar un estado terminal se borran periódicamente del sistema.

REST

Para ver una lista de los trabajos de metadatos más recientes, usa el Método metadataJobs.list.

Cancela un trabajo de metadatos

Puedes cancelar un trabajo de metadatos que no deseas ejecutar.

REST

Para cancelar un trabajo de metadatos, usa el Método metadataJobs.cancel.

Ver registros de trabajos y solucionar problemas

Usar Cloud Logging para visualizar los registros de un trabajo de metadatos Para obtener más información, consulta Supervisa los registros de Dataplex.

Debes configurar el nivel de registro cuando creas un trabajo de metadatos. El siguiente registro niveles disponibles:

  • INFO: Proporciona registros a nivel del trabajo general. Incluye registros agregados sobre importar elementos, pero no especifica cuál de ellos tiene un error.

  • DEBUG: Proporciona registros detallados para cada elemento de importación. Usar el registro de nivel de depuración para solucionar problemas con artículos de importación específicos. Por ejemplo, usa el registro de nivel de depuración para identificar los recursos que faltan en el trabajo alcance, entradas o aspectos que no se ajusten al tipo de entrada asociado tipo de aspecto u otros errores de configuración del archivo de importación de metadatos.

Errores de validación

Dataplex valida los archivos de importación de metadatos con respecto al metadatos en tu proyecto. Si hay un problema de validación, es posible que el estado mostrar uno de los siguientes estados:

  • FAILED: sucede cuando el archivo de importación de metadatos tiene un error. Dataplex no importa metadatos y el trabajo falla. Ejemplos de errores en el archivo de importación de metadatos incluye los siguientes:
    • No se puede analizar un elemento del archivo como un elemento de importación válido
    • Una entrada o un aspecto en el archivo pertenece a un grupo de entradas, un tipo de entrada o tipo de aspecto que no forma parte del alcance del trabajo
    • Se especificó el mismo nombre de entrada más de una vez en el trabajo
    • Es un tipo de aspecto que se especifica en el mapa de aspecto o en las claves de aspecto. no usa el formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH
  • SUCCEEDED_WITH_ERRORS: sucede cuando el archivo de importación de metadatos se puede analizarse correctamente, pero importar un elemento en el archivo provocaría una entrada en tu proyecto esté en un estado incoherente. Dataplex ignora estas entradas, pero importa el resto de los metadatos del archivo.

Usar los registros de trabajos para solucionar el error

¿Qué sigue?