Soluciona problemas del framework de extensiones de Looker

El framework de extensiones de Looker te permite compilar aplicaciones y visualizaciones personalizadas de JavaScript y TypeScript que se ejecutan dentro de Looker. Las extensiones se ejecutan en un iframe de zona de pruebas y, además, interactúan con tu instancia de Looker a través del SDK de extensiones. Si tienes problemas con una extensión personalizada, como una página en blanco o un mensaje de error dentro del iframe, errores de JavaScript de la consola del navegador o de uso compartido de recursos de origen cruzado (CORS), solicitudes a la API de Looker fallidas (códigos de estado 4xx o 5xx) o errores de configuración de manifest.lkml, este documento te ayudará a solucionar problemas y resolverlos.

Requisitos previos y requisitos de configuración comunes

Antes de comenzar a solucionar problemas, verifica que tu entorno, el proyecto de LookML y la cuenta de usuario cumplan con los requisitos para ejecutar una extensión de Looker:

  • Framework de extensiones habilitado: Un administrador de Looker debe habilitar el parámetro de configuración Framework de extensiones en Administrador > Plataforma > Framework de extensiones.
  • Configuración del proyecto y del modelo de LookML: Cada extensión requiere un proyecto de LookML que incluya los siguientes componentes:
  • Derechos del manifiesto: La declaración application en el archivo manifest.lkml debe definir de forma explícita todos los entitlements que requiere la extensión, como core_api_methods para las llamadas a la API de Looker o external_api_urls para las solicitudes a dominios externos. Una extensión no se ejecutará sin un bloque entitlements.
  • Permisos de usuario: Los usuarios deben tener permisos de extensión (como access_data, explore o develop) para un conjunto de modelos que incluya el modelo de LookML de la extensión. Para compilar una extensión, los desarrolladores necesitan permisos de LookML develop.
  • Herramientas de diagnóstico y detalles del entorno: Ten listos los siguientes detalles y herramientas antes de comenzar a solucionar problemas:
    • La URL de tu instancia de Looker, el nombre del proyecto de LookML y el nombre de application que se declara en manifest.lkml.
    • Acceso a las herramientas para desarrolladores de tu navegador web (pestañas Consola y Red) en la máquina cliente
    • Durante el desarrollo local, acceso a la terminal que ejecuta tu servidor de desarrollo local
    • Para errores de servidor 5xx en llamadas a la API de Looker, acceso a los registros de la instancia de Looker (looker.log en instancias alojadas por el cliente o el Explorador de registros en Cloud Logging en la consola de Google Cloud para instancias de Looker (Google Cloud Core)).

Árbol de depuración

Usa el siguiente árbol de decisión para comenzar a solucionar problemas del framework de extensiones de Looker:

En las siguientes secciones, se describen las situaciones del árbol con más detalle.

Inspecciona la consola del navegador y los registros de red

Debido a que las extensiones de Looker se ejecutan del lado del cliente en tu navegador, comienza a solucionar problemas inspeccionando las herramientas para desarrolladores de tu navegador en busca de errores de JavaScript, incumplimientos de políticas de seguridad y solicitudes HTTP con errores.

Revisa la consola del navegador para ver si hay errores

Para identificar los errores del cliente que impiden que la extensión se cargue o ejecute, sigue estos pasos:

  1. En Looker, abre la página en la que se carga la extensión.
  2. Haz clic con el botón derecho en cualquier lugar de la página y selecciona Inspeccionar (o presiona Control + Mayúsculas + I en Windows y Linux, o Comando + Opción + I en macOS).
  3. En el panel de herramientas para desarrolladores, selecciona la pestaña Consola.
  4. Actualiza la página para capturar los errores que se producen durante la carga inicial.
  5. Inspecciona los mensajes de error rojos en la consola:

Inspecciona la pestaña Red para ver las solicitudes con errores

