Baja de la API de Looker 3.x

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

Anteriormente, comunicamos que este cambio se produciría en la versión de julio de 2023. En función de los comentarios de los clientes, trasladamos esta fecha límite a agosto de 2023 para que la transición sea más fluida. Cierra este diálogo para obtener más detalles.

Después de nuestro lanzamiento de la API 4.0 con DG en Looker 22.4, anunciamos la baja de nuestra API 3.1, además de nuestra API 3.0, que ya está obsoleta.

A partir de nuestro anuncio de baja en junio de 2022, tanto la API 3.1 como la API 3.0, denominadas 3.x, se encuentran en estado de baja. Las versiones 3.x de la API se inhabilitarán a partir del lanzamiento de la versión 23.14 de Looker en agosto de 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. Como resultado, todas las instancias alojadas en Looker deben actualizar sus aplicaciones para usar los endpoints de API 4.0 en lugar de los endpoints de API 3.x antes del 14 de agosto de 2023. Cualquier funcionalidad que dependa de los extremos de la versión 3.x dejará de funcionar después de este cambio.

Si tu instancia es autoalojada, 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 la funcionalidad 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 comunicarse con el equipo de asistencia de Looker.

Cronograma

  • Antes de 2022: La API 3.0 está en estado obsoleto, la 3.1 está en estado estable y la 4.0 está en estado beta
  • Marzo de 2022: La API 4.0 entra en estado estable y está disponible de forma general en Looker 22.4
  • Junio de 2022: Se anuncia la baja de la API 3.1
  • Agosto de 2023: Se desactivará la API 3.x en Looker

¿Quién debería leer esto?

Este documento es para ti si usas la API de Looker a través de los SDK compatibles con Looker, los SDK compatibles con la comunidad o la API en sí. Sigue leyendo para obtener información sobre los cambios rotundos que pueden afectar tu aplicación y aprender

¿Qué debo hacer?

Deberás realizar los siguientes cambios en tu código. Estos se describen con más detalle más adelante en esta página.

  • Cambia tu código para que apunte a la API nueva.
  • Identifica el uso de los extremos quitados y reemplaza 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 de la API 4.0

Cambia tu código para que apunte a la API nueva

Cuando realices llamadas a la API directamente a través de la línea de comandos o programas como Postman, deberás ajustar la URL que usas para realizar 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, deberás asegurarte de inicializar la versión correcta del SDK. Este es un ejemplo básico de cómo se vería el comienzo 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 realizado el cambio a la API 4.0, es hora de probar tu código y prestar atención a los siguientes cambios.

Reemplazos de extremos de la API 3.x

Para mantener la coherencia de la terminología entre la API de Looker y la IU de Looker, la API 4.0 reemplaza algunos extremos obsoletos de la API 3.x por extremos equivalentes o mejorados, que se indican a continuación:

Se cambiaron los nombres de los extremos de "Space". En su lugar, usa los extremos sinónimos de "Carpeta".

Ejemplo del 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 quitaron los extremos de "Página principal". En su lugar, usa los endpoints de "tablero" con funcionalidad expandida.

Ejemplo del 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 que generan errores en la API 4.0

La API 4.0 actualizó 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 cambiaron entre la versión 3.1 y la 4.0. Usa SDKs de lenguaje compatibles con Looker actualizados (23.0 o versiones posteriores) para asegurarte de que tus aplicaciones tengan el tipo correcto durante y después de la migración. La mayoría de los SDK de lenguajes compatibles con la comunidad, incluidos Kotlin, Swift, R, C# y Go, también funcionan con los tipos actualizados.

Los desarrolladores que usan bibliotecas personalizadas deben buscar referencias a estos campos en su código para asegurarse de que se manejen de forma adecuada.

Diferencias de la API 4.0

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

Inhabilitación o habilitación de la API 3.x a través del parámetro de configuración de funciones heredadas

Para los clientes alojados en Looker que usan Looker 23.6, 23.8, 23.10 y 23.12, los administradores actualmente tienen la capacidad de inhabilitar todas las llamadas a los extremos de la API 3. Esto te permitirá realizar pruebas en tu instancia para asegurarte de que no se interrumpan los servicios o las aplicaciones integrados antes de la fecha límite del 14 de agosto. Para ello, puedes activar la opción "Rechazar solicitudes de la API 3.x" en el panel de administración de funciones heredadas.

Los clientes que usan Looker 23.6, 23.8, 23.10 y 23.12 alojado de forma automática pueden ejecutar el siguiente comando de shell antes de iniciar Looker para agregar una variable de entorno que hará visible el botón de activación "Rechazar solicitudes de la API 3.x" (Nota: Después de ejecutar el comando, deberás activar el botón de activación en el panel Funciones heredadas de la IU de Looker para detener las llamadas a la API 3):

export FF_DENY_API3=true

Preguntas frecuentes

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

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

Nuestro servicio de informes interno tiene información más detallada sobre las solicitudes a la API, incluidas las que se usan para completar las tareas de desarrollo de LookML y de administración. Los clientes con instancias que siguen la configuración de red recomendada pueden comunicarse con la Asistencia de Looker para solicitar una exportación de estos datos.

Alojo mi propia instancia. ¿Debo actualizar antes del 14 de agosto de 2023?

Si tu instancia es autohospedada, deberás realizar los cambios antes de actualizar a la versión de agosto de 2023 (versión 23.14) o cualquier versión posterior. Te recomendamos que comiences a realizar este trabajo lo antes posible para que puedas mantenerte en una versión compatible y obtener la mejor experiencia con Looker.

Mi instancia está alojada en Looker, pero en el programa de ESR. ¿Debo actualizar antes del 14 de agosto de 2023?

Deberás realizar los cambios antes de que tu instancia se actualice a la versión de agosto de 2023 (versión 23.14) o a cualquier versión posterior. Te recomendamos que comiences a realizar este trabajo lo antes posible para que no tengas poco tiempo cuando tu instancia esté programada para recibir esa actualización.

Leí 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 comunicarse con el equipo de asistencia de Looker.