Utilidades puente: API de llamada

La utilidad Llamar a API le permite gestionar las llamadas a API públicas que realice a través de sus flujos de trabajo de automatización en Bridge. Tiene dos componentes principales: 

• Perfiles: conservan información sobre las API del sistema a las que desea conectar sus flujos de trabajo. 

• El 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.

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

Consejo para constructores de puentes

Los perfiles simplifican los cambios en el flujo de trabajo en caso de que cambie información clave, como el token de autorización o la URL base. Una actualización del perfil garantiza que todos los módulos que llamen al perfil obtengan los datos más recientes para realizar la llamada.

Módulo Make API Call (Realizar llamada a API) 

Este es el único módulo de la utilidad y contiene los siguientes campos:

Endpoint

Este campo especifica la acción que desea realizar (por ejemplo, ordenar la hoja). En este valor, puede añadir cualquier referencia de datos de sus activadores Bridge. A continuación se ofrecen ejemplos de configuración para datos estáticos o dinámicos:

• Valor de ID estático - El formato de URL para este tipo de datos es el siguiente: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Especifique el ID de la hoja en esta URL, para que la llamada a la API siempre ordene esa hoja específica. 
• Referencia de datos de registro de ejecución dinámica - El formato de URL para estos datos es el siguiente: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Sin embargo, en lugar de añadir el ID de la hoja, debe añadir la referencia de los datos de la hoja del registro de ejecución. Esto resulta útil si su flujo de trabajo de Bridge se desencadena con cambios o incorpora datos de varias hojas. Cuando se utiliza este tipo de URL, la llamada a la API ordena la hoja específica a la que se hace referencia en esta URL.

Método

El método define el tipo de operaciones que desea realizar. Defina un método 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 puedes utilizar:

• GET: Introduzca datos en su flujo de trabajo de Bridge "obteniendo" una fila de una hoja.
• POST: Crea algo. Por ejemplo, agregue una fila a una hoja.
• PUT: Actualiza algo. Por ejemplo, actualice una fila de una hoja.
• BORRAR: Borrar algo. Por ejemplo, elimine una fila de una hoja.

Encabezados

Las cabeceras son los valores que necesita para la solicitud, y los pares clave-valor. Suelen utilizarse para gestionar la autorización (permisos). Por ejemplo, en las llamadas de Smartsheet, tendría un encabezado clave llamado Autorización con el valor establecido en Portador [Introduzca su token de API].

El Perfil puede configurar las cabeceras necesarias para cada llamada a un sistema. En su flujo de trabajo, el módulo Make API Call le permite configurar cabeceras adicionales para acciones específicas. 

Parámetros del formulario 

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

Un escenario de ejemplo sería aplicar la paginación con llamadas a Smartsheet para incluir algunos elementos en la respuesta. Por ejemplo, solo desea obtener la primera página de un informe con 20 000 filas.

Cuerpo de solicitud HTTP

Un organismo contiene los datos de la solicitud que debe enviar. Por lo general, está en formato JSON.

El envío de parámetros de formulario anula cualquier dato del cuerpo.

