Exporter les métadonnées

Vous pouvez exporter des métadonnées de Dataplex Universal Catalog pour les utiliser dans des systèmes externes en exécutant un job d'exportation de métadonnées.

Vous pouvez exporter des métadonnées dans les cas suivants :

  • Interroger et analyser les métadonnées avec BigQuery ou d'autres outils d'analyse de données
  • Traiter de grands volumes de métadonnées de manière programmatique, que vous pourrez ensuite réimporter dans Dataplex Universal Catalog
  • Intégrer des métadonnées dans des applications personnalisées ou des outils tiers

Un job d'exportation de métadonnées exporte un instantané de vos métadonnées Dataplex Universal Catalog. Les métadonnées Dataplex Universal Catalog se composent d'entrées et de leurs aspects. Les étapes décrites sur cette page supposent que vous êtes familiarisé avec les concepts de métadonnées de Dataplex Universal Catalog, y compris les groupes d'entrées, les types d'entrées et les types d'aspects.

Champ d'application du job

Le champ d'application du job définit les métadonnées à exporter. Vous devez fournir l'une des portées de tâche suivantes pour chaque tâche d'exportation de métadonnées :

  • Organisation : exporte les métadonnées appartenant à votre organisation.
  • Projets : exporte les métadonnées appartenant aux projets spécifiés.
  • Groupes d'entrées : exporte les métadonnées appartenant aux groupes d'entrées spécifiés.

Vous pouvez restreindre davantage le champ d'application en spécifiant les types d'entrées ou d'aspects à inclure dans le job. Le job n'exporte que les entrées et les aspects qui appartiennent à ces types d'entrées et d'aspects.

VPC Service Controls

Le catalogue universel Dataplex utilise VPC Service Controls pour renforcer la sécurité des jobs d'exportation de métadonnées. Le projet auquel appartient le job détermine le périmètre VPC Service Controls, comme suit :

  • Si vous définissez le champ d'application du job au niveau de l'organisation, les éléments suivants se produisent :
    • Le champ d'application de l'exportation correspond à l'organisation à laquelle appartient le job.
    • Seules les entrées qui se trouvent dans le périmètre VPC Service Controls sont exportées.
    • Tous les projets qui se trouvent dans l'organisation du job, mais en dehors du périmètre VPC Service Controls, sont exclus.
  • Si vous définissez le champ d'application du job sur des projets ou des groupes d'entrées, ceux-ci doivent se trouver dans le même périmètre VPC Service Controls que le job. Si l'un des projets ou groupes d'entrées ne respecte pas les règles de VPC Service Controls, le job échoue.

Avant de commencer

Avant d'exporter des métadonnées, effectuez les tâches décrites dans cette section.

Rôles requis pour les utilisateurs finaux

Pour obtenir les autorisations nécessaires pour gérer les jobs d'exportation 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 Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour gérer les jobs d'exportation de métadonnées. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour gérer les jobs d'exportation de métadonnées :

  • Exporter les métadonnées :
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • Accédez aux résultats exportés : storage.objects.get

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

Rôles requis pour le compte de service Dataplex Universal Catalog

Pour vous assurer que le compte de service Dataplex Universal Catalog dispose des autorisations nécessaires pour accéder au bucket Cloud Storage, demandez à votre administrateur d'accorder au compte de service Dataplex Universal Catalog les autorisations suivantes sur le bucket : storage.buckets.get, storage.objects.get et storage.objects.create.

Configurer les ressources Google Cloud

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Créez un bucket Cloud Storage pour stocker les résultats exportés.

    Le bucket doit se trouver au même emplacement et dans le même périmètre VPC Service Controls que le job de métadonnées.

Exécuter un job d'exportation de métadonnées

Les sections suivantes expliquent comment exporter des métadonnées avec différentes portées de job.

Exporter des métadonnées depuis votre organisation

Pour exporter les métadonnées de votre organisation, utilisez la méthode metadataJobs.create et définissez le booléen organizationLevel sur true.

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

  • JOB_PROJECT : projet Google Clouddans lequel vous exécutez le job de métadonnées. Indiquez un numéro ou un ID de projet.
  • LOCATION_ID : emplacement Google Cloud , par exemple us-central1.
  • METADATA_JOB_ID : Facultatif. ID du job de métadonnées.

  • BUCKET : bucket Cloud Storage vers lequel exporter les métadonnées.

    Vous pouvez éventuellement inclure un préfixe personnalisé après le nom du bucket, au format gs://BUCKET/PREFIX/. La longueur maximale du préfixe personnalisé est de 128 caractères.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

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

