Dominé el Explorador de API de Looker. ¿Y ahora qué?

Con el Explorador de APIs de Looker, los usuarios pueden probar las llamadas a la API casi de inmediato sin tener que escribir una sola línea de código. Si instalaste la extensión del Explorador de API desde el Marketplace de Looker, puedes hacer clic en Explorador de API en el menú Aplicaciones de Looker para abrir el Explorador de API y ver la documentación actual de la API. Si no instalaste la extensión del Explorador de API, puedes hacerlo desde la sección Applications de Looker Marketplace.

Tal vez, con el uso del Explorador de APIs, hayas descubierto el mejor flujo de trabajo para crear de forma dinámica una vista, actualizar la consulta subyacente y programarla para varias partes interesadas de tu empresa. Una pregunta común es: "¿Cómo ejecuto estas llamadas o funciones fuera del Explorador de APIs?". Existen tres formas comunes de acceder a la API:

  1. Kits de desarrollo de software (SDK) de la API de Looker
  2. Solicitudes HTTP
  3. Herramientas de desarrollo de software

En esta página, se explica cómo usar estos métodos.

Antes de comenzar: Autenticación y puertos

Independientemente de cómo accedas a la API de Looker, primero necesitarás dos datos: tu autenticación personal de la API (en forma de ID de cliente y secreto del cliente) y el número de puerto que usa tu instancia de Looker.

Para encontrar un ID de cliente y un secreto del cliente, haz lo siguiente:

  • Si eres administrador de Looker, visita la página Usuarios en la IU de Looker del usuario que te interesa y ve a Editar claves.
  • Si no eres administrador de Looker, tu administrador de Looker te habrá enviado tu ID de cliente y secreto del cliente.
Lo más importante que debes recordar sobre tu ID de cliente y secreto de cliente es no compartir estas claves con nadie.

En el caso de las instancias de Looker alojadas en Google Cloud o Microsoft Azure, y de las instancias alojadas en Amazon Web Service (AWS) que se crearon a partir del 07/07/2020, la ruta de acceso predeterminada de la API de Looker usa el puerto 443. En el caso de las instancias de Looker alojadas en AWS que se crearon antes del 7/7/2020, la ruta de acceso predeterminada de la API de Looker usa el puerto 19999.

Si alojas tu propia instancia, consulta con el administrador del sistema el número de puerto. Se puede establecer en el campo URL del host de la API del panel de administración de Looker. Para ver esto, ve al menú desplegable Administrador en Looker y selecciona API.

Para obtener más información sobre los puertos, consulta la página de documentación Cómo comenzar a usar la API de Looker. En los siguientes ejemplos, se usa un puerto de API de 19999, pero debes confirmar el puerto que usa tu instancia.

Opción 1: Usa un kit de desarrollo de software (SDK) de Looker

Looker ofrece SDKs de cliente oficiales de la API de Looker en Python, Ruby, Typescript y JavaScript, Swift, Kotlin y R. Puedes encontrar el código fuente y los ejemplos en el repositorio de GitHub sdk-examples de Looker.

Un SDK proporciona herramientas o bibliotecas que permiten a los desarrolladores interactuar con una plataforma o aplicación determinada. En este caso, los SDK de Looker suelen contener APIs. Para tomar prestado un ejemplo del desarrollador web y autor Kristopher Sandoval, "Las APIs son líneas telefónicas que permiten la comunicación dentro y fuera de la casa. El SDK es la casa en sí y todo su contenido". En un excelente artículo, What Is the Difference Between an API and an SDK?, explica qué es un SDK y cómo se relaciona con las APIs.

Los SDKs de Looker contienen todos los extremos de API que podrías querer o necesitar usar, y están empaquetados de una manera que te permite interactuar sin problemas con Looker usando el lenguaje de programación que prefieras. Las funciones te permiten realizar las siguientes tareas:

  • Envía datos a Looker
  • Cómo obtener datos de Looker
  • Actualiza datos en Looker
  • Borra datos en Looker
En la siguiente sección, se analizarán los detalles más detallados de las diferencias entre estas acciones.

