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

Knowledge Catalog (anteriormente, Dataplex Universal Catalog) te permite importar y exportar glosarios empresariales y vínculos de entradas de forma masiva para administrar tu vocabulario empresarial a gran escala. Cuando ejecutas las secuencias de comandos de la utilidad de importación o exportación, puedes diagnosticar y resolver problemas comunes, como vínculos de entrada faltantes, exportaciones de glosarios vacíos, URLs de glosarios o hojas de cálculo no válidas, trabajos de importación interrumpidos y tiempos de espera de red de secuencias de comandos. Para obtener más información, consulta Acerca de la importación y exportación de glosarios y vínculos de entradas.

Si necesitas ayuda para resolver un problema que no se aborda en este documento, consulta Atención al cliente de Cloud.

Corrige los vínculos de entrada faltantes en Knowledge Catalog

Después de exportar los vínculos de entrada de Knowledge Catalog a una hoja de cálculo de Google ejecutando la utilidad de exportación de vínculos de entrada, notarás que faltan algunos vínculos de entrada (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 entrada debido a las siguientes condiciones:

  • Permisos insuficientes (recursos ocultados): No tienes los permisos de IAM necesarios para ver la entrada de origen o la entrada de destino asociada con el 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 entrada incompletas: Faltan 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 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 los registros de la terminal o de la secuencia de comandos para ver si hay advertencias que contengan Skipping redacted entrylink. Los registros muestran los IDs de recursos específicos de los vínculos de entrada 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.

No se encontraron términos en el error del glosario

Cuando exportas glosarios a una hoja de cálculo de Google, la ejecución falla o devuelve 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 encontrar 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 tus parámetros de ejecución es incorrecta o está mal escrita.
  • 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 términos dentro del glosario de destino.
  • No coincide el ID del glosario: El ID del glosario especificado en el comando de la secuencia de comandos no coincide con el ID del recurso del glosario real en Knowledge Catalog.

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

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

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

  • Valida la estructura de la URL del glosario: Si 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 de entradas no encontradas en Knowledge Catalog

Durante una operación de importación de vínculos de entrada, 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 entrada que hacen referencia a recursos de datos o términos del 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 entrada 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 entrada de tu documento de origen coincidan exactamente con los nombres de los recursos en tu catálogo de conocimientos. Corrige los recursos faltantes o los errores tipográficos y, luego, vuelve a ejecutar la secuencia de comandos de importación.

Soluciona problemas de fallas en el trabajo de importación de Knowledge Catalog

Si un trabajo de importación se interrumpe o falla durante la ejecución, no es necesario que reinicies todo el proceso ni que modifiques la 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 tu 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. Tipo 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 se devuelven errores de SSL en la terminal.

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

  • Intercepción de proxy o firewall corporativo: Un proxy o firewall de seguridad 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 APIs de Google Cloud 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 del firewall

  • Verifica la configuración de la VPN.

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

Error de URL de hoja de cálculo no válida

Cuando intentas ejecutar una utilidad de importación o exportación, la interfaz de línea de comandos devuelve 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: Falta 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 pases a la utilidad comience con la siguiente ruta 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.

Cómo resolver errores de URL de glosario no válida

Cuando intentas ejecutar una utilidad de importación o exportación para glosarios, la interfaz de línea de comandos devuelve un error Invalid glossary URL y detiene la ejecución. Verifica que no haya una 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 del 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 estándar del glosario de Knowledge Catalog.
  • 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 recurso faltante: 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 y las credenciales del recurso del glosario:

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

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

  • Confirma la existencia y el acceso de los recursos: 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 tu trabajo de importación falla, revisa los registros para detectar 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/ en tu ruta de ejecución local.
  • Formato de registro: Cada archivo de registro se agrega con una marca de tiempo para que puedas ubicar los registros de una ejecución específica.