Ce guide vous aide à résoudre les problèmes liés au Knowledge Catalog lorsque vous importez et exportez des glossaires et des liens vers des entrées, y compris les liens vers des entrées manquants, les erreurs d'URL de glossaire non valides ou lorsqu'un job d'importation échoue.
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.
Corriger les liens d'entrées manquants dans Knowledge Catalog
Après avoir exporté des liens d'entrée du Knowledge Catalog vers une Google Sheet en exécutant l'utilitaire d'exportation des liens d'entrée, vous constatez 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ées 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,relatedetsynonym.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 fait que le contrôle de validation ignore la ressource.
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 vers les entrées manquantes. Vérifiez que le compte principal exécutant le script dispose des rôles requis.
Inspectez les journaux d'exécution : vérifiez si le terminal ou les journaux de script contiennent des avertissements avec
Skipping redacted entrylink. Les journaux indiquent 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 de 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 ne dispose pas des autorisations d'accès requises pour récupérer son contenu. Les causes les plus courantes sont les suivantes :
- URL du glossaire incorrecte : l'URL du 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.
- Incompatibilité d'ID de glossaire : L'ID du glossaire spécifié dans la commande de script ne correspond pas à l'ID de ressource du glossaire dans le 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 à celui que vous transmettez au script utilitaire.
Vérifiez les autorisations IAM : assurez-vous que vos identifiants authentifiés (le compte de service ou votre compte utilisateur emprunté) 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 correct :
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 vers des entrées qui font référence à des assets 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 effectuer 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 l'exécution et corriger les ressources manquantes, saisissez
n. 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 fautes de frappe, puis exécutez à nouveau le script d'importation.
Résoudre les problèmes liés aux tâches d'importation Knowledge Catalog ayant échoué
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 Cloud Storage intermédiaire.
Pour reprendre le job, procédez comme suit :
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]:Tapez
y. L'utilitaire ignore les lots qui ont déjà été importés et ne traite que les fichiers restants.
Délai avant expiration 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 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 certains points de terminaison d'API Google Cloud ou Google Sheets.
- Instabilité du réseau local : une perte 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 la configuration de votre 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 déconnexion 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 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 s'il 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 contient 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 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 Google Sheets standard suivant :
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. Une URL valide doit respecter la structure suivante :
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/editVérifiez les autorisations d'accès : ouvrez la feuille de calcul Google Sheet dans un navigateur, cliquez sur Partager, puis vérifiez que vous avez ajouté l'adresse e-mail de votre compte de service en tant qu'éditeur.
Résoudre les erreurs d'URL de glossaire non valides
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. Vérifiez qu'aucun paramètre ne contient d'URL de glossaire non valide.
Ce problème se produit si le script ne parvient pas à analyser le chemin d'accès à la ressource du 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 mal formé : le chemin d'accès à la ressource ne correspond pas au format standard du chemin d'accès au glossaire du Knowledge Catalog.
- ID incorrect : le chemin d'accès contient un ID de projet, une 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 et les identifiants de votre ressource de glossaire :
Validez la structure du chemin d'accès aux ressources : assurez-vous que le chemin d'accès au glossaire que vous transmettez à l'utilitaire correspond au format standard suivant du Knowledge Catalog :
projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_IDVérifiez les identifiants dans le chemin d'accès : utilisez l'ID de projet, l'emplacement et l'ID de glossaire corrects.
Vérifiez l'existence et l'accès aux ressources : assurez-vous que le glossaire existe avec l'ID spécifié et que les rôles IAM nécessaires ont été accordés à votre compte de service authentifié.
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. 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 du journal : un code temporel est ajouté à chaque fichier journal pour vous permettre de localiser les journaux d'une exécution spécifique.