Este es un ejemplo de cómo puedes actualizar un usuario con el SDK de Python:

  1. Inicializa la sesión con looker_sdk.init.
  2. Actualiza al usuario con sdk.update_user. Pasas el user_id para especificar qué usuario quieres actualizar.
  3. Usa models.WriteUser para especificar cómo deseas actualizar el usuario. 

    #### Initialize API/SDK for more info go here: https://pypi.org/project/looker-sdk
    from looker_sdk import methods40, models
    sdk = looker_sdk.init40()
    me = sdk.me()
    # print(me)
    new_friend = sdk.update_user(user_id=29,
    body=models.WriteUser(first_name="newnew", last_name="new_again"))
    print(new_friend)

Cuando uses uno de nuestros SDKs, si usas un IDE como Visual Studio Code y haces clic con el botón Comando (F12 en la configuración predeterminada de Visual Studio Code) y, luego, seleccionas Ir a definiciones, puedes ver todos los métodos y todos los parámetros que aceptan o devuelven los métodos. También puedes verlas en el repositorio de GitHub del SDK. Busca métodos y archivos de modelos.

Opción 2: Solicitudes HTTP con curl o una biblioteca de solicitudes

¿Qué sucede si no quieres escribir una secuencia de comandos ni pasar meses o años aprendiendo un nuevo lenguaje de programación? En ese caso, puedes usar curl para realizar solicitudes HTTP y usar la API de Looker.

Una solicitud HTTP envía un mensaje a un destino, que puede ser un servidor, un teléfono o incluso tu smart TV. Existen varios tipos de solicitudes HTTP. La forma en que uses estas solicitudes con la API de Looker depende de la naturaleza de el método que pases como parte de la llamada a la API. Algunos métodos te proporcionan datos, otros los envían a Looker, otros los actualizan y otros los borran o quitan de Looker.

Acción Método
Crear POST
Leer GET
Actualizar PUT
Borrar DELETE

Comencemos a rizar. Para obtener información general, Zendesk tiene un excelente instructivo: Cómo instalar y usar cURL.

Para comenzar a realizar llamadas HTTP a la API de Looker, lo primero que debes hacer es llamar al extremo login de la API de Looker con tu ID de cliente y secreto de cliente. Esto crea un token de acceso. Luego, tomas este token de acceso y lo pasas con cada llamada. El token de acceso garantiza que la llamada provenga de un usuario autorizado.

En esta página, se usan algunas notaciones para indicar dónde debes reemplazar el texto de la muestra de código por tu información. Las URLs de instancias alojadas en Looker tienen el formato https://<hostname>.<subdomain>.<domain>.com. Cuando veas esta notación en los ejemplos de esta página, reemplaza la sección <hostname>.<subdomain>.<domain>.com por la URL de tu instancia de Looker. Además, usamos la notación <value> para indicar dónde debes ingresar el valor adecuado, reemplazando el <value> en la muestra de código. Por ejemplo, en el siguiente código, donde se muestra client_id=<value>&client_secret=<value>, reemplaza el primer <value> por tu client_id y el segundo <value> por tu client_secret.

Este es el comando curl para obtener el token de acceso: 

  curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login

