Importer des métadonnées à l'aide d'un pipeline personnalisé

Ce document explique comment importer des métadonnées du catalogue Dataplex à partir d'un système tiers dans Dataplex à l'aide des méthodes de l'API d'importation de métadonnées et de votre propre pipeline. Les métadonnées du catalogue Dataplex se composent d'entrées et de leurs aspects.

Si vous souhaitez plutôt utiliser un pipeline d'orchestration géré par Google Cloudpour extraire et importer des métadonnées, nous vous recommandons d'utiliser un pipeline de connectivité géré. Avec un pipeline de connectivité géré, vous apportez votre propre connecteur qui extrait les métadonnées et génère une sortie dans un format pouvant être utilisé comme entrée par les méthodes de l'API d'importation de métadonnées (fichier d'importation de métadonnées). Vous utilisez ensuite des workflows pour orchestrer les tâches du pipeline.

Étapes majeures

Pour importer des métadonnées à l'aide de l'API d'importation de métadonnées, procédez comme suit:

  1. Déterminez le champ d'application de la tâche.

    Découvrez également comment Dataplex applique la logique de comparaison et le mode de synchronisation pour les entrées et les aspects.

  2. Créez un ou plusieurs fichiers d'importation de métadonnées qui définissent les données à importer.

  3. Enregistrez les fichiers d'importation de métadonnées dans un bucket Cloud Storage.

  4. Exécutez une tâche d'importation de métadonnées.

Les étapes de cette page supposent que vous connaissez les concepts du catalogue Dataplex, y compris les groupes d'entrées, les types d'entrées et les types d'aspects. Pour en savoir plus, consultez la page Présentation de Dataplex Catalog.

Avant de commencer

Avant d'importer des métadonnées, effectuez les tâches de cette section.

Rôles requis

Pour vous assurer que le compte de service Dataplex dispose des autorisations nécessaires pour accéder au bucket Cloud Storage, demandez à votre administrateur d'accorder au compte de service Dataplex le rôle IAM Lecteur des objets Storage (roles/storage.objectViewer) et l'autorisation storage.buckets.get sur le bucket.

Pour obtenir les autorisations nécessaires pour gérer les jobs de métadonnées, demandez à votre administrateur de vous accorder les rôles IAM suivants:

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Créer des ressources Google Cloud

Préparez les ressources Google Cloud suivantes:

  1. Créez un groupe d'entrées pour les entrées que vous souhaitez importer.
  2. Créez des types d'aspects pour les aspects que vous souhaitez importer.
  3. Créez des types d'entrées pour les entrées que vous souhaitez importer.
  4. Créez un bucket Cloud Storage pour stocker vos fichiers d'importation de métadonnées.

Composants d'une tâche de métadonnées

Lorsque vous importez des métadonnées, tenez compte des composants suivants d'une tâche de métadonnées:

  • Champ d'application de la tâche: groupe d'entrées, types d'entrées et types d'aspects à inclure dans la tâche.
  • Mode de synchronisation: indique si une mise à jour complète ou incrémentielle doit être effectuée sur les entrées et les aspects de la tâche.
  • Fichier d'importation de métadonnées: fichier qui définit les valeurs à définir pour les entrées et les aspects de la tâche. Vous pouvez fournir plusieurs fichiers d'importation de métadonnées dans le même job de métadonnées. Vous enregistrez les fichiers dans Cloud Storage.
  • Logique de comparaison: méthode utilisée par Dataplex pour déterminer les entrées et les aspects à modifier.

Champ d'application du job

Le champ d'application de la tâche définit le groupe d'entrées, les types d'entrées et éventuellement les types d'aspects que vous souhaitez inclure dans une tâche de métadonnées. Lorsque vous importez des métadonnées, vous modifiez les entrées et les aspects qui appartiennent aux ressources du champ d'application de la tâche.

Pour définir le champ d'application de la tâche, suivez ces consignes:

  • Groupe d'entrées: spécifiez un seul groupe d'entrées à inclure dans la tâche. La tâche ne modifie que les entrées appartenant à ce groupe d'entrées. Le groupe d'entrée et l'offre d'emploi doivent se trouver dans la même région.

  • Types d'entrées: spécifiez un ou plusieurs types d'entrées à inclure dans la tâche. La tâche ne modifie que les entrées appartenant à ces types d'entrées. L'emplacement d'un type d'entrée doit correspondre à celui de l'offre d'emploi ou être global.

  • Types d'aspects: facultatif. Spécifiez un ou plusieurs types d'aspects à inclure dans la tâche. Si vous spécifiez un champ d'application pour les types d'aspects, la tâche ne modifie que les aspects qui appartiennent à ces types d'aspects. L'emplacement d'un type d'aspect doit correspondre à celui de l'offre d'emploi ou être global.

Vous spécifiez le champ d'application de la tâche lorsque vous créez une tâche de métadonnées.

Mode de synchronisation

Le mode de synchronisation spécifie si une mise à jour complète ou incrémentielle doit être effectuée sur les entrées et les aspects d'une tâche de métadonnées.

  • FULL: compatible avec les entrées. Toutes les entrées de la portée de la tâche sont modifiées.

    Si une entrée existe dans Dataplex, mais n'est pas incluse dans le fichier d'importation des métadonnées, elle est supprimée lorsque vous exécutez la tâche de métadonnées.

    La synchronisation complète n'est pas disponible pour les aspects.

  • INCREMENTAL: compatible avec les aspects. Un aspect n'est modifié que si le fichier d'importation de métadonnées inclut une référence à l'aspect dans les champs updateMask et aspectKeys. Pour en savoir plus sur ces champs dans le fichier d'importation de métadonnées, consultez la section Structure d'un élément d'importation de ce document.

    La synchronisation incrémentielle n'est pas compatible avec les entrées.

Vous spécifiez le mode de synchronisation lorsque vous créez une tâche de métadonnées.

Fichier d'importation de métadonnées

Le fichier d'importation des métadonnées est une collection des entrées et des aspects que vous souhaitez modifier. Il définit les valeurs à définir pour tous les champs appartenant à ces entrées et aspects. Vous devez préparer le fichier avant d'exécuter une tâche de métadonnées.

Voici les consignes générales à suivre:

  • Vous pouvez fournir plusieurs fichiers d'importation de métadonnées dans la même tâche de métadonnées.

  • Les entrées que vous fournissez dans le fichier remplacent complètement toutes les entrées existantes pour toutes les ressources qui relèvent du champ d'application de la tâche. Cela signifie que vous devez inclure des valeurs pour toutes les entrées d'une tâche, et pas seulement celles que vous souhaitez ajouter ou mettre à jour. Pour obtenir la liste des entrées actuelles de votre projet à utiliser comme point de départ, utilisez la méthode API entries.list.

  • Vous devez fournir un fichier d'importation de métadonnées dans le cadre d'une tâche de métadonnées. Si vous souhaitez supprimer toutes les données existantes pour les entrées incluses dans le champ d'application de la tâche, fournissez un fichier d'importation de métadonnées vide.

  • Toutes les entrées et les aspects que vous incluez dans le fichier doivent appartenir aux groupes d'entrées, aux types d'entrées et aux types d'aspects que vous définissez dans le champ d'application de la tâche.

Suivez les consignes détaillées des sections suivantes pour créer un fichier d'importation de métadonnées.

Structure du fichier

Chaque ligne du fichier d'importation des métadonnées contient un objet JSON correspondant à un élément d'importation. Un élément d'importation est un objet qui décrit les valeurs à modifier pour une entrée et ses aspects associés.

Vous pouvez fournir plusieurs éléments d'importation dans un même fichier d'importation de métadonnées. Toutefois, ne fournissez pas le même élément d'importation plusieurs fois dans une tâche de métadonnées. Utilisez un caractère de retour à la ligne (0x0a) pour séparer chaque élément d'importation.

Un fichier d'importation de métadonnées avec un caractère de nouvelle ligne entre chaque élément d'importation se présente comme suit:

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

Structure d'un élément d'importation

Chaque élément d'importation du fichier d'importation de métadonnées inclut les champs suivants (voir ImportItem). L'exemple suivant est mis en forme avec des sauts de ligne pour une meilleure lisibilité, mais lorsque vous enregistrez le fichier, n'incluez un caractère de nouvelle ligne qu'après chaque élément d'importation. N'incluez pas de sauts de ligne entre les champs d'un même élément d'importation.

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

Remplacez les éléments suivants :

  • entry: informations sur une entrée et ses aspects associés:

    • ENTRY_NAME: nom de ressource relatif de l'entrée, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID.
    • ENTRY_TYPE: nom de ressource relatif du type d'entrée utilisé pour créer cette entrée, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.
    • entrySource: informations du système source sur la ressource de données représentée par l'entrée :
      • RESOURCE: nom de la ressource dans le système source.
      • SYSTEM: nom du système source.
      • PLATFORM: plate-forme contenant le système source.
      • DISPLAY_NAME: nom à afficher convivial.
      • DESCRIPTION: description de l'entrée.
      • ENTRY_CREATE_TIMESTAMP: heure à laquelle l'entrée a été créée dans le système source.
      • ENTRY_UPDATE_TIMESTAMP: heure à laquelle l'entrée a été mise à jour dans le système source.

    • aspects: aspects associés à l'entrée. L'objet aspect et ses données sont appelés carte d'aspect.

      • ASPECT: aspect associé à l'entrée. Selon la façon dont l'aspect est associé à l'entrée, utilisez l'un des formats suivants:

        • Si l'aspect est associé directement à l'entrée, indiquez le nom de la ressource relative de son type d'aspect, au format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.
        • Si l'aspect est associé au chemin d'accès de l'entrée, fournissez le chemin d'accès du type d'aspect, au format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH.

      • KEY et VALUE: contenu de l'aspect, conformément au modèle de métadonnées de son type d'aspect. Le contenu doit être encodé au format UTF-8. La taille maximale du champ est de 120 Ko. Le dictionnaire data est obligatoire, même s'il est vide.

      • ASPECT_CREATE_TIMESTAMP: heure à laquelle l'aspect a été créé dans le système source.

      • ASPECT_UPDATE_TIMESTAMP: heure à laquelle l'aspect a été mis à jour dans le système source.

    • PARENT_ENTRY: nom de la ressource de l'entrée parente.

    • FULLY_QUALIFIED_NAME: nom de l'entrée pouvant être référencé par un système externe. Consultez la section Noms complets.

  • UPDATE_MASK_FIELDS: champs à mettre à jour, dans des chemins relatifs à la ressource Entry. Séparez chaque champ par une virgule.

    En mode de synchronisation des entrées FULL, Dataplex inclut les chemins de tous les champs d'une entrée pouvant être modifiés, y compris les aspects.

    Le champ updateMask est ignoré lorsqu'une entrée est créée ou recréée.

  • ASPECT_KEY: aspects à modifier. Compatible avec les syntaxes suivantes:

    • ASPECT_TYPE_REFERENCE: correspond au type d'aspect pour les aspects associés directement à l'entrée.
    • ASPECT_TYPE_REFERENCE@PATH : correspond au type d'aspect et au chemin spécifié.
    • ASPECT_TYPE_REFERENCE@*: correspond au type d'aspect pour tous les chemins.

    Remplacez ASPECT_TYPE_REFERENCE par une référence au type d'aspect, au format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.

    Si vous laissez ce champ vide, il est considéré comme spécifiant exactement les aspects présents dans l'entrée spécifiée.

    En mode de synchronisation des entrées FULL, Dataplex ajoute implicitement les clés pour tous les aspects requis d'une entrée.

Exigences pour les fichiers

Le fichier d'importation de métadonnées doit respecter les exigences suivantes:

  • Le fichier doit être au format JSON Lines, qui est un fichier JSON délimité par des retours à la ligne. Utilisez un caractère de retour à la ligne (0x0a) pour séparer chaque élément d'importation.
  • Le fichier doit utiliser l'encodage de caractères UTF-8.
  • Les extensions de fichier compatibles sont .jsonl et .json.
  • La taille de chaque fichier d'importation de métadonnées doit être inférieure à 1 Go. La taille totale maximale de toutes les données de la tâche de métadonnées est de 3 Go. Cela inclut tous les fichiers et métadonnées associés à la tâche.
  • Les entrées et les aspects que vous spécifiez dans le fichier doivent faire partie du champ d'application de la tâche de métadonnées.
  • Le fichier doit être importé dans un bucket Cloud Storage. N'enregistrez pas le fichier dans un dossier nommé CLOUD_STORAGE_URI/deletions/.

Logique de comparaison

Dataplex détermine les entrées et les aspects à modifier en comparant les valeurs et les codes temporels que vous fournissez dans le fichier d'importation de métadonnées avec les valeurs et les codes temporels existants dans votre projet.

De manière générale, Dataplex met à jour les valeurs de votre projet lorsqu'au moins une modification proposée dans le fichier d'importation de métadonnées modifie l'état de votre projet lors de l'exécution de la tâche, sans introduire de données obsolètes. Le changement proposé doit être référencé dans le champ "Masque de mise à jour" ou le champ "Clés d'aspect" du fichier d'importation des métadonnées.

Pour chaque entrée faisant partie du champ d'application de la tâche, Dataplex effectue l'une des opérations suivantes:

  • Crée une entrée et des aspects associés. Si le fichier d'importation de métadonnées inclut une entrée qui n'existe pas dans votre projet, Dataplex crée l'entrée et les aspects associés.
  • Supprime une entrée et les aspects associés. Si une entrée existe dans votre projet, mais que le fichier d'importation de métadonnées ne l'inclut pas, Dataplex supprime l'entrée et ses aspects associés de votre projet.

  • Met à jour une entrée et les aspects associés. Si une entrée existe à la fois dans le fichier d'importation de métadonnées et dans votre projet, Dataplex évalue les codes temporels de la source de l'entrée et les codes temporels de la source de l'aspect associés à l'entrée pour déterminer les valeurs à modifier. Dataplex effectue ensuite l'une ou plusieurs des opérations suivantes:

    • Recrée l'entrée. Si le code temporel de création de la source d'entrée dans le fichier d'importation de métadonnées est plus récent que le code temporel correspondant dans votre projet, Dataplex recrée l'entrée dans votre projet.
    • Met à jour l'entrée. Si le code temporel de mise à jour de la source d'entrée dans le fichier d'importation des métadonnées est plus récent que le code temporel correspondant dans votre projet, Dataplex met à jour l'entrée dans votre projet.
    • Crée un aspect. Si un aspect n'existe pas dans votre projet et qu'il est inclus dans l'objet d'entrée, le champ de masque de mise à jour et le champ de clés d'aspect dans le fichier d'importation de métadonnées, Dataplex crée l'aspect.
    • Supprime un aspect. Si un aspect existe dans votre projet et est inclus dans le champ "Masque de mise à jour" et le champ "Clés d'aspect" du fichier d'importation de métadonnées, mais qu'il n'est pas inclus dans l'objet d'entrée, Dataplex le supprime.

    • Met à jour un aspect. Si un aspect existe dans votre projet et est inclus dans l'objet d'entrée, le champ de masque de mise à jour et le champ de clés d'aspect dans le fichier d'importation de métadonnées, et que le code temporel de mise à jour de la source d'aspect dans le fichier d'importation de métadonnées est plus récent que le code temporel correspondant dans votre projet, Dataplex met à jour l'aspect.

      Si aucun code temporel de mise à jour de la source d'un aspect n'est fourni dans le fichier d'importation des métadonnées, mais que l'entrée correspondante est marquée pour une mise à jour, Dataplex met également à jour l'aspect.

      Toutefois, si au moins un aspect du fichier d'importation de métadonnées possède un code temporel plus ancien que celui correspondant dans votre projet, Dataplex n'effectue aucune mise à jour pour l'entrée jointe.

Créer un fichier d'importation de métadonnées

Avant d'importer des métadonnées, créez un fichier d'importation de métadonnées pour votre tâche. Procédez comme indiqué ci-dessous.

  1. Préparez un fichier d'importation de métadonnées en suivant les consignes décrites précédemment dans ce document.
  2. Importez le fichier dans un bucket Cloud Storage.

Vous pouvez fournir plusieurs fichiers d'importation de métadonnées dans la même tâche de métadonnées. Pour fournir plusieurs fichiers, enregistrez-les dans le même bucket Cloud Storage. Lorsque vous exécutez la tâche, vous spécifiez un bucket, et non un fichier spécifique. Dataplex importe les métadonnées de tous les fichiers enregistrés dans le bucket, y compris les fichiers situés dans des sous-dossiers.

Exécuter une tâche d'importation de métadonnées

Après avoir créé un fichier d'importation de métadonnées, exécutez une tâche d'importation de métadonnées à l'aide de l'API.

REST

Pour importer des métadonnées, utilisez la méthode metadataJobs.create.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_NUMBER: numéro ou ID de votre projet Google Cloud .
  • LOCATION_ID: emplacement Google Cloud , par exemple us-central1.
  • METADATA_JOB_ID : Facultatif. ID de la tâche de métadonnées.

  • CLOUD_STORAGE_URI: URI du bucket ou du dossier Cloud Storage contenant les fichiers d'importation de métadonnées. Pour en savoir plus sur les exigences concernant les fichiers, consultez la section Fichier d'importation de métadonnées.

  • ENTRY_GROUP: nom de ressource relatif du groupe d'entrée concerné par la tâche, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Indiquez un seul groupe d'entrées. Pour en savoir plus, consultez la section Champ d'application de la tâche.

  • ENTRY_TYPE: nom de ressource relatif d'un type d'entrée inclus dans le champ d'application de la tâche, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID. Pour en savoir plus, consultez la section Champ d'application de la tâche.

  • ASPECT_TYPE : Facultatif. Nom de ressource relatif d'un type d'aspect inclus dans le champ d'application de la tâche, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID. Pour en savoir plus, consultez la section Champ d'application de la tâche.
  • LOG_LEVEL: niveau des journaux à capturer, par exemple INFO ou DEBUG. Pour en savoir plus, consultez la section Afficher les journaux des tâches et résoudre les problèmes.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

La réponse identifie une opération de longue durée.

Obtenir des informations sur une tâche de métadonnées

Pour obtenir des informations sur une tâche de métadonnées, telles que son état et le nombre d'entrées modifiées, procédez comme suit. Pour savoir comment résoudre les problèmes liés à une tâche ayant échoué, consultez la section Afficher les journaux de tâches et résoudre les problèmes de ce document.

REST

Pour obtenir des informations sur un job de métadonnées, utilisez la méthode metadataJobs.get.

Obtenir la liste des tâches de métadonnées

Vous pouvez obtenir la liste des tâches de métadonnées les plus récentes. Les tâches plus anciennes qui ont atteint un état terminal sont supprimées régulièrement du système.

REST

Pour obtenir la liste des tâches de métadonnées les plus récentes, utilisez la méthode metadataJobs.list.

Annuler une tâche de métadonnées

Vous pouvez annuler une tâche de métadonnées que vous ne souhaitez pas exécuter.

REST

Pour annuler une tâche de métadonnées, utilisez la méthode metadataJobs.cancel.

Afficher les journaux des tâches et résoudre les problèmes

Utilisez Cloud Logging pour afficher les journaux d'une tâche de métadonnées. Pour en savoir plus, consultez la page Surveiller les journaux Dataplex.

Vous configurez le niveau de journalisation lorsque vous créez une tâche de métadonnées. Les niveaux de journalisation suivants sont disponibles:

  • INFO: fournit des journaux au niveau de l'ensemble de la tâche. Inclut des journaux agrégés sur les éléments d'importation, mais ne spécifie pas l'élément d'importation qui présente une erreur.

  • DEBUG: fournit des journaux détaillés pour chaque élément d'importation. Utilisez la journalisation au niveau du débogage pour résoudre les problèmes liés à des éléments d'importation spécifiques. Par exemple, utilisez la journalisation au niveau du débogage pour identifier les ressources manquantes dans le champ d'application de la tâche, les entrées ou les aspects qui ne respectent pas le type d'entrée ou le type d'aspect associé, ou d'autres erreurs de configuration avec le fichier d'importation de métadonnées.

Erreurs de validation

Dataplex valide les fichiers d'importation de métadonnées par rapport aux métadonnées actuelles de votre projet. En cas de problème de validation, l'état de la tâche peut renvoyer l'un des états suivants:

  • FAILED: se produit lorsqu'une erreur se produit dans le fichier d'importation des métadonnées. Dataplex n'importe aucune métadonnées et la tâche échoue. Voici quelques exemples d'erreurs dans le fichier d'importation de métadonnées :
    • Un élément du fichier ne peut pas être analysé en tant qu'élément d'importation valide
    • Une entrée ou un aspect du fichier appartient à un groupe d'entrées, un type d'entrée ou un type d'aspect qui ne fait pas partie du champ d'application de la tâche
    • Le même nom d'entrée est spécifié plusieurs fois dans la tâche
    • Un type d'aspect spécifié dans la carte des aspects ou les clés d'aspect n'utilise pas le format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH.
  • SUCCEEDED_WITH_ERRORS: se produit lorsque le fichier d'importation de métadonnées peut être analysé avec succès, mais que l'importation d'un élément du fichier entraînerait un état incohérent dans une entrée de votre projet. Dataplex ignore ces entrées, mais importe le reste des métadonnées du fichier.

Utilisez les journaux de tâche pour résoudre l'erreur.

Étape suivante