Importa metadatos con una canalización personalizada

En este documento, se describe cómo importar metadatos de Dataplex Catalog de un sistema de terceros a Dataplex con la API de importación de metadatos y tu propia canalización. Metadatos de Dataplex Catalog consta de entradas y sus aspectos.

Si, en cambio, deseas usar una canalización de orquestación administrada por Google Cloud para extraer e importar metadatos, te sugerimos que uses una canalización de conectividad administrada. Con una canalización de conectividad administrada, puedes usar tu propio conector que extrae los metadatos y genera un resultado en un formato que los métodos de la API de importación de metadatos (el archivo de importación de metadatos) pueden usar como entrada. Luego, usas Workflows para organizar las tareas de canalización.

Pasos de alto nivel

Para importar metadatos con la API de importación de metadatos, sigue estos pasos generales:

  1. Determinar el alcance del trabajo.

    Además, comprende cómo Dataplex aplica la lógica de comparación y el modo de sincronización para las entradas y los aspectos.

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

  3. Guarda 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 de Dataplex Catalog.

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 trabajos de metadatos, haz lo siguiente: solicita a tu administrador que te otorgue el 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.

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 aspectos para los aspectos que deseas importar.
  3. Crea tipos de entrada para las entradas que deseas 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: Es el grupo de entrada, los tipos de entrada y los tipos de aspecto que se incluirán en el trabajo.
  • Modo de sincronización: Indica si se debe realizar una actualización completa o incremental de las entradas y los aspectos del trabajo.
  • Archivo de importación de metadatos: Es un archivo que define los valores que se establecerán para las entradas y los aspectos de la tarea. 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.

Alcance del trabajo

El alcance del trabajo define el grupo de entrada, los tipos de entrada y, de manera opcional, los tipos de aspecto que deseas incluir en un trabajo de metadatos. Cuando importas metadatos, modificas las entradas y los aspectos que pertenecen a los recursos dentro del alcance de la tarea.

Para definir el alcance del trabajo, sigue estas pautas:

  • Grupo de entrada: Especifica un solo grupo de entrada para incluirlo en el trabajo. La tarea 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 la tarea. 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 aspectos para incluirlos en el trabajo. Si especificas un alcance para los tipos de aspectos, 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 o el tipo de aspecto debe ser global.

El alcance 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 una actualización incremental en las entradas y los aspectos de un trabajo de metadatos.

  • FULL: Se admite para las entradas. Se modifican todas las entradas del alcance del trabajo.

    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: Se admite para los 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 sobre estos campos en el archivo de importación de metadatos, consulta la sección Estructura de un elemento de importación de este documento.

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

Especificas el modo de sincronización 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 establecerán para todos los campos que pertenecen a estas entradas y aspectos. Prepara el archivo antes de ejecutar un trabajo de metadatos.

Se aplican estos lineamientos generales:

  • 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 existentes de los recursos que se encuentren dentro del alcance del trabajo. Esto significa que 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 usarlo como punto de partida, usa el Método de la API de entries.list.

  • Debes proporcionar un archivo de importación de metadatos como parte de un trabajo de metadatos. Si quieres borrar todos los datos existentes de las entradas que se encuentran dentro del alcance del trabajo, proporciona un archivo de importación de metadatos vacío.

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

Usa los lineamientos detallados 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 deben 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 línea nueva (0x0a) para separar cada elemento de importación.