A continuación, se muestra la respuesta: 

  {"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}

Recibir el token te indica que Looker reconoce tus credenciales de la API. El token se muestra con un valor expires_in, que indica durante cuánto tiempo es válido. Por lo general, es de alrededor de 60 minutos (3,600 segundos).

Ahora que tienes un token de acceso, puedes realizar las llamadas que quieras. Todos los extremos se enumeran por versión de la API en la documentación de la referencia de la API de Looker 4.0. Y recuerda que el sitio de la comunidad de Looker es un excelente recurso para hacerles preguntas a otros usuarios de Looker sobre cómo aprovechan la API, para aprender prácticas recomendadas o para compartir los éxitos que tuviste con la API con otros usuarios.

Supongamos que quieres crear un usuario nuevo. Para ello, sigue estos pasos:

  1. Escribe una solicitud de POST de curl que pase tu token para indicarle a Looker que tienes autorización.
  2. Incluye un cuerpo, en este caso con formato JSON, para indicarle a Looker qué atributos quieres que tenga tu usuario nuevo. (Hay algunos campos obligatorios para las llamadas a la API, por lo que debes consultar la documentación de la referencia de la API de Looker 4.0).
  3. Finaliza la notación de curl con el extremo que deseas usar, en este caso, users.

  curl -H "Authorization: token <value>
  " -H "Content-Type: application/json" -d "{\"first_name\": \"<value>\",\"last_name\": \"<value>\", \"email\":\"<value>\"}" https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/users

-H significa encabezado y -d significa datos. Para obtener más información sobre los comandos curl, consulta este gist de GitHub.

Acabas de crear un usuario con el nombre, el apellido y la dirección de correo electrónico que tienen los valores que ingresaste anteriormente.

¿Qué sucede si quieres escribir esto en una secuencia de comandos para no tener que escribir estos comandos cada vez que quieras completar este flujo de trabajo? Puedes usar un lenguaje de programación y una biblioteca como la biblioteca requests de Python.

Por ejemplo, esta es una secuencia de comandos que usa la biblioteca requests para obtener un aspecto con el ID de aspecto (el <value> en la llamada looks), aplicar un filtro nuevo y, luego, descargar los resultados como un archivo CSV: 

  import requests
  ID = '<value>'
  SECRET = '<value>'
  PARAMS = {'client_id':<value>,
            'client_secret': <value>}
  URL = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/login"
  r = requests.post(url = <value>, params = <value>, verify=False)
  data = r.json()
  token = data['access_token']
  print(token)
  headers = {'Authorization': "Bearer " + token}
  print(headers)
  look_url = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/looks/<value>"
  look = requests.get(look_url, headers=headers, verify=False)
  json = look.json()
  query = json['query']
  ### ADD MODEL HERE
  ### ADD FILTER
  body = {
      "model":"<value>",
      "view":query['view'],
      "fields":query['fields'],
      "filters":{<value>}
  }
  print(body)
  run_inline = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/queries/run/csv"
  run_query = requests.post(run_inline, headers = headers, json=body, verify=False)
  print(run_query._content)
  print(run_query.url)

Opción 3: Herramientas de desarrollo de software

Las herramientas como Postman o Paw permiten a los usuarios interactuar con los extremos de la API o aprovecharlos a través de una interfaz gráfica de usuario (GUI). El mismo proceso se aplica a una herramienta de desarrollo de software que a las solicitudes HTTP. El primer paso es acceder con tu secreto de cliente y tu ID de cliente. Luego, almacena el token de acceso como un token del portador para autorizar las llamadas a la API que siguen, como se muestra aquí en Postman.

La GUI de Postman, propagada con una URL POST de Looker, un secreto de cliente y un ID de cliente.

Postman y otras herramientas de desarrollo de software (como Paw) te permiten especificar la autorización, el cuerpo, los parámetros y los encabezados dentro de sus IU y, luego, generar la solicitud por ti. También ejecutarán el extremo cuando presiones enviar.

¡Adelante! (pero ten cuidado)

Ahora que puedes usar la API de Looker a través de un SDK, una solicitud HTTP y una herramienta de desarrollo de software, ¡adelante y pruébala! Sin embargo, ten en cuenta que, si bien el uso de la API puede ayudar a automatizar procesos, como crear o reasignar un programa después de que un usuario abandona tu empresa, el uso inadecuado de la API puede dañar una instancia.

Ten en cuenta lo siguiente:

  • Ten cuidado cuando edites permisos o borres usuarios, en especial de forma masiva. Es posible borrar o bloquear a muchos usuarios, incluidos los administradores, y acciones como esta no se pueden revertir fácilmente.
  • Las llamadas a la API aumentan el uso de las instancias, por lo que intenta programarlas para horas no pico para obtener un rendimiento óptimo.
  • Hay un límite de archivos abiertos en cada servidor de instancias, por lo que es posible que se produzca una falla en una instancia debido al uso irresponsable de la API.
  • Prueba los flujos de trabajo y las funciones a pequeña escala antes de agregarlos a producción.
  • Nunca compartas tus credenciales de API ni las dejes en un archivo al que otros usuarios puedan acceder.

Si tienes alguna pregunta o quieres compartir una idea interesante, consulta la Comunidad de Looker. No dudes en informarnos si hay algo que podamos mejorar o si tienes otros ejemplos que quieras agregar a nuestra documentación.