Résoudre les problèmes d'importation et d'exportation de glossaires

Ce document explique comment résoudre les problèmes et erreurs courants que vous pouvez rencontrer lorsque vous importez et exportez des glossaires et des liens d'entrée dans Knowledge Catalog (anciennement Dataplex Universal Catalog).

Si vous avez besoin d'aide pour résoudre un problème qui n'est pas abordé sur cette page, contactez l'assistance Google Cloud.

Liens d'entrée manquants dans la feuille de calcul Google Sheet exportée

Après avoir exporté des liens d'entrée de Knowledge Catalog vers une Google Sheet en exécutant l'utilitaire d'exportation de liens d'entrée, vous remarquez que certains liens d'entrée (associations) sont manquants dans la feuille de calcul Google Sheet générée.

Ce problème se produit si l'utilitaire d'exportation ignore automatiquement les liens d'entrée en raison des conditions suivantes :

  • Autorisations insuffisantes (ressources expurgées) : vous ne disposez pas des autorisations IAM requises pour afficher l'entrée source ou l'entrée cible associée au lien.

  • Type de lien d'entrée non valide : le lien d'entrée utilise un type de relation non compatible ou non reconnu. Les types valides sont limités à definition, related et synonym.

  • Références d'entrée incomplètes : les métadonnées d'entrée ne comportent pas les champs de schéma requis, ce qui entraîne l'ignorance de la ressource par la vérification de validation.

Pour résoudre ce problème, effectuez les vérifications suivantes :

  • Vérifiez les autorisations : assurez-vous que le compte principal qui exécute le script dispose des rôles requis.

  • Inspectez les journaux d'exécution : recherchez dans les journaux du terminal ou du script les avertissements contenant Skipping redacted entrylink. Les journaux affichent les ID de ressource spécifiques des liens d'entrée ignorés et la raison pour laquelle ils ont été omis.

  • Vérifiez la validité du schéma de lien : si vous avez modifié ces liens par programmation, vérifiez que leurs propriétés correspondent aux exigences du schéma.

Erreur "Aucun terme trouvé dans le glossaire"

Lorsque vous exportez des glossaires vers une feuille de calcul Google Sheets, l'exécution échoue ou renvoie un résultat vide avec le message No terms found in the glossary, même si le glossaire métier contient des termes actifs.

Ce problème se produit si le script ne parvient pas à localiser le glossaire spécifié ou ne dispose pas des autorisations d'accès requises pour récupérer son contenu. Les causes les plus courantes sont les suivantes :

  • URL de glossaire incorrecte : l'URL de glossaire configurée dans vos paramètres d'exécution est incorrecte ou comporte une faute de frappe.
  • Autorisations IAM insuffisantes : le compte de service authentifié ou les identifiants utilisateur qui exécutent le script ne sont pas autorisés à afficher ou à lister les termes dans le glossaire cible.
  • Incompatibilité des ID de glossaire : l'ID de glossaire spécifié dans la commande de votre script ne correspond pas à l'ID de ressource de glossaire réel dans Knowledge Catalog.

Pour résoudre ce problème, vérifiez votre configuration et vos autorisations :

  • Vérifiez l'ID du glossaire : dans la Google Cloud console, accédez à la page Glossaires de Knowledge Catalog, sélectionnez votre glossaire et vérifiez que l'ID de ressource correspond à l'ID que vous transmettez au script de l' utilitaire.

  • Vérifiez les autorisations IAM : assurez-vous que vos identifiants authentifiés (le compte de service ou votre compte utilisateur usurpé) disposent des rôles requis.

  • Validez la structure de l'URL du glossaire : si vous transmettez un chemin d'accès ou une URL de ressource directe au script, assurez-vous qu'il respecte le format de ressource Knowledge Catalog approprié :

    projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

Avertissement "Entrées introuvables dans Knowledge Catalog"

Lors d'une opération d'importation de liens d'entrée, le script s'interrompt et affiche un avertissement semblable à celui-ci :

Found X entries not found in Knowledge Catalog. EntryLinks associated with
these entries will be skipped. Continue with import? [y/N]:

Ce problème se produit si votre Google Sheet contient des liens d'entrée qui font référence à des actifs de données ou à des termes de glossaire qui n'existent pas dans Knowledge Catalog.

Pour résoudre ce problème, choisissez l'une des options suivantes :

  • Pour poursuivre une importation partielle, saisissez y à l'invite. L'utilitaire importe tous les liens d'entrée valides et ignore uniquement ceux qui font référence aux ressources manquantes.

  • Pour annuler et corriger les ressources manquantes, saisissez n pour annuler l'exécution. Vérifiez que les ID d'entrée de votre document source correspondent exactement aux noms de ressources de votre Knowledge Catalog. Corrigez les ressources manquantes ou les erreurs typographiques, puis exécutez à nouveau le script d'importation.

Échec ou interruption de la tâche d'importation en cours d'exécution

Si une tâche d'importation est interrompue ou échoue en cours d'exécution, vous n'avez pas besoin de redémarrer l'ensemble du processus ni de modifier votre feuille de calcul Google Sheet source.

L'utilitaire suit les lots importés avec succès à l'aide d'un dossier d'archive dans votre bucket de préproduction Cloud Storage.

Pour reprendre la tâche, procédez comme suit :

  1. Exécutez à nouveau l'utilitaire d'importation. L'utilitaire détecte l'état de votre exécution précédente et affiche l'invite suivante :

    Found X existing file(s) in archive folder from a previous incomplete import
