Configurar la herramienta Call API

Esta configuración requiere conocimientos de API y programación.

La herramienta Call API le permite administrar las llamadas públicas a la API que realiza en los flujos de trabajo de automatización en Bridge. Tiene dos componentes principales: 

• Profiles: Conserva información sobre las API del sistema con las que desea conectar sus flujos de trabajo. 

• Módulo Make API Call: Utiliza datos de perfil y detalles específicos que usted proporciona para realizar una llamada a una API del sistema.

   

Consejo sobre Bridge Builder

Los perfiles también facilitan el cambio de flujos de trabajo mediante el uso de ese perfil en caso de que cambie información clave, como el token de autorización o la URL base. Una actualización del perfil garantizará que todos los módulos que llamen al perfil obtengan los datos más recientes para realizar la llamada.

Campos de llamada a la API

Antes de comenzar, repasemos algunos detalles terminológicos sobre el uso de las API.

URL base

Este campo está incluido en el perfil y es la parte de la URL de la API que siempre permanece igual. Para Smartsheet, debe usar la URL base: https://api.smartsheet.com/2.0/.

Endpoint

Este campo está incluido en el módulo Make API Call y especifica la acción que desea realizar (por ejemplo, ordenar la hoja). En este valor, puede agregar las referencias de datos que necesite de los desencadenadores de Bridge.

A continuación, le mostramos ejemplos de cómo configurar datos estáticos o dinámicos:

• Static ID value: El formato de URL para este tipo de datos es el siguiente: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Debe especificar el ID de la hoja en esta URL, para que la llamada a la API siempre ordene esa hoja específica. 
• Referencia de datos dinámica de Run Log: El formato de URL de estos datos es similar al del valor de ID estático: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Sin embargo, en lugar de agregar el ID de la hoja, deberá agregar la referencia de datos de la hoja desde el Run Log del flujo de trabajo de Bridge. Esto resulta útil si su flujo de trabajo de Bridge se desencadena con cambios o incorpora datos de varias hojas. Cuando utiliza este tipo de URL, la llamada a la API ordenará la hoja específica a la que se hace referencia en esta URL.

Método

El método define el tipo de operaciones que está intentando realizar. Podrá configurarlo para cada llamada a la API en el módulo Make API Call. La mayoría de las API describen el método necesario para un extremo de API determinado. Por ejemplo, con Smartsheet, estos son los métodos que utilizará:

• GET: Incorpore datos al flujo de trabajo de Bridge obteniendo una fila de una hoja.
• POST: Cree un elemento. Por ejemplo, agregue una fila a una hoja.
• PUT: Actualice un elemento. Por ejemplo, actualice una fila de una hoja.
• DELETE: Elimine un elemento. Por ejemplo, elimine una fila de una hoja.

Headers

Los encabezados son los valores que necesita para la solicitud y los pares clave-valor. Por lo general, se utilizan para gestionar la autorización (permisos). Por ejemplo, en las llamadas a Smartsheet, tendrá un encabezado clave llamado Authorization con el valor establecido en bearer [introduzca el token de la API].

Los encabezados necesarios para cada llamada a un sistema pueden configurarse en el perfil. Pueden configurarse encabezados adicionales para acciones específicas en el módulo Make API Call en su flujo de trabajo. 
 

Form Parameters 

Los parámetros de formulario también se conocen como parámetros de consulta o argumentos. Son elementos adicionales que puede definir en la solicitud. Debe establecerlos en el módulo Make API Call.

Un caso de ejemplo sería aplicar la paginación con llamadas a Smartsheet para que solo se incluya una cierta cantidad de elementos en la respuesta. Por ejemplo, solo desea obtener la primera página de un informe con 20 000 filas.
 

Body

El cuerpo de la solicitud contiene los detalles relevantes que debe enviar. Por lo general, está en formato JSON.

Al enviar parámetros de formulario, se anularán los datos del cuerpo.

En una llamada a la API de ordenación de hojas, el cuerpo sería de la siguiente manera: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. El cuerpo del ejemplo anterior podría usar cualquiera de estos tipos de valores:

• Un valor estático para una columna específica de una hoja.
• Una referencia de datos dinámica del Registro de ejecución en la que se muestra el ID de la columna. 

Según el tipo de solicitud que realice, es posible que no necesite incluir un cuerpo. Por ejemplo, no necesitará un cuerpo para las llamadas GET.
 

Datos arrojados

