Paso Solicitud REST

Descripción

El paso Solicitud REST llama a una API REST como un paso más de un flujo de trabajo. Es un único paso, al estilo de Postman, para todo el ciclo de «construir → enviar → inspeccionar»: elija un punto de conexión (escrito a mano o importado desde una colección de Postman, una especificación OpenAPI/Swagger o una captura HAR), defina los encabezados, los parámetros de consulta y un cuerpo, envíe una solicitud de prueba para ver la respuesta en vivo y guarde el paso.

Usted decide adónde va la respuesta. De forma predeterminada se analiza en una tabla. Como alternativa, el paso puede capturar la respuesta en variables del flujo de trabajo para que un paso posterior se bifurque según el código de estado o lea un valor del cuerpo.

Si cierra o recarga el navegador antes de guardar, el editor conserva un borrador local en ese navegador. Vuelva a abrir el mismo paso y elija Restaurar cuando se le solicite para recuperar la configuración de solicitud sin guardar.

Antes de empezar

Normalmente le convendrá una conexión de tipo REST, que contiene la URL base y la autenticación del servicio. El paso también puede llamar directamente a una URL completa sin una conexión. Consulte Conexiones REST.

Agregar un paso Solicitud REST

Abra el flujo de trabajo y agregue un paso donde lo desee.
Elija REST Request (unified) como tipo de paso (en los pasos REST). El editor se abre con una pestaña Solicitud, una pestaña Respuesta y una pestaña Selección de datos de la tabla.

Construir la solicitud

En la pestaña Solicitud:

Origen de puntos de conexión

Elija cómo proporcionará el punto de conexión y PlaidCloud rellenará la solicitud por usted:

Manual: escriba usted mismo el método y la URL.
Desde la definición de API de la conexión: use la definición OpenAPI/Swagger almacenada en la conexión que eligió, para no repetirla en cada paso. Consulte Reutilizar la definición de API de una conexión más abajo.
Colección de Postman (archivo) / Colección de Postman (URL): importe desde una colección de Postman.
OpenAPI / Swagger (URL) / OpenAPI / Swagger (archivo): importe desde una especificación de API.
Archivo HAR (archivo): importe una solicitud capturada del registro de red de su navegador.

Para un origen importado, elija Cargar catálogo para enumerar los puntos de conexión disponibles y luego elija uno en Punto de conexión. El paso rellena su método, URL, encabezados, parámetros de consulta y cuerpo, usando el valor de ejemplo o predeterminado de cada parámetro; un parámetro opcional que no tiene ninguno de los dos empieza desactivado. Si la solicitud ya contiene algo que usted introdujo, el paso le pregunta antes de reemplazarlo. Pulse Ctrl+Z (Cmd+Z en Mac) cuando no esté escribiendo en un campo, o elija Deshacer reemplazo, para recuperar la solicitud anterior.

Un catálogo grande es fácil de acotar: escriba en Filtrar por método, ruta o nombre… para enumerar solo los puntos de conexión coincidentes. El catálogo muestra cuántos puntos de conexión contiene (12 de 340 mientras está filtrado) y cuándo se cargó, y el paso indica cuándo una definición muy grande se recortó en su límite de vista previa.

Pegar una colección o una especificación en lugar de elegir un archivo

Los tres orígenes basados en archivos (colección de Postman, OpenAPI/Swagger y archivo HAR) ofrecen cada uno un botón Pegar… junto al selector de archivos. Úselo cuando tenga el contenido a mano pero no lo haya guardado en Document: pegue el JSON y elija Usar este. El catálogo se carga de inmediato, así que no hace falta hacer clic en Cargar catálogo después.

El contenido pegado se usa en lugar del selector de archivos y dura mientras el paso permanezca abierto: no se guarda con el paso, así que péguelo de nuevo si vuelve a abrir el paso y quiere recargar el catálogo a partir de él. Si elige un archivo para ese mismo origen, el archivo prevalece y el contenido pegado se descarta; el paso le avisa cuando esto ocurre.

También puede soltar un archivo .json sobre el selector de origen. El paso comprueba el contenido con el origen que eligió y le indica qué falla, por ejemplo una colección de Postman pegada donde se espera una especificación OpenAPI o un archivo que no es JSON, y cada origen tiene un vínculo How do I get a …? que explica cómo exportar una colección de Postman, una especificación OpenAPI o un archivo HAR.

Reutilizar la definición de API de una conexión

Los conectores creados para un servicio concreto ya conocen sus puntos de conexión. Las conexiones REST genéricas y de MuleSoft no, porque pueden apuntar a cualquier API, así que permiten adjuntar la definición de la API a la propia conexión.

