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 al instante sin tener que escribir ni una sola línea de código. Si instalaste la extensión del Explorador de APIs desde Looker Marketplace, puedes hacer clic en Explorador de APIs en el menú Aplicaciones de Looker para abrir el Explorador de APIs y ver la documentación actual de la API. Si no instalaste la extensión del Explorador de APIs, puedes hacerlo desde la sección Aplicaciones de Looker Marketplace.

Quizás, con el Explorador de APIs, descubriste el mejor flujo de trabajo para crear un Look de forma dinámica, actualizar la consulta subyacente y programarla para los diferentes interesados de tu empresa. Una pregunta siguiente 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 (SDKs) 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 elementos de información: tu autenticación personal de la API (en forma de un ID de cliente y un 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 para el usuario que te interesa y ve a Editar claves.
  • Si no eres administrador de Looker, habrás recibido tu ID de cliente y tu secreto del cliente de tu administrador de Looker.
Lo más importante que debes recordar sobre tu ID y secreto del cliente es que no debes 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 para obtener el número de puerto. Se puede establecer en el campo URL del host de la API del panel de administrador 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 clientes oficiales de la API de Looker en Python, Ruby, TypeScript y JavaScript, Swift, Kotlin y R. Puedes encontrar el código fuente y ejemplos en el repositorio de sdk-examples de GitHub 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 SDKs de Looker generalmente contienen APIs. Para tomar 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 se empaquetan de una manera que te permite interactuar sin problemas con Looker usando el lenguaje de programación que elijas. Las funciones te permiten realizar las siguientes tareas:

  • Envía datos a Looker
  • Obtén datos de Looker
  • Actualiza datos en Looker
  • Cómo borrar datos en Looker
En la siguiente sección, se analizarán los detalles más específicos de las diferencias entre estas acciones.

A continuación, se muestra 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 el usuario con sdk.update_user. Pasas el user_id para especificar qué usuario deseas 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 la tecla de comando presionada (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 verlos en el repositorio de GitHub del SDK. Busca los métodos y los archivos de modelos.

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

¿Qué sucede si no quieres escribir un código o pasar meses o años aprendiendo un nuevo lenguaje de programación? En ese caso, puedes usar curl para realizar solicitudes HTTP y utilizar 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 televisor inteligente. Existen varios tipos de solicitudes HTTP. La forma en que uses estas solicitudes con la API de Looker depende de la naturaleza del método que pases como parte de la llamada a la API. Algunos métodos te proporcionan datos, otros envían datos a Looker, otros actualizan datos y otros borran o quitan datos 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 tu secreto del 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 con tu información. Las URLs de instancias alojadas en Looker tienen el formato https://<hostname>.<subdomain>.<domain>.com, donde, en los ejemplos de esta página, debes reemplazar 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 el 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.

Aquí se muestra 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 indica que Looker reconoce tus credenciales de la API. El token se devuelve con un valor expires_in, que indica durante cuánto tiempo es válido el token. Suele ser de alrededor de 60 minutos (3,600 segundos).

Ahora que tienes un token de acceso, puedes realizar llamadas. 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, aprender las prácticas recomendadas o compartir los logros que obtuviste con la API con otros usuarios.

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

  1. Escribe una solicitud de POST curl que pase tu token para indicarle a Looker que estás autorizado.
  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

La -H significa encabezado y la -d significa datos. Para obtener más información sobre los comandos de 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, aquí tienes un script que usa la biblioteca requests para obtener una visualización con el ID de visualización (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

Herramientas como Postman o Paw permiten a los usuarios interactuar con los extremos de 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 del cliente y tu ID de cliente. Luego, almacena el token de acceso como un token de portador para autorizar las llamadas a la API posteriores, como se muestra aquí en Postman.

La GUI de Postman, completada con una URL de POST de Looker, secreto del 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 en 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 prueba todo! Sin embargo, ten en cuenta que, si bien usar la API puede ayudar a automatizar procesos como crear o reasignar un programa después de que un usuario deja tu empresa, el uso inadecuado de la API puede dañar una instancia.

Algunos aspectos generales que debes recordar:

  • Ten cuidado cuando edites permisos o borres usuarios, especialmente de forma masiva. Es posible borrar o bloquear a muchos usuarios, incluidos los administradores, y estas acciones no se pueden revertir fácilmente.
  • Las llamadas a la API aumentan el uso de la instancia, por lo que te recomendamos que las programes para horas no laborales y así obtener un rendimiento óptimo.
  • Existe un límite de archivos abiertos en cada servidor de instancias, por lo que es posible que se produzca una falla en una instancia por el uso irresponsable de la API.
  • Prueba flujos de trabajo y 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 puedan acceder otros usuarios.

Si tienes alguna pregunta o quieres compartir una idea interesante, consulta la Comunidad de Looker. No dudes en comunicarte con nosotros si crees que podemos mejorar algo o si quieres que agreguemos otros ejemplos a nuestra documentación.