Résoudre les problèmes d'importation de liens vers des entrées et le glossaire d'entreprise

Knowledge Catalog (anciennement Dataplex Universal Catalog) vous permet d'importer et d'exporter des glossaires d'entreprise et des liens d'entrée de manière groupée pour gérer votre vocabulaire d'entreprise à grande échelle. Lorsque vous exécutez les scripts d'utilitaire d'importation ou d'exportation, vous pouvez diagnostiquer et résoudre les problèmes courants tels que les liens d'entrée manquants, les exportations de glossaires vides, les URL de glossaire ou de feuille de calcul non valides, les jobs d'importation interrompus et les délais d'expiration du réseau de script. Pour en savoir plus, consultez À propos de l'importation et de l'exportation de glossaires et de liens d'entrée.

Si vous avez besoin d'aide pour résoudre un problème qui n'est pas abordé dans ce document, consultez Cloud Customer Care.

Corriger les liens d'entrée manquants dans Knowledge Catalog

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 masqué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 : il manque des champs de schéma obligatoires dans les métadonnées de l'entrée, ce qui entraîne l'omission de la ressource lors de la validation.

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

  • Vérifiez les autorisations : assurez-vous de disposer des autorisations nécessaires pour afficher les liens d'entrée manquants. Vérifiez que le compte principal exécutant le script dispose des rôles requis.

  • Inspectez les journaux d'exécution : vérifiez si les journaux du terminal ou du script contiennent des avertissements incluant Skipping redacted entrylink. Les journaux affichent les ID de ressources 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 des liens : si vous avez déjà modifié ces liens de manière programmatique, 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 d'entreprise contient des termes actifs.

Ce problème se produit si le script ne parvient pas à localiser le glossaire spécifié ou s'il 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 mal orthographiée.
  • Autorisations IAM insuffisantes : le compte de service authentifié ou les identifiants utilisateur exécutant le script ne sont pas autorisés à afficher ou à lister les termes du glossaire cible.
  • ID de glossaire non concordant : l'ID de glossaire spécifié dans votre commande de 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 console Google Cloud , accédez à la page Glossaires du Knowledge Catalog, sélectionnez votre glossaire et vérifiez que l'ID de ressource correspond à l'ID que vous transmettez au script utilitaire.

  • Vérifiez les autorisations IAM : vérifiez que vos identifiants authentifiés (le compte de service ou votre compte utilisateur emprunté) ont bien reçu les 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 éléments 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 procéder à une importation partielle, saisissez y lorsque vous y êtes invité. L'utilitaire importe tous les liens d'entrée valides et ignore uniquement les liens 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 catalogue de connaissances. Corrigez les ressources manquantes ou les erreurs typographiques, puis exécutez à nouveau le script d'importation.

Résoudre les échecs des jobs d'importation Knowledge Catalog

Si un job d'importation est interrompu ou échoue en cours d'exécution, vous n'avez pas besoin de redémarrer l'ensemble du processus ni de modifier votre 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 le job, procédez comme suit :

  1. Réexécutez 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. Tapez y. L'utilitaire ignore les lots qui ont déjà été importés et ne traite que les fichiers restants.

Délais d'expiration des scripts 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 est dû aux erreurs suivantes au niveau du réseau :

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

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

  • Assurez-vous de disposer d'une connexion réseau stable.

  • Inspecter les paramètres de proxy et de pare-feu

  • Vérifiez votre configuration VPN.

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

Erreur d'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 interrompt l'exécution.

Ce problème se produit si le script ne peut pas analyser le lien Google Sheet fourni ou s'il n'est pas autorisé à afficher le fichier. Les causes les plus courantes sont les suivantes :

  • URL incorrecte : l'URL ne correspond pas au format de chemin d'accès standard de Google Sheets.
  • ID de feuille de calcul manquant : l'ID alphanumérique unique qui pointe vers votre feuille de calcul spécifique est manquant dans le chemin d'accès.
  • 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 vers 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 : vérifiez que l'URL inclut l'ID unique de votre feuille. Une URL valide doit respecter la structure suivante : 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 qu'éditeur.

Corriger les erreurs d'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 interrompt l'exécution. Vérifiez qu'il n'y a pas d'URL de glossaire non valide dans vos paramètres.

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

  • Chemin d'accès à la ressource incorrect : le chemin d'accès à la ressource ne correspond pas au format standard du chemin d'accès au 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 à la 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 Knowledge Catalog standard suivant : 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 corrects.

  • Confirmez l'existence de la ressource et l'accès à celle-ci : vérifiez 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 au fur et à mesure de leur exécution. Si votre job d'importation échoue, consultez les journaux pour identifier les erreurs spécifiques. 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 les fichiers journaux dans le répertoire logs/ de votre chemin d'exécution local.
  • Format de journal : chaque fichier journal est accompagné d'un code temporel qui vous permet de localiser les journaux d'une exécution spécifique.