Para analizar las solicitudes HTTP que realiza la extensión para paquetes de JavaScript, recursos o extremos de API, sigue estos pasos:

  1. En el panel de herramientas para desarrolladores del navegador, selecciona la pestaña Red.
  2. Selecciona la casilla de verificación Inhabilitar caché para que el navegador no cargue recursos almacenados en caché obsoletos.
  3. Actualiza la página en la que se carga la extensión.
  4. Revisa la lista de solicitudes de red para ver si hay códigos de estado 4xx o 5xx, y selecciona una solicitud con errores para inspeccionar sus pestañas Encabezados, Carga útil y Respuesta:
    • 404 en el paquete de extensiones (como bundle.js): Verifica que el servidor de desarrollo esté en ejecución y que el parámetro url o file en manifest.lkml sea correcto.
    • 401 o 403 en una solicitud a la API de Looker: Investiga la autenticación, los permisos y los derechos.
    • 400 o 422 en una solicitud a la API: Inspecciona las pestañas Carga útil y Respuesta para identificar JSON con formato incorrecto o parámetros de solicitud no válidos.
    • Errores de servidor 5xx: Indican errores del servidor en la instancia de Looker. Verifica looker.log en las instancias alojadas por el cliente o el Explorador de registros en la consola para las instancias de Looker (Google Cloud Core) para encontrar entradas con marcas de tiempo que coincidan.

Si no aparecen errores en las pestañas Consola o Red, o si necesitas verificar cómo Looker carga la extensión, continúa con la siguiente sección.

Verifica el manifiesto y la configuración del proyecto

