Importer des glossaires d'entreprise et des liens d'entrée à l'aide de fichiers JSON

Knowledge Catalog (anciennement Dataplex Universal Catalog) vous permet d'importer de manière groupée des glossaires, des catégories, des termes et des liens d'entrée à l'aide de l'API Dataplex. Vous pouvez utiliser ce processus pour migrer des métadonnées à partir d'autres outils de catalogage ou mettre à jour de manière groupée vos glossaires existants.

Avant de commencer

Avant de commencer le processus d'importation, assurez-vous de remplir les conditions préalables suivantes :

Créer un bucket Cloud Storage

Créez un bucket Cloud Storage qui servira de zone de préproduction dans laquelle vous importerez des fichiers JSON.

Rôles requis

Pour obtenir les autorisations nécessaires pour importer des glossaires et des liens d'entrée à l'aide de fichiers JSON, 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.

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

Activer les API

Pour importer des glossaires et des liens d'entrée, activez l'API Dataplex dans votre projet.

Rôles requis pour activer les API

Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Termes du glossaire et entrées physiques

La structure de votre catalogue est basée sur les composants suivants :

  • Termes du glossaire : concepts d'entreprise, tels que le chiffre d'affaires annuel, organisés en glossaires et catégories.
  • Entrées : éléments de données physiques, tels qu'une table ou une colonne BigQuery.

Les jobs d'importation de glossaires créent des catégories et des termes de glossaire, et écrasent ceux qui existent déjà. Les jobs d'importation de liens d'entrée créent des liens entre des termes du glossaire (par exemple, des synonymes ou des termes associés) ou entre des termes du glossaire et des entrées physiques (par exemple, entre un terme et un élément de données physique). Pour en savoir plus sur la structuration de votre catalogue, consultez la page Gérer un glossaire d'entreprise.

Comportement de l'importation groupée

Les importations de glossaires d'entreprise et de liens d'entrée sont des processus distincts et ont des quotas par défaut différents. Pour en savoir plus, consultez la page Quotas et limites.

Les jobs d'importation groupée de glossaires utilisent "entry_sync_mode": "FULL" et fonctionnent en mode d'écrasement complet. Lorsque vous exécutez un job d'importation pour un glossaire existant, Knowledge Catalog supprime toutes les catégories et tous les termes existants, puis les recrée à partir des fichiers JSON que vous avez importés. La recréation de termes de glossaire leur attribue de nouveaux identifiants uniques et supprime tous les liens d'entrée existants associés à ces termes, tels que les liens vers des colonnes BigQuery. Pour restaurer ces relations, vous devez réimporter vos liens d'entrée une fois le job d'importation du glossaire terminé. Les importations de liens d'entrée ne créent que de nouveaux liens d'entrée, sans écraser ni supprimer les liens existants.

Importer des glossaires à l'aide de fichiers JSON

Pour importer des glossaires, des catégories et des termes en important des fichiers JSON dans Cloud Storage, procédez comme suit.

Créer un glossaire cible

Créez un glossaire cible pour importer des métadonnées.

alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

gcurl -X POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/glossaries?glossary_id=GLOSSARY_ID -d "$(cat<<EOF

{
   "displayName": "DISPLAY_NAME",
   "description": "DESCRIPTION"
}
EOF
)"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet dans lequel vous créez le glossaire
  • LOCATION_ID : emplacement dans lequel vous souhaitez créer le glossaire.
  • GLOSSARY_ID : ID du glossaire
  • DISPLAY_NAME : nom à afficher du glossaire
  • DESCRIPTION : description du glossaire

Préparer les fichiers JSON

Créez un fichier JSON délimité par un retour à la ligne avec le glossaire, les catégories et les termes que vous souhaitez importer dans le bucket Cloud Storage.

