Importer les métadonnées

Vous pouvez importer les métadonnées du catalogue Dataplex, les entrées et leurs aspects, d'un système tiers Dataplex

Pour importer des métadonnées, procédez comme suit:

  1. Déterminer la portée du job

    Vous devez également comprendre comment Dataplex applique la logique de comparaison et le mode de synchronisation des entrées et des 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écuter un job d'importation de métadonnées

La procédure décrite sur cette page part du principe que vous connaissez Concepts du catalogue Dataplex : groupes d'entrées, types d'entrées, et types d'aspects. Pour en savoir plus, consultez Présentation du catalogue Dataplex

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éer des types d'aspects pour les aspects que vous souhaitez importer.
  3. Créer 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'un job 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.
  • Sync mode (Mode de synchronisation) : permet d'effectuer une mise à jour complète ou incrémentielle des mises à jour sur les entrées et les aspects du poste.
  • Fichier d'importation de métadonnées: fichier définissant les valeurs à définir pour les entrées. et les aspects du travail. Vous pouvez fournir plusieurs fichiers d'importation de métadonnées le même job de métadonnées. Vous enregistrez les fichiers dans Cloud Storage.
  • Logique de comparaison: comment Dataplex détermine les entrées et d'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 la portée du job, 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. Le poste modifie uniquement les entrées appartenant à ces types d'entrées. Le lieu d'un type d'entrée doit correspondre à celui du poste. le type d'entrée doit être global.

  • Types d'aspects: facultatifs. Spécifiez un ou plusieurs types d'aspects à inclure dans le travail. Si vous spécifiez une portée pour les types d'aspect, le job modifie uniquement les aspects qui appartiennent à ces types d'aspects. Le lieu d'un type d'aspect doit correspondre à celui du projet. le type d'aspect doit ê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 de métadonnées, l'entrée est supprimée lorsque vous exécutez le job de métadonnées.

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

  • INCREMENTAL: compatible avec certains 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.

Vous pouvez fournir plusieurs fichiers d'importation de métadonnées dans le même job 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 incluses dans le 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. Obtenir la liste des entrées actuelles de votre projet à utiliser comme point de départ, utilisez Méthode API entries.list.

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 des sections suivantes pour créer un fichier d'importation de métadonnées.

Structure du fichier

Chaque ligne du fichier d'importation de métadonnées contient un objet JSON qui correspond dans un seul élément à importer. 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 du fichier d'importation de métadonnées inclut les champs suivants. L'exemple suivant est formaté avec des sauts de ligne pour une meilleure lisibilité, mais lorsque vous enregistrez le fichier, n'incluez un retour à la ligne qu'après chaque importation élément. 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_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 qui est représentée par l'entrée suivante:
    • RESOURCE: nom de la ressource dans la source du système d'exploitation.
    • 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ées « carte d'aspects ».

    • ASPECT : aspect associé à l'entrée. Selon la manière dont l'aspect est associé à l'entrée, utilisez l'un des éléments suivants : formats:

      • 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, indiquez le type chemin d'accès, au format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH

    • KEY et VALUE: le contenu de selon son schéma de type d'aspect. Le contenu doit être encodé au format UTF-8. La taille maximale du champ est de 120 Ko.

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

    • ASPECT_UPDATE_TIMESTAMP: heure de mise à jour de l'aspect 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ées par un système externe.

  • UPDATE_MASK_FIELDS: champs à mettre à jour, dans les chemins d'accès par rapport à la ressource Entry. Séparez chaque champ par une virgule.

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

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

  • ASPECT_KEY : aspects à modifier. Compatible avec Syntaxe 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, dans le format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID

    Si vous laissez ce champ vide, le système considère qu'il spécifie exactement 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 relatives aux 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 nouvelle ligne (0x0a) pour séparer chaque élément importé.
  • Le fichier doit utiliser l'encodage des caractères UTF-8.
  • Les extensions de fichier compatibles sont .jsonl et .json.
  • La taille du fichier doit être inférieure à 1 Gio.
  • Les entrées et les aspects que vous spécifiez dans le fichier doivent faire partie du champ d'application de la tâche d'importation.
  • Le fichier doit être importé dans un bucket Cloud Storage. N'enregistrez pas dans un dossier nommé CLOUD_STORAGE_URI/deletions/.

