Soluciona problemas relacionados con la importación del glosario empresarial y los vínculos de entrada

En esta guía, se te ayudará a solucionar problemas de Knowledge Catalog cuando importes y exportes glosarios y vínculos de entradas, incluidos los vínculos de entradas faltantes, los errores de URL de glosario no válidos o cuando falla un trabajo de importación.

Si necesitas ayuda para resolver un problema que no se aborda en esta página, comunícate con Asistencia de Google Cloud.

Corrige los vínculos de entradas faltantes en Knowledge Catalog

Después de exportar vínculos de entradas de Knowledge Catalog a una Hoja de cálculo de Google mediante la ejecución de la utilidad de exportación de vínculos de entradas, observas que faltan algunos vínculos de entradas (asociaciones) en la Hoja de cálculo de Google generada.

Este problema se produce si la utilidad de exportación omite automáticamente los vínculos de entradas debido a las siguientes condiciones:

  • Permisos insuficientes (recursos redactados): No tienes los permisos de IAM necesarios para ver la entrada de origen ni la de destino asociada al vínculo.

  • Tipo de vínculo de entrada no válido: El vínculo de entrada usa un tipo de relación no admitido o no reconocido. Los tipos válidos se limitan a definition, related y synonym.

  • Referencias de entradas incompletas: Faltan los campos de esquema obligatorios en los metadatos de la entrada, lo que hace que la verificación de validación omita el recurso.

Para resolver este problema, realiza las siguientes verificaciones:

  • Verifica los permisos: Asegúrate de tener los permisos para ver los vínculos de entradas faltantes. Confirma que se hayan otorgado los roles necesarios al principal que ejecuta la secuencia de comandos.

  • Inspecciona los registros de ejecución: Revisa la terminal o los registros de la secuencia de comandos para ver las advertencias que contienen Skipping redacted entrylink. Los registros generan los IDs de recursos específicos de los vínculos de entradas omitidos y el motivo por el que se omitieron.

  • Verifica la validez del esquema de vínculos: Si modificaste estos vínculos de forma programática, verifica que sus propiedades coincidan con los requisitos del esquema.

Error No terms found in the glossary

Cuando exportas glosarios a una Hoja de cálculo de Google, la ejecución falla o muestra un resultado vacío con el mensaje No terms found in the glossary, aunque el glosario empresarial contenga términos activos.

Este problema se produce si la secuencia de comandos no puede ubicar el glosario especificado o no tiene los permisos de acceso necesarios para recuperar su contenido. Entre las causas comunes, se incluyen las siguientes:

  • URL de glosario incorrecta: La URL del glosario configurada en los parámetros de ejecución es incorrecta o tiene errores ortográficos.
  • Permisos de IAM insuficientes: La cuenta de servicio autenticada o las credenciales de usuario que ejecutan la secuencia de comandos no tienen permiso para ver o enumerar los términos dentro del glosario de destino.
  • Incompatibilidad de ID de glosario: El ID de glosario especificado en el comando de la secuencia de comandos no coincide con el ID de recurso del glosario real en Knowledge Catalog.

Para resolver este problema, verifica tu configuración y permisos:

  • Verifica el ID del glosario: En la Google Cloud consola, navega a la página Glosarios de Knowledge Catalog, selecciona tu glosario y confirma que el ID del recurso coincida con el ID que le pasas a la secuencia de comandos de la utilidad.

  • Verifica los permisos de IAM: Confirma que se hayan otorgado los roles necesariosa tus credenciales autenticadas (la cuenta de servicio o tu cuenta de usuario suplantada).

  • Valida la estructura de la URL del glosario: Si le pasas una ruta de acceso o una URL de recurso directa a la secuencia de comandos, asegúrate de que siga el formato de recurso de Knowledge Catalog correcto:

    projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

Advertencia Entries not found in Knowledge Catalog

Durante una operación de importación de vínculos de entradas, la secuencia de comandos se detiene y muestra una advertencia similar a la siguiente:

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

Este problema se produce si tu Hoja de cálculo de Google contiene vínculos de entradas que hacen referencia a recursos de datos o términos de glosario que no existen en Knowledge Catalog.

Para resolver este problema, elige una de las siguientes opciones:

  • Para continuar con una importación parcial, escribe y en el mensaje. La utilidad importa todos los vínculos de entradas válidos y omite solo los vínculos que hacen referencia a los recursos faltantes.

  • Para cancelar y corregir los recursos faltantes, escribe n para cancelar la ejecución. Verifica que los IDs de entradas de tu documento de origen coincidan exactamente con los nombres de los recursos en Knowledge Catalog. Corrige los recursos faltantes o los errores tipográficos y, luego, vuelve a ejecutar la secuencia de comandos de importación.

Soluciona problemas de trabajos de importación de Knowledge Catalog que fallan

Si un trabajo de importación se interrumpe o falla a mitad de la ejecución, no es necesario reiniciar todo el proceso ni modificar tu Hoja de cálculo de Google de origen.

La utilidad hace un seguimiento de los lotes importados correctamente con una carpeta de archivo en tu bucket de etapa de pruebas de Cloud Storage.