Utilisez le schéma JSON suivant pour structurer vos fichiers d'importation :

   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-category","aspects":{"dataplex-types.global.glossary-category-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","displayName":"CATEGORY_NAME","description":"CATEGORY_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"}]}}}
   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM1_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-term","aspects":{"dataplex-types.global.glossary-term-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"TERM1_CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM1_ID","displayName":"TERM1_DISPLAY_NAME","description":"TERM1_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"},{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary-category"}]}}}
   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM2_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-term","aspects":{"dataplex-types.global.glossary-term-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"TERM1_CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM2_ID","displayName":"TERM2_DISPLAY_NAME","description":"TERM2_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"},{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary-category"}]}}}

Importer un glossaire, des catégories et des termes

Importez le glossaire, les catégories et les termes dans le bucket Cloud Storage :

# Set GCURL alias
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
{
   "type":"IMPORT",
   "import_spec":{
      "log_level":"DEBUG",
      "source_storage_uri":"gs://STORAGE_BUCKET/",
      "entry_sync_mode":"FULL",
      "aspect_sync_mode":"INCREMENTAL",
      "scope":{
         "glossaries": "GLOSSARY_NAME"
      }
   }
}
EOF
)"

Remplacez DATAPLEX_API par le point de terminaison de l'API Dataplex au format dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Pour importer de manière groupée des liens d'entrée en important des fichiers JSON dans Cloud Storage, procédez comme suit.

Créez un fichier JSON délimité par un retour à la ligne avec les liens d'entrée que vous souhaitez importer dans le bucket Cloud Storage.

Utilisez le schéma JSON suivant pour structurer vos fichiers d'importation :

Exemple de format pour les liens entre les termes

   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-0606e3f2-8206-4f3a-aba9-32c6196f6048","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/synonym","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-2"}]}}
   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-2f7408e3-af3d-405d-81bb-861cf9ec5146","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/related","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-2"}]}}

Exemple de format pour les liens entre les termes et les éléments de données

   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-0606e3f2-8206-4f3a-aba9-32c6196f6048","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/definition","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/us-central1/entryGroups/entry-group-1/entries/entry-1"}]}}

Pour lancer un job d'importation de métadonnées qui établit des connexions synonym ou related entre vos termes de catalogue, utilisez la commande suivante :

gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
   {
      "type":"IMPORT",
      "import_spec":{
         "log_level":"DEBUG",
         "source_storage_uri":"gs://STORAGE_BUCKET/",
         "entry_sync_mode":"FULL",
         "aspect_sync_mode":"INCREMENTAL",
         "scope":{
            "entry_groups":[  "projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex"
            ],
            "entry_link_types":[
               "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
               "projects/dataplex-types/locations/global/entryLinkTypes/related"
            ],
            "referenced_entry_scopes":[
               "PROJECT_IDS"
            ]
         }
      }
   }
EOF
)"

Remplacez DATAPLEX_API par dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Pour créer un lien entre les termes du glossaire et les éléments de données, exécutez le job d'importation pour chaque groupe d'entrées auquel appartient l'entrée de l'élément de données. Tous les liens d'entrée de définition sont créés dans ce groupe d'entrées.

   gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
   {
   "type":"IMPORT",
   "import_spec":{
      "log_level":"DEBUG",
      "source_storage_uri":"gs://STORAGE_BUCKET/",
      "entry_sync_mode":"FULL",
      "aspect_sync_mode":"INCREMENTAL",
      "scope":{
         "entry_groups":[  "projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/@dataplex"
         ],
         "entry_link_types":[
            "projects/dataplex-types/locations/global/entryLinkTypes/definition"
         ],
         "referenced_entry_scopes":[
            "PROJECT_IDS"
         ]
      }
   }
   }
EOF
)"

Remplacez DATAPLEX_API par dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Surveiller l'état du job d'importation

  1. Pour obtenir l'état de l'opération import, exécutez la commande suivante :

    gcurl https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/operations/operation-OPERATION_ID

    Remplacez OPERATION_ID par l'ID de l'opération.

  2. Pour obtenir l'état du job de métadonnées, exécutez la commande suivante :

    gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataJobs/JOB_ID

Étapes suivantes