Un archivo de importación de metadatos con un carácter de nueva línea entre cada elemento de importación se ve como 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 del archivo de importación de metadatos incluye los siguientes campos (consulta ImportItem). El siguiente ejemplo tiene formato con saltos de línea para facilitar la lectura, pero cuando guardes el archivo, incluye un carácter de nueva línea solo después de cada elemento de importación. 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 de recurso relativo del 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 el sistema de origen.
    • SYSTEM: Es el nombre del sistema de origen.
    • PLATFORM: Es la plataforma que contiene el sistema de origen.
    • DISPLAY_NAME: Un nombre visible fácil de usar.
    • DESCRIPTION: Es una descripción de la entrada.
    • ENTRY_CREATE_TIMESTAMP: La hora en la que se creó la entrada en el sistema de origen.
    • ENTRY_UPDATE_TIMESTAMP: La hora en la que se actualizó la entrada en el sistema de origen.

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

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

      • Si el aspecto se adjunta directamente a la entrada, proporciona el nombre del recurso relativo 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 del aspecto, según su plantilla de metadatos de tipo de aspecto El contenido debe estar codificado como UTF-8. El tamaño máximo del campo es de 120 KB. El diccionario data es obligatorio, incluso si está vacío.

    • ASPECT_CREATE_TIMESTAMP: Es la hora en la que se creó el aspecto en el sistema de origen.

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

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

    • FULLY_QUALIFIED_NAME: Es un nombre para la entrada al que puede hacer referencia un sistema externo. Consulta Nombres completamente calificados.

  • 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 entradas FULL, Dataplex incluye las rutas de acceso de todos los campos de una entrada que se pueden modificar, incluidos los aspectos.

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

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

    • ASPECT_TYPE_REFERENCE: Coincide con el tipo de aspecto de los aspectos que se adjuntan directamente a la entrada.
    • ASPECT_TYPE_REFERENCE@PATH: coincide 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 de importación.
  • El archivo debe usar la codificación de caracteres UTF-8.
  • Las extensiones de archivo compatibles son .jsonl y .json.
  • El tamaño de cada archivo de importación de metadatos debe ser inferior a 1 GiB. El tamaño máximo total de todos los datos en la tarea de metadatos es de 3 GB. Esta incluye todos los archivos y metadatos asociados al trabajo.
  • Las entradas y los aspectos que especifiques en el archivo deben ser parte del alcance del trabajo de metadatos.
  • 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.

Para cada entrada que forma parte del alcance del trabajo, Dataplex realiza una de las siguientes acciones:

  • 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 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 aspectos que están asociadas 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 marca de tiempo de creación de la fuente de entrada en el archivo de importación de metadatos es más reciente que la marca de tiempo correspondiente en tu proyecto, Dataplex vuelve a crear la entrada en tu proyecto.
    • Actualiza la entrada. Si la marca de tiempo de actualización de la fuente de la entrada en el archivo de importación de metadatos es más reciente que la marca de tiempo correspondiente en tu proyecto, Dataplex actualiza la entrada en tu proyecto.
    • Crea un aspecto. Si un aspecto no existe en tu proyecto y se incluye en el objeto de entrada, el campo de máscara de actualización y el campo de claves de aspecto en el archivo de importación de metadatos, Dataplex lo crea.
    • Borra un aspecto. Si existe un aspecto en tu proyecto y se incluye en el campo de máscara de actualización y en el campo de claves de aspecto del archivo de importación de metadatos, pero no se incluye en el objeto de entrada, Dataplex borra el aspecto.

    • Actualiza un aspecto. Si existe un aspecto en tu proyecto y está incluido en el objeto de entrada, el campo de máscara de actualización y el campo de claves de aspecto de el archivo de importación de metadatos y la marca de tiempo de actualización de la fuente de aspecto en la de importación de metadatos es más reciente que la marca de tiempo correspondiente en tu proyecto, Dataplex actualiza el aspecto.

      Si no se proporciona una marca de tiempo de actualización de la fuente de aspectos en el archivo de importación de metadatos, pero la entrada correspondiente está marcada para una actualización, Dataplex también actualiza el aspecto.

      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 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, guárdalos en el mismo bucket de Cloud Storage. Cuando ejecutas el trabajo, especificas un bucket, no un archivo específico. Dataplex importa los metadatos de todos los archivos que se guardan 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 la API.

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 bucket o la carpeta de Cloud Storage que contiene los archivos de importación de metadatos. Para obtener más información 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 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. 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 los registros de trabajo 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.

Cómo 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 general de la tarea. 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. Usa el registro a nivel de depuración para solucionar problemas con elementos de importación específicos. Por ejemplo, usa el registro a nivel de depuración para identificar los recursos que faltan en el ámbito del trabajo, las entradas o los aspectos que no se ajustan al tipo de entrada o al tipo de aspecto asociados, o bien otros parámetros de configuración incorrectos con el archivo de importación de metadatos.

Errores de validación

Dataplex valida los archivos de importación de metadatos en función de los metadatos actuales de tu proyecto. Si hay un problema de validación, el estado del trabajo podría mostrar uno de los siguientes estados:

  • FAILED: Ocurre cuando el archivo de importación de metadatos tiene un error. Dataplex no importa ningún metadato 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 del archivo pertenecen a un grupo de entradas, un tipo de entrada o un tipo de aspecto que no forma parte del alcance del trabajo
    • Se especifica 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: Ocurre cuando el archivo de importación de metadatos se puede analizar correctamente, pero la importación de un elemento del archivo causaría que una entrada de 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?