Desactivación de la API Looker 3.x

La API 3.x se inhabilitará en agosto del 2023

Anteriormente, habíamos comunicado que este cambio se produciría en la versión de julio del 2023. En respuesta a los comentarios de los clientes, hemos aplazado esta fecha límite hasta agosto del 2023 para que la transición sea más fluida. Cierra este cuadro de diálogo para obtener más información.

Tras el lanzamiento de la versión 4.0 de la API en Looker 22.4, anunciamos la retirada de la versión 3.1 de la API, además de la versión 3.0, que ya se había retirado.

Desde que anunciamos la retirada de las APIs 3.1 y 3.0 (denominadas 3.x) en junio del 2022, ambas están obsoletas. Las versiones 3.x de la API se inhabilitarán a partir del lanzamiento de la versión 23.14 de Looker en agosto del 2023.

Esta actualización se implementará en las instancias alojadas en Looker durante las horas de mantenimiento entre el 14 y el 24 de agosto. Por lo tanto, todas las instancias alojadas en Looker deben actualizar sus aplicaciones para usar los endpoints de la API 4.0 en lugar de los de la API 3.x antes del 14 de agosto del 2023. Cualquier función que dependa de los endpoints de la versión 3.x dejará de funcionar después de este cambio.

Si tu instancia está autohospedada, debes actualizar tus aplicaciones antes de actualizar tu instancia de Looker a la versión 23.14 o posterior.

La API 4.0 abarca por completo las funciones que ofrecen las APIs obsoletas, y esperamos que la actualización de la versión 3.x a la 4.0 sea sencilla para la mayoría de los clientes.

Los clientes que no puedan migrar correctamente a la API 4.0 deben ponerse en contacto con el servicio de asistencia de Looker.

Cronología

  • Antes del 2022: la API 3.0 está obsoleta, la 3.1 es estable y la 4.0 está en fase beta.
  • Marzo del 2022: la API 4.0 pasa a estar en estado estable y está disponible de forma general en Looker 22.4
  • Junio del 2022: se anuncia la retirada de la API 3.1
  • Agosto del 2023: se desactivará la API 3.x en Looker

¿A quién va dirigida esta información?

Este documento está dirigido a los usuarios que utilizan la API de Looker a través de los SDKs compatibles con Looker, los SDKs compatibles con la comunidad o la propia API. Sigue leyendo para obtener información sobre los cambios que pueden afectar a tu aplicación y

¿Qué debo hacer?

Deberá hacer los siguientes cambios en su código. Se describen con más detalle más adelante en esta página.

  • Cambia el código para que apunte a la nueva API.
  • Identifica el uso de los endpoints retirados y sustituye esas referencias por el equivalente de la API 4.0.
  • Actualiza los valores de ID que antes se expresaban como números para que se expresen como cadenas.

Detalles de la migración a la API 4.0

Cambiar el código para que apunte a la nueva API

Cuando hagas llamadas a la API directamente a través de la línea de comandos o de programas como Postman, tendrás que ajustar la URL que utilices para hacer la solicitud.

### API 3.1 ###
GET https://myinstance.looker.com/api/3.1/users/5877

### API 4.0 ###
GET https://myinstance.looker.com/api/4.0/users/5877

Si usas uno de nuestros SDKs, tendrás que asegurarte de inicializar la versión correcta. A continuación, se muestra un ejemplo básico de cómo podría ser el principio de una secuencia de comandos de Python con nuestro SDK en ambas versiones:

### API 3.1 ###
import looker_sdk
sdk = looker_sdk.init31()

### API 4.0 ###
import looker_sdk
sdk = looker_sdk.init40()

Una vez que hayas cambiado a la API 4.0, es el momento de probar tu código y buscar los siguientes cambios.

Sustituciones de endpoints de la API 3.x

Para que la terminología sea coherente entre la API de Looker y la interfaz de usuario de Looker, la API 4.0 sustituye algunos endpoints de la API 3.x obsoletos por endpoints equivalentes o mejorados, que se indican a continuación:

Se ha cambiado el nombre de los endpoints de "Space". En su lugar, utilice los endpoints sinónimos "Folder".

