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 décrites dans cette section.

Rôles requis

Pour vous assurer que 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 Rôle IAM de lecteur des objets Storage (roles/storage.objectViewer) et l'autorisation storage.buckets.get sur le bucket.

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

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

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éer 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éer 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'un job de métadonnées:

  • Champ d'application de la tâche: le groupe d'entrées, les types d'entrées et les types d'aspects à inclure 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 métadonnées, vous modifiez les entrées et les aspects qui appartiennent aux ressources dans le du champ d'application du job.

Pour définir la portée du job, suivez ces consignes:

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

  • Entry types (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 du job lorsque vous créez un job de métadonnées.

Mode de synchronisation

Le mode de synchronisation permet de spécifier s'il faut effectuer une mise à jour complète une mise à jour incrémentielle sur les entrées et les aspects d'un job de métadonnées.

  • FULL: compatible avec les entrées. Toutes les entrées du champ d'application du job 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 certains 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 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 un job de métadonnées.

Fichier d'importation de métadonnées

Le fichier d'importation de métadonnées est une collection des entrées et des aspects que vous vous souhaitez modifier. Elle définit les valeurs à définir pour tous les champs qui appartiennent à ces entrées et aspects. Vous préparez le fichier avant d'exécuter un job 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 pour toutes les ressources comprises dans le champ d'application du job. Cela signifie que vous doit inclure des valeurs pour toutes les entrées d'une tâche, pas seulement les valeurs qui 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 tous les aspects que vous incluez dans le fichier doivent appartenir au les groupes d'entrées, les types d'entrées et les types d'aspects que vous définissez dans la portée de la tâche.

Suivez les instructions 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 importé 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 seul fichier d'importation de métadonnées. Toutefois, ne fournissent pas le même élément d'importation plusieurs fois dans une tâche de métadonnées. Utilisez un de retour à la ligne (0x0a) pour séparer chaque élément à importer.

Fichier d'importation de métadonnées avec un caractère de nouvelle ligne entre chaque apparence d'élément importé comme dans l'exemple suivant:

{ "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'ajoutez pas de saut de ligne entre les champs d'un même élément importé.

{
  "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: l'heure à laquelle l'entrée a été créés dans le système source.
    • ENTRY_UPDATE_TIMESTAMP: l'heure à laquelle l'entrée a été mis à 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: un 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 directement associé à l'entrée, indiquez la ressource relative nom 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 de création de l'aspect le système source.

    • ASPECT_UPDATE_TIMESTAMP: heure de mise à jour de l'aspect le système source.

    • PARENT_ENTRY: nom de 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 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 de liés directement à l'entrée.
    • ASPECT_TYPE_REFERENCE@PATH: correspond au type d'aspect et au chemin d'accès 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 présente les exigences suivantes:

  • Le fichier doit être mis en forme en tant que lignes JSON. qui est un fichier JSON délimité par un retour à 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 le champ d'application du job 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.

Dans les grandes lignes, Dataplex met à jour les valeurs de votre projet. Lorsqu'au moins une proposition de modification du fichier d'importation de métadonnées sera modifiée l'état de votre projet lorsque le job s'exécute, sans introduire de données données. 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 du job, Dataplex effectue une des éléments suivants:

  • Crée une entrée et les aspects qui lui sont 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 le fichier d'importation de métadonnées n'inclut pas l'entrée, 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, qui évalue les horodatages de source d'entrée et les horodatages de source d'aspect sont associés à l'entrée pour déterminer les valeurs à modifier. Ensuite, Dataplex effectue 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 d'importation de métadonnées, mais n'est pas incluse dans le champ du 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 horodatage de mise à jour de la source d'entrée, ou si l'horodatage 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 du code temporel que le code temporel 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 job. Procédez comme indiqué ci-dessous.

  1. Préparez un fichier d'importation de métadonnées en suivant les étapes ci-dessous : les directives 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 le même job de métadonnées. À si vous fournissez plusieurs fichiers, enregistrez-les dans le même bucket. 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 un job d'importation de métadonnées

Après avoir créé un fichier d'importation de métadonnées, exécutez un job d'importation de métadonnées à l'aide de la méthode API.

REST

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

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

  • PROJECT_NUMBER: numéro de votre projet Google Cloud ou l'ID du projet.
  • LOCATION_ID: emplacement Google Cloud, tel que us-central1
  • METADATA_JOB_ID : Facultatif. ID du job 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 plus sur les exigences relatives aux fichiers, consultez Fichier d'importation de métadonnées.

  • ENTRY_GROUP: nom de ressource relatif du groupe d'entrées qui entrent dans le champ d'application de la tâche, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID Fournissez un seul groupe d'entrées. Pour en savoir plus, consultez la section Champ d'application du job.

  • 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 aspect dans le champ d'application du job, 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 de 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 en savoir plus 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 jobs de métadonnées

Vous pouvez obtenir la liste des jobs de métadonnées les plus récents. Les emplois plus anciens qui ont atteint un état final sont régulièrement supprimés du système.

REST

Pour obtenir la liste des jobs de métadonnées les plus récents, utilisez le Méthode metadataJobs.list.

Annuler un job de métadonnées

Vous pouvez annuler un job 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 de jobs 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 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 en cas d'erreur dans le fichier d'importation de métadonnées. Dataplex n'importe aucune métadonnée et le job échoue. Exemples d'erreurs dans le fichier d'importation de métadonnées sont les suivantes: <ph type="x-smartling-placeholder">
      </ph>
    • 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 de la portée du job
    • Le même nom d'entrée est spécifié plusieurs fois dans le job
    • 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 à partir du fichier.

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

Étape suivante