Para reanudar el trabajo, sigue estos pasos:

  1. Vuelve a ejecutar la utilidad de importación. La utilidad detecta el estado de la ejecución anterior y muestra el siguiente mensaje:

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

  2. Escribe y. La utilidad omite los lotes que ya se importaron correctamente y procesa solo los archivos restantes.

Tiempos de espera de la secuencia de comandos o errores de SSL durante la ejecución

Mientras se ejecuta la secuencia de comandos de la utilidad de importación o exportación, la ejecución se detiene, se agota el tiempo de espera o muestra errores de SSL en tu terminal.

Este problema se produce debido a los siguientes errores a nivel de la red:

  • Intercepción de proxy o firewall corporativo: Un proxy de seguridad o un firewall intercepta e inspecciona el tráfico HTTPS, lo que invalida los certificados SSL.
  • Restricciones de VPN activas: Tu configuración de VPN restringe el tráfico saliente a ciertas Google Cloud APIs o extremos de Hojas de cálculo de Google.
  • Inestabilidad de la red local: Una caída temporal en la conectividad a Internet interrumpió la sesión.

Para resolver estos problemas de red, prueba los siguientes pasos:

  • Asegúrate de tener una conexión de red estable.

  • Inspecciona la configuración del proxy y el firewall.

  • Verifica tu configuración de VPN.

  • Confía en los reintentos integrados: La secuencia de comandos de la utilidad tiene una lógica de reintento integrada para fallas de red transitorias. Si la caída de la red es momentánea, espera a que la secuencia de comandos termine sus intentos de reintento antes de reiniciar la ejecución.

Error Invalid spreadsheet URL

Cuando intentas ejecutar una utilidad de importación o exportación, la interfaz de línea de comandos muestra un error Invalid spreadsheet URL y detiene la ejecución.

Este problema se produce si la secuencia de comandos no puede analizar el vínculo de la Hoja de cálculo de Google proporcionada o no tiene autorización para ver el archivo. Entre las causas comunes, se incluyen las siguientes:

  • URL con formato incorrecto: La URL no coincide con el formato de ruta de acceso estándar de Hojas de cálculo de Google.
  • Falta el ID de la hoja de cálculo: La ruta de acceso no tiene el ID alfanumérico único que apunta a tu hoja específica.
  • Restricciones de acceso: Tu cuenta de servicio autenticada no tiene permiso para ver ni editar la hoja, lo que impide que la utilidad valide el vínculo.

Para resolver este problema, verifica el vínculo de la hoja de cálculo y la configuración de acceso:

  • Valida el prefijo de la URL: Asegúrate de que la URL de la hoja de cálculo que le pasas a la utilidad comience con la siguiente ruta de acceso estándar de Hojas de cálculo de Google: https://docs.google.com/spreadsheets/.

  • Verifica el ID de la hoja de cálculo: Confirma que la URL incluya el ID único de tu hoja. Una URL válida debe seguir esta estructura: https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

  • Verifica los permisos de acceso: Abre la Hoja de cálculo de Google en un navegador, haz clic en Compartir, y confirma que agregaste el correo electrónico de tu cuenta de servicio como Editor.

Resuelve errores de URL de glosario no válidas

Cuando intentas ejecutar una utilidad de importación o exportación para glosarios, la interfaz de línea de comandos muestra un error Invalid glossary URL y detiene la ejecución. Verifica que no haya ninguna URL de glosario no válida en tus parámetros.

Este problema se produce si la secuencia de comandos no puede analizar la ruta de acceso del recurso de glosario de Knowledge Catalog proporcionada o no tiene autorización para ver el recurso. Entre las causas comunes, se incluyen las siguientes:

  • Ruta de acceso del recurso con formato incorrecto: La ruta de acceso del recurso no coincide con el formato de ruta de acceso del glosario de Knowledge Catalog estándar.
  • ID incorrecto: La ruta de acceso contiene un ID del proyecto, una ubicación de región o un ID de glosario incorrectos.
  • Restricciones de acceso o falta de recursos: El glosario no existe o tu cuenta de servicio autenticada no tiene los permisos de IAM necesarios para acceder a él.

Para resolver este problema, verifica la ruta de acceso del recurso de glosario y las credenciales:

  • Valida la estructura de la ruta de acceso del recurso: Asegúrate de que la ruta de acceso del glosario que le pasas a la utilidad coincida con el siguiente formato de Knowledge Catalog estándar: projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID.

  • Verifica los identificadores en la ruta de acceso: Usa el ID del proyecto, la ubicación y el ID del glosario correctos.

  • Confirma la existencia y el acceso al recurso: Confirma que el glosario exista con el ID especificado y que se hayan otorgado los roles de IAM necesarios a tu cuenta de servicio autenticada.

Visualiza los registros de ejecución

Las utilidades de importación y exportación generan registros de ejecución detallados a medida que se ejecutan. Si falla tu trabajo de importación, revisa los registros para ver errores específicos. Estos registros te ayudan a auditar el proceso de transferencia y a identificar las entradas omitidas o las advertencias de formato.

  • Ubicación de los registros: Las utilidades de importación y exportación escriben archivos de registro en el directorio logs/ de tu ruta de acceso de ejecución local.
  • Formato de los registros: Cada archivo de registro se agrega con una marca de tiempo para que puedas ubicar los registros de una ejecución específica.