Defínala una vez en la conexión (consulte Conexión REST genérica) y luego, en cualquier paso que use esa conexión:

Elija la conexión en Conexión.
Establezca Origen de puntos de conexión en Desde la definición de API de la conexión.
Elija Cargar catálogo y seleccione su punto de conexión.

Todos los pasos que comparten esa conexión ofrecen la misma lista de puntos de conexión, y actualizar la definición en la conexión los actualiza a todos.

Resumen de la conexión y entorno

Debajo del selector Conexión, una línea de resumen muestra lo que usará el paso: el tipo de autenticación, el host y cuántos encabezados predeterminados envía la conexión con cada solicitud. Elija el botón de actualizar junto al selector después de cambiar la conexión para recargar su autenticación, host y encabezados predeterminados sin volver a abrir el paso. Cuando la conexión define entornos, el selector Entorno elige contra cuál se ejecuta el paso.

Conexión, método y punto de conexión

Conexión: la conexión REST con la que autenticarse. Déjela sin definir para llamar directamente a una URL completa. Use el acceso directo de edición junto al selector para ver o editar la conexión seleccionada sin salir del editor de solicitudes.
Método: GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS.
Punto de conexión: la ruta (cuando hay una conexión definida) o una URL completa.

Encabezados, parámetros de consulta y cuerpo

Encabezados y Parámetros de consulta son tablas editables de filas de nombre/valor, cada una con un interruptor En y una descripción. Agregue filas con Agregar y quítelas con Quitar.
Cuerpo contiene la carga útil de la solicitud (JSON, formulario o texto sin formato) en un editor de código.

Dar formato a JSON aplica sangría al cuerpo, y Validar JSON lo comprueba e indica la línea y la columna de cualquier error. Ambos leen cada variable {{…}} como un valor, de modo que sus variables se mantienen exactamente como las escribió. Referencia de variables… enumera todas las variables que puede usar en la solicitud, e Insertar {{…}} coloca una variable en el cursor.

Mientras edita, el paso señala los problemas debajo de la solicitud:

Un nombre de encabezado o de parámetro de consulta que aparece dos veces, con lo que se perdería un valor.
Un nombre de encabezado que parece mal escrito, con una sugerencia Did you mean…, como Authorisation en lugar de Authorization.
Un secreto, como un valor de Authorization o X-API-Key, escrito en texto sin formato. Guárdelo en una variable de proyecto y escriba {{project_var.NAME}} para que el secreto no se almacene en el paso.
Un cuerpo JSON sin el encabezado Content-Type: application/json, que algunos servidores rechazan con HTTP 415.
Una URL con un esquema mal escrito, una barra doble en la ruta, una barra final o espacios sueltos.

Sustitución de variables

En cualquier parte del punto de conexión, los encabezados, los valores de consulta o el cuerpo puede inyectar una variable en tiempo de ejecución encerrando su nombre entre llaves dobles: {{name}}. También puede escribir {{var.name}} para una variable de ejecución del flujo de trabajo o {{project_var.name}} para una variable de proyecto; el prefijo es opcional y ambos resuelven el mismo nombre.

El editor resalta los tokens {{...}} detectados en el punto de conexión, en las tablas de encabezados y de consulta, y en el editor del cuerpo, para que las sustituciones sean fáciles de ver antes de probar o guardar.

Solo se sustituyen las llaves dobles, así que una { o } simple en un cuerpo JSON se deja exactamente como está: puede combinar variables con JSON libremente, por ejemplo {"id": "{{var.order_id}}", "qty": 1}. Un nombre de variable desconocido hace fallar el paso, de modo que un error tipográfico aflora de inmediato.

Cuando el flujo de trabajo lo inicia un sensor o un webhook, también hay cuatro variables de disparador disponibles: {{trigger_sensor_id}}, {{trigger_sensor_type}}, {{trigger_fired_at}} y {{trigger_payload_json}} (la carga entrante como cadena JSON; analícela en un paso posterior para acceder a los campos anidados). En una ejecución manual o programada, se resuelven como una cadena vacía.

Probar la solicitud