Continue using existing files? [y/N]:

  2. Saisissez y. L'utilitaire ignore les lots qui ont déjà été importés et ne traite que les fichiers restants.

Délai d'attente du script ou erreurs SSL lors de l'exécution

Lors de l'exécution du script de l'utilitaire d'importation ou d'exportation, l'exécution s'arrête, expire ou renvoie des erreurs SSL dans votre terminal.

Ce problème se produit en raison des erreurs au niveau du réseau suivantes :

  • Interception par un proxy ou un pare-feu d'entreprise : un proxy de sécurité ou un pare-feu intercepte et inspecte le trafic HTTPS, ce qui invalide les certificats SSL.
  • Restrictions VPN actives : votre configuration VPN limite le trafic sortant à certaines Google Cloud API ou certains points de terminaison Google Sheets.
  • Instabilité du réseau local : une baisse temporaire de la connectivité Internet a interrompu la session.

Pour résoudre ces problèmes de réseau, procédez comme suit :

  • Assurez-vous que votre connexion réseau est stable.

  • Vérifiez les paramètres du proxy et du pare-feu.

  • Vérifiez votre configuration VPN.

  • Utilisez les nouvelles tentatives intégrées : le script de l'utilitaire dispose d'une logique de nouvelle tentative intégrée pour les problèmes de réseau temporaires. Si la baisse du réseau est momentanée, attendez que le script termine ses tentatives avant de redémarrer l'exécution.

Erreur "URL de feuille de calcul non valide"

Lorsque vous tentez d'exécuter un utilitaire d'importation ou d'exportation, l'interface de ligne de commande renvoie une erreur Invalid spreadsheet URL et arrête l'exécution.

Ce problème se produit si le script ne parvient pas à analyser le lien de la feuille de calcul Google Sheet fournie ou n'est pas autorisé à afficher le fichier. Les causes les plus courantes sont les suivantes :

  • URL mal formée : l'URL ne correspond pas au format de chemin d'accès standard de Google Sheets.
  • ID de feuille de calcul manquant : le chemin d'accès ne comporte pas l'ID alphanumérique unique qui pointe vers votre feuille de calcul spécifique.
  • Restrictions d'accès : votre compte de service authentifié n'est pas autorisé à afficher ni à modifier la feuille de calcul, ce qui empêche l'utilitaire de valider le lien.

Pour résoudre ce problème, vérifiez le lien de votre feuille de calcul et les paramètres d'accès :

  • Validez le préfixe de l'URL : assurez-vous que l'URL de la feuille de calcul que vous transmettez à l'utilitaire commence par le chemin d'accès standard suivant de Google Sheets : https://docs.google.com/spreadsheets/.

  • Vérifiez l'ID de la feuille de calcul : assurez-vous que l'URL inclut l'ID unique de votre feuille de calcul. Une URL valide doit suivre cette structure : https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

  • Vérifiez les autorisations d'accès : ouvrez la feuille de calcul Google Sheet dans un navigateur, cliquez sur Partager, et vérifiez que vous avez ajouté l'adresse e-mail de votre compte de service en tant que Éditeur.

Erreur "URL de glossaire non valide"

Lorsque vous tentez d'exécuter un utilitaire d'importation ou d'exportation pour les glossaires, l'interface de ligne de commande renvoie une erreur Invalid glossary URL et arrête l'exécution.

Ce problème se produit si le script ne parvient pas à analyser le chemin d'accès à la ressource de glossaire Knowledge Catalog fournie ou n'est pas autorisé à afficher la ressource. Les causes les plus courantes sont les suivantes :

  • Chemin d'accès à la ressource mal formé : le chemin d'accès à la ressource ne correspond pas au format de chemin d'accès standard du glossaire Knowledge Catalog.
  • ID incorrect : le chemin d'accès contient un ID de projet, un emplacement de région ou un ID de glossaire incorrect.
  • Restrictions d'accès ou ressource manquante : le glossaire n'existe pas ou votre compte de service authentifié ne dispose pas des autorisations IAM requises pour y accéder.

Pour résoudre ce problème, vérifiez le chemin d'accès à votre ressource de glossaire et vos identifiants :

  • Validez la structure du chemin d'accès à la ressource : assurez-vous que le chemin d'accès au glossaire que vous transmettez à l'utilitaire correspond au format standard suivant de Knowledge Catalog : projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID.

  • Vérifiez les identifiants dans le chemin d'accès : utilisez l'ID du projet, l'emplacement et l'ID de glossaire appropriés.

  • Vérifiez l'existence et l'accès à la ressource : assurez-vous que le glossaire existe avec l'ID spécifié et que votre compte de service authentifié dispose des rôles IAM nécessaires.

Afficher les journaux d'exécution

Les utilitaires d'importation et d'exportation génèrent des journaux d'exécution détaillés lors de leur exécution. Ces journaux vous aident à auditer le processus de transfert et à identifier les entrées ignorées ou les avertissements de mise en forme.

  • Emplacement des journaux : les utilitaires d'importation et d'exportation écrivent des fichiers journaux dans le répertoire logs/ de votre chemin d'exécution local.
  • Format des journaux : un horodatage est ajouté à chaque fichier journal afin que vous puissiez localiser les journaux d'une exécution spécifique.