La réponse identifie une opération de longue durée. Les métadonnées exportées sont enregistrées dans un bucket Cloud Storage.

Exporter des métadonnées de projets spécifiques

Pour exporter des métadonnées d'un ou de plusieurs projets, utilisez la méthode metadataJobs.create et fournissez une liste de projets.

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

  • JOB_PROJECT : projet Google Clouddans lequel vous exécutez le job de métadonnées. Indiquez un numéro ou un ID de projet.
  • LOCATION_ID : emplacement Google Cloud , par exemple us-central1.
  • METADATA_JOB_ID : Facultatif. ID du job de métadonnées.

  • BUCKET : bucket Cloud Storage vers lequel exporter les métadonnées.

    Vous pouvez éventuellement inclure un préfixe personnalisé après le nom du bucket, au format gs://BUCKET/PREFIX/. La longueur maximale du préfixe personnalisé est de 128 caractères.

  • METADATA_SOURCE_PROJECT : projet dont vous souhaitez exporter les métadonnées. Indiquez un numéro ou un ID de projet. Le projet doit se trouver dans la même organisation et le même périmètre VPC Service Controls que le job de métadonnées.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

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

La réponse identifie une opération de longue durée. Les métadonnées exportées sont enregistrées dans un bucket Cloud Storage.

Exporter des métadonnées à partir de groupes d'entrées spécifiques

Pour exporter des métadonnées à partir de groupes d'entrées spécifiques, utilisez la méthode metadataJobs.create et fournissez une liste de groupes d'entrées.

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

  • JOB_PROJECT : projet Google Clouddans lequel vous exécutez le job de métadonnées. Indiquez un numéro ou un ID de projet.
  • LOCATION_ID : emplacement Google Cloud , par exemple us-central1.
  • METADATA_JOB_ID : Facultatif. ID du job de métadonnées.

  • BUCKET : bucket Cloud Storage vers lequel exporter les métadonnées.

    Vous pouvez éventuellement inclure un préfixe personnalisé après le nom du bucket, au format gs://BUCKET/PREFIX/. La longueur maximale du préfixe personnalisé est de 128 caractères.

  • ENTRY_GROUP : nom de ressource relatif d'un groupe d'entrées inclus dans le champ d'application du job, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Le groupe d'entrées doit se trouver dans le même projet que le job de métadonnées.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

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

La réponse identifie une opération de longue durée. Les métadonnées exportées sont enregistrées dans un bucket Cloud Storage.

Exporter des métadonnées à partir de types d'entrées ou d'aspects spécifiques

Pour exporter des métadonnées à partir de types d'entrées ou d'aspects spécifiques, définissez le champ d'application principal du job, par exemple au niveau de l'organisation, comme indiqué dans l'exemple suivant. Fournissez ensuite une liste de types d'entrées, de types d'aspects ou des deux.

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

  • ENTRY_TYPE : Facultatif. Nom de ressource relatif d'un type d'entrée inclus dans le champ d'application du job, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ASPECT_TYPE : Facultatif. Nom de ressource relatif d'un type d'aspect inclus dans le champ d'application du job, au format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
      "entry_types": [
        "ENTRY_TYPE",
        # Additional entry types
      ],
      "aspect_types": [
        "ASPECT_TYPE",
        # Additional aspect types
      ]
    },
  }
}

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

La réponse identifie une opération de longue durée. Les métadonnées exportées sont enregistrées dans un bucket Cloud Storage.

Obtenir des informations sur un job de métadonnées

Pour obtenir des informations sur un job de métadonnées, comme son état et le nombre d'entrées exportées, utilisez la méthode metadataJobs.get.

Résultats de l'exportation des métadonnées

La tâche d'exportation des métadonnées exporte un instantané de vos métadonnées Dataplex Universal Catalog au moment de la création de la tâche de métadonnées.

Exporter le contenu d'un fichier

Le contenu du fichier de sortie suit le même format que le fichier d'importation de métadonnées utilisé pour les tâches d'importation de métadonnées. Vous pouvez utiliser le fichier de sortie directement comme entrée pour un job d'importation de métadonnées.

Emplacement du fichier d'exportation

Dataplex Universal Catalog enregistre les fichiers de résultats d'exportation dans un bucket Cloud Storage en tant qu'objets.

Le chemin d'accès à l'objet pour chaque fichier de sortie est construit à l'aide du nom du bucket et du préfixe personnalisé que vous avez spécifiés dans le job d'exportation, suivis d'un chemin d'accès généré par le système. Le chemin généré par le système est conçu pour l'intégration à BigQuery. Le chemin d'objet utilise le format suivant :

gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl

Veuillez noter les points suivants :

  • Le chemin généré par le système commence par le format de partition Hive standard pour la date de création du job d'exportation. Ce format est compatible avec BigQuery. Pour en savoir plus, consultez la page Charger des données partitionnées externes.
  • Le paramètre consumer_project correspond au projet dans lequel vous exécutez le job d'exportation des métadonnées. Le paramètre project correspond au projet qui contient les métadonnées que vous exportez.
  • Vous pouvez réutiliser un ID de job de métadonnées si le job précédent a été supprimé. Toutefois, lorsque vous supprimez un job, les fichiers qu'il a exportés ne sont pas supprimés. Cela signifie que si vous réutilisez un ID de job supprimé, vous pouvez voir des ID de job en double dans les chemins d'accès aux fichiers de sortie.

  • Chaque fichier de sortie est nommé avec un numéro de fichier, qui est un entier commençant par 1.

    Si une tâche d'exportation de métadonnées contient un grand nombre d'entrées, elle divise les résultats en plusieurs fichiers pour limiter la taille de chaque fichier de sortie. Le nombre maximal d'entrées dans chaque fichier de sortie est de 1 000 000.

Exemples de fichiers de sortie

Voici des exemples de fichiers de sortie pour une tâche d'exportation de métadonnées incluant plusieurs projets :

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl

Voici des exemples de fichiers de sortie pour un job d'exportation de métadonnées contenant un grand groupe d'entrées. Les résultats du groupe d'entrées ont été répartis dans plusieurs fichiers.

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl

Analyser les métadonnées exportées dans BigQuery

Si vous souhaitez analyser les métadonnées exportées dans BigQuery, vous pouvez créer une table externe pour les métadonnées exportées. La création d'une table externe vous permet d'interroger les données exportées sans avoir à charger ni à transformer des données supplémentaires. Par exemple, vous pouvez compter le nombre d'entrées par groupe d'entrées, rechercher les entrées qui présentent des aspects spécifiques ou effectuer des analyses supplémentaires dans BigQuery.

Procédez comme suit :

  • Créez une table externe pour les données partitionnées avec Hive. Fournissez les informations suivantes :

    • Sélectionner un fichier à partir d'un bucket Cloud Storage : indiquez le chemin d'accès au dossier Cloud Storage contenant les fichiers de métadonnées exportés. Pour inclure tous les fichiers du bucket, utilisez le caractère générique astérisque (*). Exemple : gs://export-bucket/example-folder/*.
    • Format de fichier : sélectionnez JSONL (JSON délimité par un retour à la ligne).
    • Cochez la case Partitionnement des données source, puis, pour Sélectionner le préfixe d'URI source, indiquez le préfixe d'URI Cloud Storage pour la table BigQuery afin de définir les partitions. Exemple : gs://export-bucket/example-folder/.
    • Mode d'inférence de la partition : sélectionnez l'option Déduire automatiquement les types.
    • Type de table : sélectionnez l'option Table externe.

    • Schéma : cliquez sur le bouton Modifier sous forme de texte, puis saisissez la définition de schéma suivante pour les fichiers d'exportation :

      [
  {
    "name": "entry",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "name",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entryType",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "createTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "updateTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "aspects",
        "type": "JSON"
      },
      {
        "mode": "NULLABLE",
        "name": "parentEntry",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "fullyQualifiedName",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entrySource",
        "type": "RECORD",
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "resource",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "system",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "platform",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayName",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "description",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "labels",
            "type": "JSON"
          },
          {
            "mode": "REPEATED",
            "name": "ancestors",
            "type": "RECORD",
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "name",
                "type": "STRING"
              },
              {
                "mode": "NULLABLE",
                "name": "type",
                "type": "STRING"
              }
            ]
          },
          {
            "mode": "NULLABLE",
            "name": "createTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "updateTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "location",
            "type": "STRING"
          }
        ]
      }
    ]
  }
]

BigQuery crée une table externe contenant les métadonnées exportées. Le schéma de la table inclut une colonne de schéma entry, où chaque ligne représente une entrée. Pour en savoir plus sur les champs d'une entrée, consultez ImportItem. Le schéma de la table contient également les partitions du fichier d'exportation, comme décrit dans la section Emplacement du fichier d'exportation de ce document.

Après avoir créé la table externe, vous pouvez l'interroger à l'aide de la syntaxe GoogleSQL. Par exemple, pour interroger les types d'entrées exportés, utilisez l'instruction suivante :

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

Étapes suivantes