Enviar solicitud de prueba envía la solicitud con su configuración actual y muestra la respuesta en vivo en el mismo lugar, para que pueda confirmar que la llamada funciona antes de guardar. Pulse Ctrl+Enter (Cmd+Enter en Mac) para enviar desde cualquier punto del formulario. Una línea de estado muestra el estado HTTP y el tiempo de respuesta, y un temporizador cuenta mientras la solicitud está en curso. (Esto envía una sola solicitud; la paginación se ejecuta solo cuando se ejecuta el paso.)
Probar paginación sigue la paginación configurada e informa de cuántos registros se obtienen a lo largo de las páginas (hasta un límite de vista previa), para que pueda confirmar que el modo de paginación y sus parámetros y rutas se encadenan correctamente antes de una ejecución completa. Solo se lanzan las páginas necesarias para alcanzar el límite.
Copiar como curl copia al portapapeles un comando curl equivalente para compartirlo o depurar (con los secretos enmascarados).
Importar desde curl hace lo contrario: pegue un comando curl, por ejemplo el «Copy as cURL» de un navegador, y su método, URL, encabezados y cuerpo reemplazan la solicitud actual. La autenticación básica (-u) se convierte en un encabezado Authorization; las opciones no admitidas se notifican en lugar de descartarse en silencio. Use Deshacer reemplazo para restaurar los valores anteriores.

La respuesta se abre en un visor con las vistas Formateado y Compacto. Los últimos cinco resultados de prueba se conservan mientras el paso está abierto, y puede elegir uno para verlo de nuevo o volver a ejecutarlo. Cuando la respuesta contiene una lista de registros, Sugerir establece Ruta de elementos con la primera lista que encuentra.

El grupo Vista previa de la solicitud muestra la solicitud exactamente como la enviaría una ejecución, con las variables resueltas y los secretos enmascarados, sin enviar nada. Elija Actualizar vista previa después de editar.

Si cambia los campos de la solicitud saliente y guarda antes de una Enviar solicitud de prueba correcta, PlaidCloud pregunta ¿Guardar sin una prueba correcta? y usted elige Guardar de todos modos o vuelve atrás. En el modo de distribución, use Probar fila 1 para probar la primera fila del inductor antes de guardar.

Dirigir la respuesta

En la pestaña Respuesta, establezca el Destino de la respuesta:

Tabla (predeterminado)

La respuesta se analiza en la Tabla de destino, que es obligatoria en este modo. Elija una tabla existente o cree una desde el selector; no se ofrecen vistas. El grupo Paginación y análisis controla cómo:

Formato de fila: Objeto (el predeterminado) cuando cada registro es un objeto JSON, o Matriz cuando cada registro es una lista de valores. Matriz no está disponible con Una solicitud por fila de la tabla. Ruta de elementos indica dónde están los registros dentro de la respuesta.

Modo de paginación: Sin paginación (el predeterminado), Paginación por desplazamiento, Paginación por número de página, Paginación por URL de la página siguiente, Paginación por cursor o Paginación por encabezado Link (RFC 5988). Parámetros del modo y Rutas del modo indican qué parámetros y campos de la respuesta controlan la paginación, y solo están disponibles cuando se elige un modo de paginación. Al elegir un modo se rellenan ambos con sus valores predeterminados, que puede editar.

Modo	Parámetros del modo predeterminados	Rutas del modo predeterminadas	Cómo pagina
Desplazamiento	`{"offset": "offset", "limit": "limit"}`	`{"has_more": ["has_more"]}`	Envía los parámetros de consulta de desplazamiento y límite, y sigue leyendo mientras el `has_more` de la respuesta sea verdadero.
Número de página	`{"offset": "page"}`	`{"has_more": ["has_more"]}`	Envía el número de página en el parámetro `page` y no envía ningún límite.
URL de la página siguiente	`{}`	`{"next": ["next"]}`	Solicita la URL que se encuentra en la ruta `next` de cada respuesta. Una URL relativa se interpreta respecto de la página de la que procede.
Cursor	`{"cursor": "after"}`	`{"has_more": ["has_more"], "cursor": ["next_cursor"]}`	Envía el cursor de la respuesta anterior en el parámetro `after`. Agregue `"send_as": "header"` o `"send_as": "body_field"` a Parámetros del modo para enviarlo como encabezado de la solicitud o como campo del cuerpo. Para leer el cursor de un encabezado de respuesta, como el encabezado `x-ms-continuation` que envía Azure Cosmos DB, ponga `"token_header": "x-ms-continuation"` en Rutas del modo en lugar de `has_more` y `cursor`; la última página es la que no tiene el encabezado.
Encabezado Link	`{"rel": "next"}`	`{}`	Sigue la relación del encabezado de respuesta `Link` indicada por `rel`.