Logique de comparaison

Dataplex détermine les entrées et les aspects à modifier en comparant les et les codes temporels fournis 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. La modification proposée doit être référencée dans le champ du masque de mise à jour ou dans l'aspect "keys" dans le fichier d'importation de 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 la source d'entrée crée un code temporel fichier d'importation de métadonnées est plus récent que le code temporel correspondant dans votre Dataplex recrée l'entrée dans votre projet.
    • Met à jour l'entrée. Si la source d'entrée met à jour le code temporel dans les métadonnées fichier d'importation 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 est inclus dans l'objet d'entrée du fichier d'importation de métadonnées, mais qu'il n'est pas inclus dans le champ de masque de mise à jour, Dataplex crée l'aspect.
    • Supprime un aspect. Si un aspect n'est pas inclus dans l'objet d'entrée dans le fichier d'importation des métadonnées, mais elle est incluse dans le champ du masque de mise à jour, Dataplex supprime l'aspect.

    • Met à jour un aspect. Si le code temporel de mise à jour de la source d'aspect dans les métadonnées fichier d'importation est plus récent que le code temporel correspondant dans votre projet, Dataplex met à jour l'aspect dans votre projet. Dataplex met également à jour l'aspect si l'entrée associée est l'absence d'un code temporel de mise à jour de la source d'entrée, ou si le code temporel de la source d'entrée du fichier d'importation de métadonnées est plus récente que l'horodatage correspondant dans votre projet.

      Toutefois, si au moins un aspect du fichier d'importation de métadonnées que l'horodatage correspondant dans votre projet, Dataplex n'effectue aucune mise à jour de 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 ingère les métadonnées de tous les fichiers enregistrés dans le bucket, y compris les fichiers qui se trouvent 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, tel que us-central1
  • METADATA_JOB_ID : Facultatif. ID de la tâche de métadonnées.

  • CLOUD_STORAGE_URI: URI de la Bucket ou 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 dans le champ d'application du poste, dans un format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID Pour en savoir plus, consultez la section Champ d'application du job.

  • 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 du job.
  • LOG_LEVEL : niveau des journaux à capturer, par exemple INFO ou DEBUG. Pour en savoir plus, consultez Affichez les journaux de jobs et résolvez 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 les détails d'un job 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 plus d'informations sur la résolution des problèmes de tâche, consultez la Afficher les journaux de jobs 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 Méthode metadataJobs.get.

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

Vous pouvez obtenir la liste des jobs de métadonnées les plus récents. 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 un job de métadonnées

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

REST

Pour annuler un job de métadonnées, utilisez la Méthode metadataJobs.cancel.

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

Utiliser Cloud Logging pour afficher les journaux d'un job 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 un job de métadonnées. Le journal suivant sont disponibles:

  • INFO: fournit des journaux au niveau global du job. Inclut des journaux agrégés sur importer des éléments, mais ne spécifie pas quel élément d'importation comporte une erreur.

  • DEBUG: fournit des journaux détaillés pour chaque élément d'importation. Utiliser 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 Journalisation de niveau débogage pour identifier les ressources manquantes dans le job d'une portée, d'entrées ou d'aspects non conformes au type d'entrée associé ou le type d'aspect ou d'autres erreurs de configuration du fichier d'importation de métadonnées.

Erreurs de validation

Dataplex valide les fichiers d'importation de métadonnées par rapport aux de métadonnées dans votre projet. En cas de problème de validation, l'état du job peut renvoient 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. Exemples d'erreurs dans le fichier d'importation de métadonnées sont les suivantes:
    • Impossible d'analyser un élément du fichier dans un é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 le plan d'aspect ou les touches 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és avec succès, mais l’importation d’un élément dans le fichier générerait une entrée dans votre projet dans un état incohérent. Dataplex ignore ces entrées, mais importe le reste des métadonnées du fichier.

Utilisez les journaux de jobs pour résoudre l'erreur.

Étape suivante