Si la API que responde devuelve un objeto JSON, se guardará en el RUn Log. Esto le permite hacer referencia a los datos arrojados en partes posteriores del flujo de trabajo.

Ahora, conoce los campos que encontrará cuando configure los módulos Profiles y Make API Call. Siga leyendo para obtener más información sobre cómo configurar y usar esta opción.

Lo que necesita para comenzar

• Una hoja 
  • El ID de la hoja
  • Una columna en la que desee desencadenar su flujo de trabajo de Bridge cuando esta se modifique en sus filas
• Bridge
  • Integración de Smartsheet
  • Desencadenador de flujo de trabajo de Bridge: Smartsheet - When Column Values are Changed
  • Módulos de flujo de trabajo de Bridge: Make API Call
• Una clave de API de Smartsheet Aprenda a generar una clave de API para Smartsheet. 

Introducción

Para crear este flujo de trabajo en Bridge, autentique la integración de Smartsheet para su espacio de trabajo de Bridge. Lea los pasos sobre cómo configurar la integración de Smartsheet para Bridge. 

Al crear un flujo de trabajo, mantenga la hoja, la documentación de la API de Smartsheet y el flujo de trabajo de Bridge abiertos en tres pestañas separadas. Esto facilitará la navegación por el proceso de creación.

Paso 1: Crear el modelo básico de flujo de trabajo

Antes que nada, extraiga todos los módulos que necesita para el flujo de trabajo. 

1. Cree un nuevo flujo de trabajo en Bridge. 
2. En el generador de flujo de trabajo, utilice el panel para agregar el módulo Make API Call.
3. Guarde el flujo de trabajo.

Esto es lo que debería ver en su flujo de trabajo al finalizar: 

Brandfolder Image

Configurar el desencadenador del flujo de trabajo

Después de crear el modelo básico de flujo de trabajo, configure su desencadenador.

1. Seleccione el módulo Trigger.
2. Para abrir el panel Integration en una nueva pestaña, en la sección Integrations , seleccione Integrations Page.

3. Busque Smartsheet en la lista de integraciones.
    

   Puede usar la opción Conectado que se encuentra debajo del logotipo de Bridge para obtener una lista de las integraciones autenticadas para ese espacio de trabajo.

4. Expanda la fila Desencadenadores.
5. Para crear un nuevo desencadenador, seleccione el ícono más.
6. Complete los siguientes campos:
   • Trigger Name: Cree una etiqueta personalizada para su desencadenador.
   • Sheet ID: Pegue el ID de la hoja correspondiente a su hoja (la hoja que desea ordenar).
   • Event Type: Seleccione When Column Values are Changed. 
   • Column Name or ID: Escriba el nombre de la columna de Smartsheet a la que desea responder. Por ejemplo, si quiere ordenar las filas de la hoja cada vez que se modifique la prioridad, escriba el nombre de la columna Prioridad.
   • Select Workflow: Seleccione el nuevo flujo de trabajo que acaba de crear de la lista desplegable.
7. Seleccione Save.
8. En la información de Trigger, copie el ID de la columna.
   • El ID de la columna estará disponible en la información del desencadenador una vez que guarde el desencadenador del flujo de trabajo.
9. Péguelo en un bloc de notas o en cualquier procesador de texto. Necesitará el ID de la columna para un paso posterior. 

10. Vuelva al flujo de trabajo.
     

    Si desea regresar a la pestaña original, actualice la página para ver el desencadenador.

Obtener los detalles de la llamada a la API

Los cambios de valor en la columna Prioridad de su hoja se desencadenan en este flujo de trabajo. Una vez que este flujo de trabajo detecta los desencadenadores, realiza las acciones necesarias en la misma hoja. Así que, para completar los módulos de Smartsheet, usaremos las referencias de datos de tiempo de ejecución (Run Log) del desencadenador.

Para este flujo de trabajo, realizará una llamada a la API al extremo Smartsheet Sort Sheet. Utilice la documentación de la API de Smartsheet para cambiar el ejemplo a cURL.

Paso 2: Configurar su primer perfil

Los perfiles son una forma de guardar información clave para las API del sistema con las que desea conectar sus flujos de trabajo. Cuando seleccione un perfil en el módulo Make API Call, parte de la información necesaria para realizar la llamada a la API ya estará configurada. 

1. Inicie sesión en su cuenta de Bridge.
2. Vaya a la página Integraciones en Bridge.
3. Seleccione la utilidad Call API.

4. Seleccione Agregar a perfiles.

   Brandfolder Image

   
5. Asigne un nombre a su perfil. Cada nombre de perfil debe ser único.
6. Agregue la URL base para la API del sistema con la que desea conectarse.
   • En este ejemplo, la URL base para Smartsheet: https://api.smartsheet.com/2.0/.
7. Debajo de Encabezados secretos, agregue cualquier encabezado que contenga tokens o información secreta (por ejemplo, tokens de API).
   • Por ejemplo, en las llamadas a Smartsheet, normalmente tendrá un encabezado clave llamado Authorization con el valor establecido en bearer [introduzca el token de la API].
8. Debajo de Encabezados, agregue cualquier encabezado que deba incluirse en todas las llamadas a la API que realice con este perfil.
   • En este ejemplo, hemos utilizado Content-Type como encabezado con el valor aplication/json.
9. Guarde el perfil.

10. Vuelva al flujo de trabajo.

     

Consejo sobre Bridge Builder

La URL base es la parte de la URL de la API del sistema que siempre será la misma, independientemente de lo que esté tratando de hacer en ese sistema. El extremo en el módulo Make API Call es para incluir los detalles específicos y la acción que debe realizar con esa llamada a la API.

Ejemplo: Usamos la API de Smartsheet para ordenar una hoja. La URL base de nuestro perfil de API de Smartsheet es https://api.smartsheet.com/2.0 y la acción específica que estamos haciendo con el módulo es ordenar una hoja específica, así que ingresaremos sheets/sheet_id_or_data_reference_here/sort en el campo Extremo del módulo.

Paso 3: Configurar el módulo Make API Call en su flujo de trabajo

1. En el módulo Make API Call, seleccione su perfil deseado en el menú desplegable.
2. En el campo Extremo, incluya la parte del campo URL que no se agregó a la URL base en el perfil.
   • En este ejemplo, hemos utilizado sheets/sheet_id_or_data_reference_here/sort.
3. Complete los siguientes campos. Tenga en cuenta que puede no usar todos:
   • Defina el Método como POST.
   • En el campo Cuerpo de solicitud HTTP, un cuerpo se vería así: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Parámetros de formulario (si se usan; no se utilizan para este flujo de trabajo)

4. Guarde los cambios.

   Brandfolder Image

   

   
    

Paso 4: Probar el flujo de trabajo

1. Abra su hoja. 
2. Cambie un valor en la columna Prioridad. 
3. Guarde la hoja. 

Si su columna Prioridad incluye una lista desplegable, las filas ordenadas aparecerán de forma ascendente o descendente (según lo que haya definido en el cuerpo de la llamada a la API) de los valores, tal como se muestran en la configuración de la columna. 

Configuraciones adicionales para el módulo

• El módulo Make API Call muestra todas las llamadas a la API como un objeto JSON. Si necesita que la respuesta se muestre como una cadena, puede marcar la casilla de verificación Devolver respuesta sin procesar en el Configuración adicional en el módulo.
• Si necesita incluir encabezados adicionales para una llamada específica, cópielos en la sección Encabezados de solicitud HTTP.

Opciones alternativas para este flujo de trabajo

Le mostramos algunas ideas para personalizar este flujo de trabajo:

• Active el desencadenador desde una hoja o columna diferente a la que desea ordenar. Deberá cambiar los detalles de llamada a la API para que reflejen la hoja y la columna que desea ordenar. 
• Agregue una condición a la ordenación. Después de que se desencadene el flujo de trabajo, utilice un módulo de unión para evaluar el valor de la columna y realizar diferentes acciones en función del cambio introducido en la columna Prioridad (p. ej., si la Prioridad es 0, mueva la fila fuera de la hoja; si la Prioridad es 1, ordene la hoja).
• Utilice un desencadenador de cronograma. Cuando utilice este desencadenador, no tendrá que responder a los cambios, ya que ordenará la hoja una vez al día, a la semana o al mes.

Usar las herramientas Call API en todas sus soluciones

• Los perfiles se aplican al espacio de trabajo, por lo que todos los flujos de trabajo de su espacio de trabajo pueden usar el mismo perfil en cualquier módulo Make API Call que se utilice. Cuando los detalles del perfil deben cambiar porque los permisos de un usuario han cambiado o la API del sistema realiza cambios, hay un solo lugar para hacer esos ajustes y hacer que se apliquen a los flujos de trabajo en el espacio de trabajo que utilizan ese perfil.
• Para cada API adicional del sistema a la que necesita conectarse, puede configurar un nuevo perfil único siguiendo la primera parte de la guía.