Desplazamiento y Número de página aceptan más claves en Parámetros del modo: start es el primer desplazamiento o número de página (0 de forma predeterminada), stop_on_empty se detiene en la primera página sin registros en la ruta de elementos, por lo que la respuesta no necesita un campo has_more, y send_limit indica si se envía el parámetro limit (verdadero de forma predeterminada para Desplazamiento, falso para Número de página).

Volcar JSON sin procesar en lugar de analizar filas: almacena la carga sin procesar en lugar de analizarla en columnas.
Reintentos (de 0 a 100) y Tiempo de espera (s) (de 1 a 600): cómo se comporta la solicitud ante un fallo y cuánto tiempo puede ejecutarse. Una ejecución espera hasta el tiempo de espera que usted establezca; Enviar solicitud de prueba, Probar fila 1 y Probar paginación esperan como máximo 300 s. Los reintentos cubren fallos de conexión, errores del servidor (5xx) y limitación de velocidad (HTTP 429) en métodos idempotentes (GET, HEAD, OPTIONS, DELETE). Un POST, PUT o PATCH se reintenta solo después de una respuesta de limitación de velocidad (HTTP 429), que indica que el servidor no hizo nada con él, y nunca después de un error del servidor, de modo que un cuerpo de solicitud no idempotente nunca se envía dos veces cuando el servidor pudo haber actuado; cuando la API devuelve un encabezado Retry-After, el paso espera el intervalo que se le pide (con un máximo de 2 minutos) antes de reintentar.

La pestaña Selección de datos de la tabla asigna los campos de la respuesta a las columnas de la tabla de destino. Inspeccionar origen → Populate rellena la asignación a partir de una respuesta en vivo: envía la solicitud del paso a través de su conexión, como lo haría una ejecución. Requiere una conexión y pregunta primero cuando el método es distinto de GET, HEAD u OPTIONS. Resumir y Distinto no se ofrecen aquí, porque el paso escribe la respuesta analizada directamente en la tabla de destino.

Variables del flujo de trabajo

Establezca Destino en Variables del flujo de trabajo e indique un Prefijo de variable (un nombre sencillo como my_call). El paso envía una solicitud y escribe cuatro variables del flujo de trabajo:

Variable	Contenido
`{prefix}_status`	Código de estado HTTP (por ejemplo, `200`).
`{prefix}_body`	Cuerpo de la respuesta como cadena (las respuestas JSON se almacenan como texto JSON).
`{prefix}_headers`	Encabezados de la respuesta como texto JSON.
`{prefix}_elapsed_ms`	Cuánto tardó la solicitud, en milisegundos.

Haga referencia a ellas más adelante como a cualquier variable del flujo de trabajo, por ejemplo {my_call_status}. Este es el elemento básico de los patrones del tipo «enviar una solicitud y luego bifurcar según el resultado».

Enviar una solicitud por cada fila de la tabla

De forma predeterminada, el paso envía una solicitud. Para llamar a una API una vez por cada fila de una tabla (por ejemplo, consultar cada id de cliente de una tabla, o enviar con POST cada fila como un registro), establezca Enviar (en la pestaña Solicitud) en Una solicitud por fila de la tabla. Esto muestra los campos de la tabla de inductores:

