Passer au glossaire d'entreprise dans Knowledge Catalog

Ce document fournit des instructions pour migrer en une seule étape de la version preview du glossaire d'entreprise, qui prenait en charge les métadonnées Data Catalog, vers la version en disponibilité générale du glossaire d'entreprise dans Knowledge Catalog (anciennement Dataplex Universal Catalog). La migration vers la version en disponibilité générale vous permet d'utiliser les fonctionnalités améliorées et une intégration plus poussée avec les métadonnées Knowledge Catalog, offrant une meilleure stabilité, de nouvelles fonctionnalités et une assistance complète en production. Ce processus met automatiquement à jour vos glossaires pour qu'ils soient compatibles avec les métadonnées Knowledge Catalog.

Remarque : Si vous avez déjà commencé le processus de migration à l'aide du processus manuel de migration de vos glossaires et que vous souhaitez accéder à ces instructions, consultez la page Passer manuellement au glossaire d'entreprise dans Knowledge Catalog.

Avant de commencer

1. Installez gcloud ou des packages Python. Authentifiez votre compte utilisateur et les identifiants par défaut de l'application (ADC) utilisés par les bibliothèques Python. Exécutez les commandes suivantes et suivez les invites basées sur le navigateur :

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. Activez les API suivantes :

   • API Dataplex
   • API Data Catalog
   • API Cloud Resource Manager
   • API Cloud Storage

3. Créez un ou plusieurs buckets Cloud Storage dans l'un de vos projets. Les buckets serviront d'emplacement temporaire pour les fichiers d'importation. Plus vous fournissez de buckets, plus l'importation est rapide. Attribuez le rôle IAM d'administrateur de l'espace de stockage au compte de service qui exécute la migration :

   [e-mail]

   Remplacez MIGRATION_PROJECT_ID par le projet à partir duquel vous migrez les glossaires.

4. Configurez le dépôt :

   1. Clonez le dépôt :

      git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
      cd dataplex-labs/dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import
      

   2. Installez les packages requis :

      pip3 install -r requirements.txt
      cd migration
      

      Remarque : Si vous rencontrez des problèmes lors de l’installation du package, suivez les étapes pour créer un environnement virtuel Python.

Rôles requis

Pour obtenir les autorisations nécessaires pour migrer des glossaires de Data Catalog vers Knowledge Catalog, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Propriétaire du glossaire Data Catalog (roles/datacatalog.glossaryOwner) sur votre projet
• Administrateur Dataplex (roles/dataplex.admin) sur votre projet

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 migrer des glossaires de Data Catalog vers Knowledge Catalog. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour migrer des glossaires de Data Catalog vers Knowledge Catalog :

• datacatalog.glossaries.get sur le projet à partir duquel vous migrez les glossaires
• datacatalog.glossaries.list sur le projet à partir duquel vous migrez les glossaires
• dataplex.glossaries.create sur le projet dans lequel les glossaires sont créés dans Knowledge Catalog
• dataplex.glossaries.update sur le projet dans lequel les glossaires seront mis à jour dans Knowledge Catalog

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

Pour en savoir plus sur Identity and Access Management (IAM) dans Knowledge Catalog, consultez Gérer les accès avec IAM.

Exécuter le script de migration

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2

Remplacez les éléments suivants :

• USER_PROJECT_ID: ID du projet à migrer.

  MIGRATION_PROJECT_ID fait référence au projet source contenant les glossaires Data Catalog que vous souhaitez exporter. USER_PROJECT_ID est le projet utilisé pour la facturation et l'attribution de quotas pour les appels d'API générés par le script.

• BUCKET1 et BUCKET2 : ID des bucket Cloud Storage à utiliser pour l'importation.

  Vous pouvez fournir un ou plusieurs buckets. Pour les arguments de bucket, fournissez une liste de noms de buckets séparés par une virgule, sans espace (par exemple, --buckets=bucket-one,bucket-two). Un mappage un-à-un entre les buckets et les glossaires n'est pas obligatoire. Le script exécute les tâches d'importation en parallèle, ce qui accélère la migration.

Si des problèmes d'autorisation empêchent le script de découvrir automatiquement les ID de votre organisation, utilisez l'indicateur --orgIds pour spécifier les organisations que le script peut utiliser pour rechercher des éléments de données liés aux termes du glossaire.

Remarque : Ne modifiez pas les fichiers JSON exportés. Le script génère des fichiers au format requis par l'API d'importation Dataplex. La modification du format peut entraîner l'échec des tâches d'importation.

Définir le champ d'application des glossaires lors de la migration

Pour migrer uniquement des glossaires spécifiques, définissez leur champ d'application en fournissant leurs URL respectives.

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

Remplacez GLOSSARY_URL1 (et GLOSSARY_URL2) par les URL des glossaires que vous migrez. Vous pouvez fournir une ou plusieurs URL de glossaire.

Lorsque la migration s'exécute, le nombre de tâches d'importation peut être inférieur au nombre de glossaires exportés. Cela se produit lorsque des glossaires vides qui ne nécessitent pas de tâche d'importation en arrière-plan sont créés directement.

Reprendre la migration en cas d'échec de la tâche d'importation

La présence de fichiers après la migration indique que certaines tâches d'importation ont échoué. Pour reprendre la migration, exécutez la commande suivante :

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

Si vous rencontrez des échecs, exécutez à nouveau la commande resume. Le script ne traite que les fichiers qui n'ont pas été importés et supprimés.

Le script applique des vérifications de dépendances pour les liens d'entrée et les liens inter-glossaires. Un fichier de lien d'entrée n'est importé que si son glossaire parent a été importé. De même, un lien entre des termes n'est importé que si tous les termes référencés ont été importés.

Remarque : Des ID aléatoires peuvent être ajoutés aux noms de glossaires, de liens d'entrée et de tâches dans les journaux ou les fichiers générés. Ces ID sont destinés à l'unicité interne du backend et n'affectent pas les noms ni la structure de vos glossaires migrés finaux.

Résoudre les problèmes

Cette section fournit des solutions aux erreurs courantes.

• Autorisation refusée / Erreur 403 : assurez-vous que l'utilisateur ou le compte de service dispose du rôle d'éditeur Dataplex sur le projet de destination et du rôle de lecteur Dataplex sur le projet source.

• ModuleNotFoundError : assurez-vous d'avoir activé votre environnement virtuel Python et installé les packages requis à l'aide de pip3 install -r requirements.txt.

• TimeoutError / ssl.SSLError : ces erreurs au niveau du réseau peuvent être causées par des pare-feu, des proxys ou des connexions lentes. Le script dispose d'un délai d'attente de cinq minutes. Si les problèmes persistent, vous devrez peut-être vérifier la configuration de votre réseau local.

• Méthode introuvable (Impossible de récupérer les entrées) : cette erreur indique souvent que votre projet utilisateur n'est pas autorisé à appeler l'API, ce qui empêche la récupération des entrées nécessaires.