Ejemplo de SDK de Python

    #####################
    ##### API 3 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_space(
      body=mdls.CreateSpace(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.space(space_id="555")

    # Change name of existing Folder
    response = sdk.update_space(
      space_id="555",
      body=mdls.UpdateSpace(
        name="My Updated Folder"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_folder(
      body=mdls.CreateFolder(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.folder(folder_id="555")

    # Change name of existing Folder
    response = sdk.update_folder(
      space_id="555",
      body=mdls.UpdateFolder(
        name="My Updated Folder"
      )
    )

Ejemplo de cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/spaces/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/3.1/spaces/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/folders/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/4.0/folders/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

Se han eliminado los endpoints "Homepage". En su lugar, usa los endpoints de la función ampliada "board".

Ejemplo de SDK de Python

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    response = sdk.homepage(homepage_id=1348)

    # Update displayed title of Board item
    response = sdk.update_homepage_item(
      homepage_item_id=86,
      body=mdls.WriteHomepageItem(
        custom_title="Volume 3"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    response = sdk.board(board_id=1348)

    # Update displayed title of Board item
    response = sdk.update_board_item(
      board_item_id=86,
      body=mdls.WriteBoardItem(
        custom_title="Volume 3"
      )
    )

Ejemplo de cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/homepages/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/3.1/homepage_items/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/boards/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/4.0/boards/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

Tipos de campos de ID de la API 4.0

En la API 4.0 se han actualizado los tipos de algunos campos de ID de números a cadenas. Usa nuestra herramienta de comparación de referencias de la API para determinar qué campos de ID han cambiado entre las versiones 3.1 y 4.0. Usa SDKs de lenguajes compatibles con Looker actualizados (23.0 o versiones posteriores) para asegurarte de que tus aplicaciones tengan el tipo correcto durante la migración y después de ella. La mayoría de los SDKs de lenguajes compatibles con la comunidad, como Kotlin, Swift, R, C# y Go, también funcionan con los tipos actualizados.

Los desarrolladores que usen bibliotecas personalizadas deben buscar en su código referencias a estos campos para asegurarse de que se gestionan correctamente.

Diferencias de la API 4.0

Además de las directrices que se indican en esta página de documentación, el Explorador de APIs de Looker ofrece una lista completa de todas las diferencias entre las APIs 3.x y la API 4.0.

Habilitar o inhabilitar la API 3.x mediante el antiguo interruptor de funciones

En el caso de los clientes alojados en Looker que usen Looker 23.6, 23.8, 23.10 y 23.12, los administradores pueden inhabilitar todas las llamadas a los endpoints de la API 3. De esta forma, podrás hacer pruebas en tu instancia para asegurarte de que no se interrumpan los servicios ni las aplicaciones integrados antes del 14 de agosto. Para ello, puedes activar la opción "Deny API 3.x requests" (Rechazar solicitudes de la API 3.x) en el panel de administración de funciones antiguas.

Los clientes con alojamiento propio que usen Looker 23.6, 23.8, 23.10 y 23.12 pueden ejecutar el siguiente comando de shell antes de iniciar Looker para añadir una variable de entorno que hará que el interruptor "Deny API 3.x requests" (Denegar solicitudes de la API 3.x) esté visible. Nota: Después de ejecutar el comando, tendrás que activar el interruptor en el panel Funciones antiguas de la interfaz de usuario de Looker para detener las llamadas a la API 3.

export FF_DENY_API3=true

Preguntas frecuentes

No sé si se están haciendo llamadas a la API 3.x en mi instancia. ¿Cómo puedo encontrar esta información?

Desde Looker 23.8, la columna Fuente del panel Administrar > Consultas ahora muestra correctamente la versión de la API (v3 o v4) de las consultas que se inician desde la API de Looker. Esto no incluirá información sobre tareas de administrador o desarrollador, como la creación de usuarios o tareas de desarrollo de LookML o de Git.

Nuestro servicio de informes interno tiene información más detallada sobre las solicitudes de las APIs, incluidas las que se usan para completar tareas de administrador y de desarrollo de LookML. Los clientes cuyas instancias sigan la configuración de red recomendada pueden ponerse en contacto con el servicio de asistencia de Looker para solicitar una exportación de estos datos.

Tengo mi propia instancia. ¿Tengo que cambiar a la versión de pago antes del 14 de agosto del 2023?

Si tu instancia está autohospedada, tendrás que hacer los cambios antes de actualizar a la versión de agosto del 2023 (versión 23.14) o a cualquier versión posterior. Le recomendamos que empiece a hacerlo lo antes posible para poder seguir usando una versión compatible y disfrutar de la mejor experiencia con Looker.

Mi instancia está alojada en Looker, pero en el programa ESR. ¿Tengo que cambiar a la versión de pago antes del 14 de agosto del 2023?

Deberás hacer los cambios antes de que tu instancia se actualice a la versión de agosto del 2023 (23.14) o a cualquier versión posterior. Te recomendamos que empieces a hacerlo lo antes posible para que no tengas que correr cuando se programe la actualización de tu instancia.

He leído la documentación, pero sigo teniendo problemas o no sé cómo proceder.

Los clientes que no puedan migrar correctamente a la API 4.0 deben ponerse en contacto con el servicio de asistencia de Looker.