Tabla de inductores: elija la tabla cuyas filas generan las solicitudes. Elíjala entre las tablas del flujo de trabajo con el selector o escriba el nombre de una tabla. Las columnas de cada fila están disponibles como tokens {{row.column}}.
Filtro de inductor (opcional): una cláusula SQL WHERE que limita qué filas se usan.
Columnas clave (opcional): columnas del inductor, separadas por comas, que se trasladan a cada fila de salida para que los resultados se puedan unir de nuevo con el inductor.
Límite de filas y Simultaneidad: el número máximo de filas que se procesan y cuántas solicitudes se ejecutan a la vez.
Máx. solicitudes/s (opcional): limite la rapidez con que se inician las solicitudes en todos los procesos de trabajo para que una ráfaga no supere el límite de velocidad de la API (0 = sin límite). El valor puede ser una fracción: 0,5 inicia una solicitud cada dos segundos. Un valor superior a 1000 se ejecuta como 1000 con una advertencia. Es independiente de Simultaneidad: la simultaneidad limita cuántas se ejecutan a la vez, mientras que Máx. solicitudes/s regula la frecuencia con que se inicia una nueva.
Add Idempotency-Key header (opcional): para una única solicitud POST, PUT o PATCH por fila (Sin paginación), envía un encabezado Idempotency-Key estable derivado de cada fila, de modo que volver a ejecutar el paso no duplique registros en una API que admite idempotencia (la misma fila siempre envía la misma clave, así que la API elimina la repetición). Se ignora, con una advertencia, para GET/HEAD/DELETE o cuando hay un modo de paginación activo. Una solicitud que ya define su propio Idempotency-Key lo conserva.
Respuesta: cómo cada respuesta se convierte en filas. Registros analizados (el predeterminado) escribe cada registro de la respuesta como una fila. Texto (una fila por solicitud) escribe una fila por solicitud con las columnas DownloadData y DownloadHeaders; una solicitud fallida se descarta. Texto sin procesar, errores como filas también escribe una fila por solicitud, pero conserva el cuerpo exactamente como lo envió el servidor, agrega una columna DownloadStatus y conserva un error HTTP o de transporte como una fila con su cuerpo de error y su estado. Las credenciales se enmascaran en el cuerpo, los encabezados y el texto de error de cada fila sin procesar, y no se sigue una redirección a un origen distinto en una solicitud que lleva credenciales. La paginación no se aplica a los modos de texto. En Texto (una fila por solicitud), Keep error response (keep_error_response) escribe en la fila el cuerpo de una respuesta HTTP 400 o superior igual que en una respuesta correcta, en lugar de hacer fallar la fila, y Añadir DownloadStatus, DownloadReason y DownloadUrl a la salida (response_meta) agrega las columnas DownloadStatus, DownloadReason y DownloadUrl con el estado, el motivo y la URL final de la respuesta. Ambas están desactivadas de forma predeterminada. El formulario del paso tiene la opción Añadir DownloadStatus, DownloadReason y DownloadUrl a la salida; establezca keep_error_response con un asistente de IA o la API REST.
Continue on error: cuando está activada, una fila que falla se registra y el paso termina con una advertencia en lugar de abortar al primer fallo. El registro de ejecución nombra las primeras filas fallidas (por sus columnas clave) y el error de cada una, para que pueda saber qué filas fallaron y por qué.

Use tokens {{row.column}} en cualquier parte del punto de conexión, la consulta, los encabezados o el cuerpo para sustituir los valores de esa fila; por ejemplo, GET /customers/{{row.customer_id}}. Un valor en un parámetro de consulta se codifica como URL una sola vez, de modo que el servidor recibe A 1 y a/b tal como se escribieron. Las versiones anteriores lo codificaban dos veces, y el servidor recibía A%201 y a%2Fb. Si un paso POST, PUT o PATCH tiene activada Add Idempotency-Key header y un valor de fila que necesita codificación en su consulta, su clave cambia una vez tras la actualización porque la solicitud cambió. Una nueva ejecución que abarque la actualización puede enviar una solicitud repetida por cada una de esas filas. Los valores formados solo por letras, dígitos y -._~ no cambian. Los registros de la respuesta de cada fila se analizan en la tabla de destino (con las columnas clave antepuestas); con Volcar JSON sin procesar activado, se obtiene una fila por solicitud.

El menú Insertar {{row.column}} enumera las columnas de la tabla de inductores seleccionada, de modo que puede colocar un token del tipo {{row.customer_id}} en el punto de conexión o en el cuerpo (en el campo que editó por última vez) en lugar de escribir los nombres de columna a mano. Mientras edita, el formulario también enumera los tokens {{row.column}} que ha usado y resalta en rojo los que no son una columna de la tabla de inductores, de modo que los errores tipográficos se detectan antes de ejecutar el paso.

Probar fila 1 lee la primera fila del inductor (respetando el filtro de inductor), sustituye sus valores en el punto de conexión, la consulta, los encabezados y el cuerpo, y envía esa única solicitud, para que pueda confirmar que la distribución está bien configurada antes de ejecutarla sobre todas las filas. La respuesta se muestra en el mismo lugar que con Enviar solicitud de prueba, junto con los valores de la fila del inductor que se usaron. Preview Row 1 resuelve de forma similar los valores {{row.column}} de la primera fila del inductor y muestra la solicitud resuelta sin enviarla.

Ejecutar el paso

El paso Solicitud REST se ejecuta como cualquier otro, como parte de una ejecución completa o por sí solo (consulte Ejecutar un solo paso de un flujo de trabajo). En el modo de tabla escribe la respuesta analizada (o sin procesar) en la tabla de destino; en el modo de variables establece las cuatro variables para que las lean los pasos posteriores.

Pasos siguientes

Referencia del paso Solicitud REST: lista concisa de campos
Administrar variables del flujo de trabajo: lea y establezca variables entre pasos
Conexiones REST: configure conexiones de API autenticadas