La declaración application en el archivo manifest.lkml de tu proyecto controla cómo Looker carga la extensión y qué recursos puede usar la extensión. Los errores de configuración en manifest.lkml son una causa común de fallas de carga y de la API:

  • Verifica el parámetro url o file: En el IDE de Looker, abre el archivo manifest.lkml de tu proyecto y, luego, inspecciona la declaración application:
    • Una declaración application debe incluir un parámetro url o un parámetro file, pero no ambos.
    • Durante el desarrollo local: Verifica que el parámetro url coincida con el protocolo (http o https), el nombre de host, el puerto y la ruta de acceso exactos que entrega tu servidor de desarrollo local (por ejemplo, https://localhost:8080/bundle.js).
    • En producción: Verifica que hayas actualizado la declaración application de la ruta de acceso de desarrollo local url a la ruta de acceso de producción file en tu proyecto de LookML (por ejemplo, file: "apps/bundle.js") o la URL del paquete de producción.
  • Verifica los derechos de manifest.lkml: Revisa el bloque entitlements en tu declaración de application. Una extensión no puede usar un recurso de Looker ni un dominio externo, a menos que ese derecho se declare de forma explícita, como se indica a continuación:
    • core_api_methods: Debe enumerar todos los métodos de la API de Looker a los que llama tu extensión (por ejemplo, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: Debe enumerar todos los dominios externos que no sean de Looker que la extensión solicite directamente o a través del proxy.
    • Derechos adicionales: Verifica si tu extensión requiere local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes o scoped_user_attributes.
  • Valida, confirma e implementa: Después de editar manifest.lkml, haz clic en Validar LookML, confirma los cambios y haz clic en Implementar en producción para que se aplique la configuración actualizada.

Soluciona problemas del servidor y el entorno de desarrollo locales

Cuando desarrollas una extensión de forma local con el parámetro url en manifest.lkml, el servidor de desarrollo local debe estar en ejecución y ser accesible desde el navegador:

  • Confirma que el servidor de desarrollo se esté ejecutando: Revisa la ventana de la terminal en la que iniciaste el servidor de desarrollo (por ejemplo, con yarn develop o npm start):
    • Verifica que la compilación se haya realizado sin errores y que muestre un mensaje de escucha (como webpack compiled successfully o listening on localhost:8080).
    • Si el servidor no se está ejecutando, inícialo con yarn develop o npm start.
    • Si el servidor se cerró con un error de sintaxis o de dependencia faltante, resuelve el error de código o ejecuta yarn install (o npm install) para instalar los paquetes faltantes.
    • Si el servidor falla con un conflicto de puerto (EADDRINUSE), detén el otro proceso que usa ese puerto o configura tu servidor de desarrollo y el parámetro manifest.lkml url para usar un puerto diferente.
  • Abre la URL de la extensión directamente en el navegador: Copia el valor url de manifest.lkml (por ejemplo, https://localhost:8080/bundle.js) y ábrelo en una nueva pestaña del navegador:
    • Certificado SSL autofirmado no confiable: Los servidores de desarrollo locales suelen usar certificados SSL autofirmados. Si tu navegador muestra una advertencia de seguridad del certificado, selecciona Avanzado y continúa con localhost para confiar en el certificado de tu sesión del navegador. Hasta que se confíe en el certificado, el navegador bloqueará la carga del paquete dentro del iframe de Looker.
    • Conexión rechazada o bloqueada: Si el navegador no puede acceder a la URL, verifica que ningún firewall local ni software de seguridad de extremos bloquee las conexiones a localhost en el puerto configurado.

Soluciona problemas de redes, CORS y políticas de seguridad

Los navegadores web aplican la política del mismo origen, que impide que Looker cargue recursos de extensiones o llame a servidores externos en un origen diferente, a menos que se configuren los encabezados y las políticas de seguridad del uso compartido de recursos de origen cruzado (CORS):

  • Identifica los errores de CORS en la consola del navegador: Busca mensajes de error en la pestaña Consola que contengan Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy o encabezados Access-Control-Allow-Origin faltantes.
  • Configura los encabezados de CORS del servidor de desarrollo local: Si usas webpack-dev-server (o un agrupador similar), asegúrate de que la configuración de devServer en webpack.config.js incluya el encabezado Access-Control-Allow-Origin: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Configura el hosting de producción y los encabezados de CORS de la API externa: Si tu extensión carga recursos o solicita datos de un servicio externo (como Cloud Storage, Amazon S3 o un servidor de backend personalizado), configura el servicio de hosting para que devuelva el encabezado Access-Control-Allow-Origin que permite el dominio de tu instancia de Looker. También verifica que ningún proxy de red o firewall quite los encabezados de CORS de la respuesta y asegúrate de que el dominio externo aparezca en external_api_urls en manifest.lkml.
  • Verifica la Política de Seguridad del Contenido (CSP) y la carga de extensiones mejorada: Si encuentras incumplimientos de la CSP cuando cargas una extensión, verifica el parámetro de configuración Carga de extensiones mejorada en Administrador > Plataforma > Marco de trabajo de extensiones.

Soluciona problemas de autenticación y acceso a la API

Las extensiones interactúan con la API de Looker en nombre del usuario que accedió a través del SDK de extensiones. Si las llamadas a la API fallan con los códigos de estado 401 Unauthorized o 403 Forbidden en la pestaña Red, investiga lo siguiente:

  • Distingue entre los errores 401 y 403:
    • 401 Unauthorized: No se autenticó la solicitud. Por lo general, este error se produce si el SDK de extensiones no se inicializó correctamente o si la extensión intentó realizar una llamada a la API antes de que el SDK completara su protocolo de enlace de autenticación.
    • 403 Forbidden: Se autenticó la solicitud, pero el usuario que accedió no tiene los permisos de Looker necesarios o el manifest.lkml de la extensión no incluye el método llamado en core_api_methods.
  • Verifica los roles y permisos de los usuarios: En Administrador > Usuarios y Administrador > Roles, verifica los roles, los conjuntos de permisos y los conjuntos de modelos asignados al usuario que accedió:
    • Confirma que el usuario tenga permisos para usar la extensión, incluidos access_data (y explore o develop según sea necesario) para un conjunto de modelos que contenga el modelo de LookML de la extensión y cualquier modelo que consulte la extensión.
    • Confirma que el rol del usuario incluya los permisos específicos que requiere cada extremo de API de Looker al que llama la extensión.
  • Asegúrate de que el contexto del SDK esté listo antes de llamar a la API: Verifica que el código de tu extensión espere a que se inicialice el contexto del SDK de extensiones antes de invocar los métodos de la API.

Soluciona problemas del SDK de extensión y las dependencias

Los problemas con la instalación de paquetes de npm o Yarn, o la falta de componentes del proveedor del SDK, pueden impedir que una extensión se compile o se conecte a Looker:

  • Verifica la instalación del módulo de Node.js: En la terminal, ve al directorio raíz del proyecto de extensión y verifica el directorio node_modules:
    1. Si falta node_modules o las dependencias parecen dañadas, borra el directorio node_modules y el archivo de bloqueo (yarn.lock o package-lock.json).
    2. Opcional: Si la instalación del paquete falla repetidamente, borra la caché del administrador de paquetes (por ejemplo, ejecuta npm cache clean --force).
    3. Verifica que la versión de Node.js instalada sea compatible con los requisitos del proyecto y, luego, ejecuta yarn install o npm install para realizar una instalación limpia.
  • Verifica la inicialización de ExtensionProvider: Abre el archivo de entrada principal de tu extensión (como App.js o index.js) y confirma que <ExtensionProvider> (importado de @looker/extension-sdk-react) une los componentes de la aplicación que necesitan el contexto del SDK de Looker: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Si falta <ExtensionProvider> o si lo colocaste después de los componentes que llaman al SDK, los componentes secundarios no podrán acceder al contexto del SDK.

Soluciona problemas de errores de lógica y de JavaScript en el entorno de ejecución

Si la configuración de la extensión, el servidor de desarrollo, los permisos y la configuración del SDK son válidos, el problema podría ser un error de tiempo de ejecución en el código personalizado de JavaScript o TypeScript de la extensión:

  • Analiza los seguimientos de pila de la consola: En la pestaña Consola del navegador, busca el mensaje de error rojo y haz clic en la flecha de expansión para ver el seguimiento de pila completo. Las líneas superiores del seguimiento de pila identifican el archivo y el número de línea en tu código fuente donde se produjo el error. Haz clic en el vínculo del archivo (por ejemplo, MyComponent.js:42) para ir directamente a esa línea en la pestaña Fuentes.
  • Verifica si hay valores indefinidos o nulos: En el caso de errores como TypeError: Cannot read properties of undefined, verifica que las respuestas o propiedades asíncronas de la API hayan terminado de cargarse antes de que tu código lea las propiedades anidadas. Agrega verificaciones defensivas (como if (myObject && myObject.property) o encadenamiento opcional myObject?.property).
  • Verifica los formatos de respuesta de la API: Confirma que tu código controle la estructura de datos real que devuelven las llamadas a la API de Looker (por ejemplo, verifica si una carga útil de respuesta es un objeto o un array antes de llamar a los métodos de array).
  • Depura con puntos de interrupción y registros: En la pestaña Sources del navegador, establece puntos de interrupción antes de la línea con errores para pausar la ejecución y, luego, inspecciona los valores de las variables en tiempo real o agrega sentencias console.log() para hacer un seguimiento del flujo de ejecución.

Verifica la compatibilidad de la versión de Looker

Las actualizaciones o los cambios importantes de las funciones en Looker pueden requerir una versión compatible del SDK de extensiones de Looker:

  1. Verifica la versión de @looker/extension-sdk (y @looker/extension-sdk-react, si se usa) en el archivo package.json del proyecto de extensión.
  2. En la interfaz web de Looker, verifica la versión de actualización actual de tu instancia en Ayuda > Acerca de o Administrador > General > Configuración.
  3. Compara tu versión de actualización de Looker con las notas de compatibilidad en la documentación de @looker/extension-sdk.
  4. Si tu instancia de Looker se actualizó recientemente y la extensión usa un SDK desactualizado, o si la extensión usa una función del SDK más reciente que no es compatible con una versión anterior de Looker, actualiza el paquete del SDK a una versión compatible: bash npm install @looker/extension-sdk@latest Después de actualizar el paquete, reinstala las dependencias y reinicia el servidor de desarrollo.

Recopila información de diagnóstico

Si no puedes resolver el problema después de seguir los pasos para solucionar problemas, recopila la siguiente información antes de comunicarte con el equipo de asistencia:

  1. Información de la instancia y el proyecto de Looker:
    • La URL de la instancia de Looker (por ejemplo, instance_name.looker.com).
    • Es la versión de actualización de Looker.
    • Es el nombre del proyecto de LookML que contiene la extensión y el nombre de application en manifest.lkml.
  2. Configuración de la extensión y detalles del SDK:
    • Una copia o captura de pantalla de la declaración application en el archivo manifest.lkml
    • La versión de @looker/extension-sdk que se especifica en package.json.
    • Indica si la extensión se ejecuta desde un servidor de desarrollo local (url) o se implementa en producción (file).
  3. Registros de errores y capturas de pantalla:
    • Capturas de pantalla o texto completo de los errores de las pestañas Consola y Red del navegador (incluidos los encabezados de la solicitud y las cargas útiles de respuesta para las solicitudes 4xx o 5xx con errores).
    • Si las llamadas a la API devuelven de forma constante errores de servidor 5xx, extractos de registros coincidentes de looker.log (para instancias alojadas por el cliente) o el Explorador de registros en Logging (para instancias de Looker (Google Cloud Core)).
  4. Resumen de la solución de problemas y pasos para reproducirlos:
    • Un resumen de los pasos de solución de problemas que ya realizaste y sus resultados.
    • Pasos exactos para reproducir el problema o un ejemplo mínimo reproducible si sospechas que hay un problema en el framework de extensiones de Looker o el SDK de extensiones.

Comunicarse con el equipo de asistencia

Si verificaste todos los pasos anteriores y el problema aún no se resolvió, haz lo siguiente: