Gérer les métadonnées des lacs, des zones et des composants

Ce guide décrit les métadonnées Knowledge Catalog (anciennement Dataplex Universal Catalog) pour les lacs, les zones et les éléments, et explique comment utiliser l'API Dataplex pour les gérer.

Attention : L'ingestion des entités Knowledge Catalog sous les lacs et les zones dans Data Catalog (y compris celles créées en tant que résultat de la découverte Knowledge Catalog) est obsolète et cessera de fonctionner d'ici le 30 septembre 2025. Les tables externes de BigQuery publiées par Discovery seront ingérées dans Knowledge Catalog en tant qu'entrées.

Présentation

Knowledge Catalog analyse les éléments suivants :

• Les éléments de données structurées et semi-structurées dans les lacs de données, afin d'extraire les métadonnées de table dans des entités de table
• Les données non structurées, telles que les images et les textes, afin d'extraire les métadonnées d'ensemble de fichiers dans des entités d'ensemble de fichiers

Vous pouvez utiliser l'API Dataplex Metadata pour effectuer les opérations suivantes :

• Afficher, modifier et supprimer les métadonnées d'entité de table et d'ensemble de fichiers
• Créer vos propres métadonnées d'entité de table ou d'ensemble de fichiers

Vous pouvez analyser les métadonnées Knowledge Catalog à l'aide des éléments suivants :

• Data Catalog (obsolète) pour la recherche et le tagging
• Dataproc Metastore et BigQuery pour l'interrogation des métadonnées de table et le traitement analytique

API Dataplex

Cette section récapitule les ressources de lac, de zone et d'élément de l'API Dataplex, ainsi que les ressources clés associées.

API du plan de contrôle

L'API du plan de contrôle Dataplex permet de créer et de gérer les ressources de lac, de zone et d'élément.

• Lac: instance de service Knowledge Catalog qui permet de gérer les ressources de stockage entre les projets d'une organisation.

• Zone : regroupement logique d'éléments dans un lac. Utilisez plusieurs zones dans un lac pour organiser les données en fonction de leur état de préparation, de leur charge de travail ou de la structure de l'organisation.

• Éléments : ressources de stockage, avec des données stockées dans des buckets Cloud Storage ou des ensembles de données BigQuery, qui sont associés à une zone dans un lac.

API Metadata

Utilisez l'API Dataplex Metadata pour créer et gérer des métadonnées dans des entités de table et d'ensemble de fichiers, ainsi que dans des partitions. Knowledge Catalog analyse les éléments de données, dans un lac ou fournis par vous, pour créer des entités et des partitions. Les entités et les partitions conservent des références aux éléments associés et aux emplacements de stockage physiques.

Concepts clés

Entité de table :

Métadonnées pour les données structurées avec des schémas bien définis. Les entités de table sont identifiées de manière unique par un ID d'entité et un emplacement de données. Les métadonnées d'entité de table peuvent être interrogées dans BigQuery et Dataproc Metastore :

• Objets Cloud Storage : métadonnées pour les objets Cloud Storage, auxquels vous accédez via les API Cloud Storage.
• Tables BigQuery : métadonnées pour les tables BigQuery, auxquelles vous accédez via les API BigQuery.

Entité d'ensemble de fichiers :

Métadonnées sur les données non structurées, généralement sans schéma. Les ensembles de fichiers sont identifiés de manière unique par un ID d'entité et un emplacement de données. Chaque ensemble de fichiers a un format de données.

Partitions :

Métadonnées pour un sous-ensemble de données dans une entité de table ou d'ensemble de fichiers, identifiées par un ensemble de paires clé-valeur et un emplacement de données.

Essayer l'API

Consultez les pages de documentation de référence de l'API Knowledge Catalog lakes.zones.entities et lakes.zones.partitions pour afficher les paramètres et les champs associés à chaque API. Utilisez le panneau Try this API (Essayer cette API) qui accompagne la documentation de référence de chaque méthode d'API pour effectuer des requêtes API à l'aide de différents paramètres et champs. Vous pouvez créer, afficher et envoyer vos requêtes sans avoir à générer d'identifiants, puis afficher les réponses renvoyées par le service.

Les sections suivantes fournissent des informations pour vous aider à comprendre et à utiliser les API Knowledge Catalog Metadata.

Entités

Lister les entités

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.entities.list.

Pour limiter la liste des entités renvoyées par le service, ajoutez filter paramètres de requête à l'URL de requête list entities.

Obtenir l'entité

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.entities.get.

Par défaut, la réponse Get Entity contient des métadonnées d'entité de base. Pour récupérer des métadonnées de schéma supplémentaires, ajoutez le view paramètre de requête à l'URL de requête.

Informations sur la compatibilité : bien que les métadonnées Knowledge Catalog soient enregistrées de manière centralisée dans l'API Metadata, seules les métadonnées de table d'entité compatibles avec BigQuery et Apache Hive Metastore sont publiées dans BigQuery et Dataproc Metastore. L'API Get Entity renvoie un CompatibilityStatus message, qui indique si les métadonnées de table sont compatibles avec BigQuery et Hive Metastore, et si ce n'est pas le cas, la raison de l'incompatibilité.

Mettre à jour l'entité

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.entities.update.

Utilisez cette API pour modifier les métadonnées d'entité, y compris si vous ou Knowledge Catalog gérez les métadonnées d'entité.

• Cette API remplace entièrement tous les champs d'entité mutables Entity. Les champs d'entité suivants sont immuables. Si vous les spécifiez dans une requête de mise à jour, ils seront ignorés :
  • asset
  • dataPath
  • type
  • system
• Spécifiez une valeur pour tous les champs d'entité mutables, y compris tous les champs de schéma, même si les valeurs ne sont pas modifiées.
• Fournissez le champ etag. Vous pouvez obtenir l'etag en envoyant d'abord une entities.get, qui renvoie le etag de l'entité dans la réponse.
• Mise à jour des champs de schéma : vous pouvez mettre à jour le schéma de table découvert par Knowledge Catalog pour améliorer sa précision.
  Les champs de schéma sont listés dans l'onglet "Discover" (Découvrir) de l' interface Web Knowledge Catalog dans la Google Cloud console.
  • Si le schéma est un ensemble de fichiers, laissez tous les champs de schéma vides.
  • Pour définir un champ répété, définissez le mode sur REPEATED. Pour définir un champ de structure, définissez le type sur RECORD.
  • Vous pouvez définir le userManaged champ du schéma pour spécifier si vous ou Knowledge Catalog gérez les métadonnées de table. Le paramètre par défaut est "géré par Knowledge Catalog" . Si userManaged est défini sur "true", ce paramètre est inclus dans les informations renvoyées par une requête entities.get si EntityView est défini sur SCHEMA ou FULL.
• Mise à jour des champs de partition :
  • Pour les données partitionnées de style non Hive, la découverte Knowledge Catalog génère automatiquement des clés de partition. Par exemple, pour le chemin d'accès aux données gs://root/2020/12/31, les clés de partition p0, p1 et p2 sont générées. Pour rendre les requêtes plus intuitives, vous pouvez remplacer p0, p1, et p2 par year, month, et day, respectivement.
  • Si vous remplacez le style de partition par le style HIVE, le champ de partition est immuable.
• Mise à jour d'autres champs de métadonnées : vous pouvez mettre à jour les champs mimeType, CompressionFormat, CsvOptions et JsonOptions générés automatiquement pour faciliter la découverte Knowledge Catalog. La découverte Knowledge Catalog utilisera de nouvelles valeurs lors de sa prochaine exécution.

Créer une entité

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.entities.create.

Utilisez l'API entities.create pour créer des entités de métadonnées de table ou d'ensemble de fichiers. Renseignez les champs obligatoires et les champs facultatifs pertinents, ou laissez le service de découverte Knowledge Catalog remplir les champs facultatifs.

Supprimer l'entité

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.entities.delete.

• Fournissez le champ etag. Vous pouvez obtenir l'etag en envoyant d'abord une entities.get, qui renvoie le etag de l'entité dans la réponse.

Si les données sous-jacentes d'une table ou d'un ensemble de fichiers dans une zone brute sont supprimées, les métadonnées de la table ou de l'ensemble de fichiers sont automatiquement supprimées lors de la prochaine analyse de découverte. Si les données sous-jacentes d'une table dans une zone organisée sont supprimées, les métadonnées de la table ne sont pas supprimées en conséquence, mais une action de données manquantes est signalée. Pour résoudre ce problème, supprimez explicitement l'entité de métadonnées de table via l'API Metadata.

Remarque : Lorsque les données sous-jacentes existent toujours, le choix de la fonction delete tables (supprimer les tables) ne supprime que temporairement l’entité de métadonnées. L'entité sera régénérée lors de la prochaine exécution de la découverte.

Partitions

Lister les partitions

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.partitions.list.

Pour limiter la liste des partitions renvoyées par le service, ajoutez filtre paramètres de requête à l'URL de requête list partitions.

Exemples :

• ?filter="Country=US AND State=CA AND City=Sunnyvale"
• ?filter="year < 2000 AND month > 12 AND Date > 10"

Obtenir la partition

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.partitions.get.

Pour obtenir une partition, vous devez compléter l'URL de requête en ajoutant les valeurs de clé de partition à la fin de l'URL, au format partitions/value1/value2/…./value10.

Exemple : si une partition comporte les valeurs {Country=US, State=CA, City=Sunnyvale}, l'URL de requête get doit se terminer par /partitions/US/CA/Sunnyvale.

Important : Les valeurs d'URL ajoutées doivent être doublement encodées. Par exemple, url_encode(url_encode(value)) peut être utilisé pour encoder "US:CA/CA#Sunnyvale" afin que l'URL de requête se termine par /partitions/US%253ACA/CA%2523Sunnyvale. Le champ name de la réponse conserve le format encodé.

Créer une partition

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.partitions.create.

Pour créer une partition personnalisée pour votre source de données, utilisez l'API partitions.create. Spécifiez le champ de localisation obligatoire avec un chemin d'accès Cloud Storage.

Vous pouvez fournir jusqu'à 20 clés de partition, mais seules les 10 premières clés peuvent être utilisées pour le filtrage.

Supprimer une partition

Pour obtenir des informations complètes sur l'API, consultez la documentation lakes.zones.partitions.delete.

Complétez l'URL de requête en ajoutant les valeurs de clé de partition à la fin de l'URL de requête, au format partitions/value1/value2/…./value10.

Exemple : si une partition comporte les valeurs {Country=US, State=CA, City=Sunnyvale}, l'URL de requête doit se terminer par /partitions/US/CA/Sunnyvale.

Important : Les valeurs d'URL ajoutées doivent être conformes à la norme RFC-1034 ou être doublement encodées, par exemple, US:/CA#/Sunnyvalesous la forme US%3A/CA%3A/Sunnyvale.

Étape suivante

• Découvrez comment accéder aux métadonnées dans Apache Spark.