En una llamada a la API Sort Sheet, el cuerpo tendría este aspecto {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. El cuerpo de este ejemplo podría utilizar 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. 

Un cuerpo puede no ser necesario dependiendo del tipo de solicitud que estés haciendo. Por ejemplo, no se necesita un cuerpo para las llamadas GET .

Resultado

Si la API que responde devuelve un objeto JSON, se guarda en el registro de ejecución. Esto le permite hacer referencia a los datos devueltos más adelante en el flujo de trabajo.

Lo que necesita para comenzar

• Una hoja 
  • El ID de la hoja
  • Una columna que, cuando se modifica en las filas, activa el flujo de trabajo de Bridge en
• Bridge
  • Integración de Smartsheet
  • Desencadenador de flujo de trabajo de Bridge: Smartsheet - When Column Values are Changed
  • Módulo puente: Utilidades > Llamar a API > Hacer llamada a API
• A Smartsheet API Key.

Para crear este flujo de trabajo en Bridge, autentique la integración de Smartsheet para su espacio de trabajo de 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 facilita la navegación por el proceso de creación.

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

Extraiga todos los módulos que necesite 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 cuando haya terminado: 

Brandfolder Image

Configurar el desencadenador del flujo de trabajo

1. Seleccione el módulo Disparador.
2. En la sección Integraciones, seleccione la página Integraciones.

3. Busque Smartsheet en la lista de integraciones.

   Puede utilizar la opción Conectado situada bajo el logotipo de Bridge para obtener una lista únicamente de las integraciones autenticadas para ese espacio de trabajo.

4. Despliegue la fila Disparadores.
5. Para crear un nuevo disparador, seleccione Añadir a disparadores.
6. Complete los siguientes campos:
   • Nombre del activador: Cree una etiqueta personalizada para su activador.
   • ID de hoja: Pegue el ID de hoja de su hoja (la hoja que desea ordenar).
   • Tipo de Evento: Seleccione Cuando se cambian los valores de columna. 
   • Nombre o ID de columna: Escriba el nombre de la columna de Smartsheet a la que desea responder. Por ejemplo, si va a ordenar las filas de la hoja cada vez que cambie la prioridad, escriba el nombre de la columna de prioridad.
   • Seleccione Flujo de trabajo: Seleccione el nuevo flujo de trabajo que acaba de crear en la lista desplegable.
7. Seleccione Save (Guardar).
8. Copie el ID de la columna en la información del activador. Una vez guardado el desencadenador del flujo de trabajo, el ID de columna estará disponible en la información del desencadenador.
9. Pégalo en el Bloc de notas o en cualquier procesador de textos. Necesitará el ID de columna para un paso posterior. 
10. Vuelva al flujo de trabajo.

Obtener los detalles de la llamada a la API

Este flujo de trabajo cambia el valor de la columna de prioridad de su activador de hoja. Una vez que este flujo de trabajo detecta los desencadenadores, realiza las acciones necesarias en la misma hoja. Utilizamos las referencias de datos en tiempo de ejecución (Run Log) del activador para rellenar los módulos de Smartsheet.

Para este flujo de trabajo, debe realizar una llamada API al punto final Ordenar hoja de Smartsheet. 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 selecciona un perfil en el módulo Realizar llamada a la API, parte de la información necesaria para realizar la llamada a la API ya está configurada. 

1. Vaya a la pestaña Integraciones.
2. Seleccione la utilidad Llamar API.
3. Despliegue la sección Perfiles , en la pestaña Perfiles.

4. Seleccione Añadir 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.  La URL base de Smartsheet es https://api.smartsheet.com/2.0/
7. En Cabeceras secretas, añada cualquier cabecera que contenga tokens o información secreta, como tokens de API.
   • Por ejemplo, en las llamadas de Smartsheet, normalmente tiene un encabezado clave llamado Autorización con el valor establecido en Portador [Introduzca su token de API].
8. En Cabeceras, añada cualquier cabecera que deba incluirse en todas las llamadas a la API que realice con este perfil.
   • En este ejemplo, hemos utilizado Content-Type como cabecera con el valor application/json.
9. Seleccione Save (Guardar).
10. Vuelva al flujo de trabajo.

Consejo para constructores de puentes

La URL base es la parte de la URL de la API del sistema que siempre permanece igual, independientemente de lo que intente hacer en ese sistema. El punto final del módulo Make API Call le permite incluir los detalles específicos y las acciones que realiza con esa llamada a la API.

Ejemplo: Usamos la API de Smartsheet para ordenar una hoja. La URL base de nuestro perfil API de Smartsheet es https://api.smartsheet.com/2.0 y la acción específica que estamos realizando con el módulo es ordenar una hoja concreta, por lo que debemos poner sheets/sheet_id_or_data_reference_here/sort en el campo Endpoint 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 en el desplegable el perfil de API que desea utilizar .
2. En el campo Endpoint, incluya la parte del campo URL que no se añadió al campo Base URL 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:
   • Establezca el Método en POST.
   • En el campo HTTP Request Body, el cuerpo tendría este aspecto {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Parámetros del formulario (si se utiliza - no se utiliza 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 de prioridad es desplegable, las filas ordenadas están en orden ascendente o descendente (dependiendo de lo que haya definido en el cuerpo de la llamada a la API) de los valores tal y como aparecen 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 devuelva en forma de cadena, puede marcar la casilla Devolver respuesta sin procesar en Configuración adicional del módulo.
• Si debe incluir cabeceras adicionales para una llamada específica, cópielas en la sección Cabeceras de solicitud HTTP.

Opciones alternativas para este flujo de trabajo

• Disparar desde una hoja o columna diferente a la que desea ordenar. Para ello, deberá modificar los detalles de la llamada a la API para adaptarlos a la hoja y la columna que desee ordenar. 
• Añade una condición a tu ordenación. Una vez activado 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 realizado en la columna Prioridad (por ejemplo: si Prioridad es 0, mueva la fila fuera de la hoja y si Prioridad es 1, ordene la hoja).
• Utilizar un activador de programación. Cuando utilice este activador, no tendrá que responder a los cambios, ya que ordena la hoja una vez al día, a la semana o al mes.

Utilice 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 único lugar para realizar esos ajustes y hacer que se apliquen a los flujos de trabajo en el área de trabajo que utilizan ese perfil.
• Para cada API de sistema adicional a la que deba conectarse, puede configurar un nuevo Perfil único.
• El módulo Make API Call tiene éxito si recibe cualquier respuesta de la API de destino, incluso si recibe un error. Esto es útil en pasos posteriores para determinar rutas en su flujo de trabajo para respuestas inesperadas de la API (por ejemplo, si la llamada a la API devuelve un error, puede enviar una actualización a una fila diciendo que hubo un problema). Si prefiere que el flujo de trabajo se detenga si la API devuelve un error, puede marcar la casilla en la sección Configuración adicional del módulo.