Usar una API REST en Operaciones

Introducción

Aunque cada API REST se adhiere a las mismas restricciones arquitectónicas, no todas están diseñadas de la misma manera para cada método HTTP. Por ejemplo, para un POST, una API puede tomar una estructura de solicitud y proporcionar una estructura de respuesta, mientras que otra API puede tomar una estructura de solicitud pero responder solo con un código de estado. Para una ELIMINACIÓN, una API puede requerir que la solicitud se proporcione en la URL en lugar de una estructura.

Debido a que cada método puede ser diferente, es importante haber consultado la documentación de la API específica (Investigando una API REST) y haber validado la solicitud y la respuesta con una herramienta independiente (Validación de una API REST). Por lo tanto, en lugar de proporcionar patrones para cada método, que pueden variar según la API, los patrones que se presentan a continuación se basan en si se proporcionan estructuras de solicitud o respuesta.

En esta página, veremos estos patrones de diseño y veremos cómo modelarlos en Design Studio:

Solo una estructura de respuesta
Estructuras de solicitud y respuesta
Solo una estructura de solicitud
Ni una Solicitud ni una Estructura de Respuesta

Los patrones continúan con el Tutorial API REST mediante API REST de Atlassian Jira Cloud v2 como ejemplo. Sin embargo, no es necesario completar los pasos anteriores del tutorial para usar estos patrones, que son aplicables a todas las API REST en general.

Una Estructura de Respuesta Solamente

Este patrón se aplica a los métodos en los que necesita proporcionar solo una estructura de respuesta y ninguna estructura de solicitud. Este suele ser el caso con los métodos GET, ya que normalmente solo solicita que se envíen datos desde la API, en lugar de proporcionar datos a la API. Todavía está enviando una solicitud a la API, pero su solicitud no está en forma de datos estructurados. La solicitud se realiza simplemente utilizando la URL de solicitud y cualquier encabezado de solicitud u otras opciones configurables establecidas durante la configuración de la fuente HTTP.

En este ejemplo del patrón, hacemos una solicitud utilizando un método GET ("GET Jira Issue"), pasamos los datos recibidos a través de la transformación ("Issue") y escribimos los datos devueltos por la API a un objetivo de variable global ("Respuesta"), que luego escribimos en el registro de operación usando un secuencia de comandos ("Registro de depuración") para informar sobre los datos devueltos.

Una estructura de respuesta solamente 1

Tenga en cuenta que cualquier otro objetivo podría usarse, y que el método y lo que devuelve depende de la API específica. Este patrón se puede modificar dependiendo de cómo le gustaría usar los datos de respuesta devueltos por la API.

Cree una operación de transformación utilizando una fuente HTTP con el Verbo HTTP y la URL para la solicitud de API específica.
En la operación, haga doble clic en el marcador de posición de destino y cree un destino de variable global con una variable llamada "Respuesta". (Cualquier tipo de objetivo podría usarse aquí).
En la operación, haga clic con el botón derecho en el objetivo de la variable global que acaba de agregar y seleccione Insertar después de esto > Secuencia de Comandos. Luego, haga doble clic en el secuencia de comandos y cree un nuevo Jitterbit Script donde escribiremos el valor de la variable global en el registro de operación:
```
<trans>
WriteToOperationLog($Response)
</trans>
```
En la operación, haga doble clic en el marcador de posición de la transformación y cree una nueva transformación. Aquí es donde proporcionaremos la estructura de respuesta de muestra para que Harmony sepa cómo procesar los datos.
1. En el paso Nombre del asistente de transformación, seleccione el formato de origen y destino de los datos. En el ejemplo, seleccionamos "JSON" para ambos, ya que la API de Jira brinda respuestas en este formato.
2. En el paso Fuente, seleccione la opción para crear una nueva estructura a partir de un archivo de muestra. En la siguiente pantalla, proporcione el archivo de respuesta de muestra que guardó al validar la API para este tipo de solicitud, luego genere el XSD a partir de ese archivo de muestra. En nuestro ejemplo, generamos el XSD a partir de la Jira_GET_GetIssue_Response.json respuesta de muestra que habíamos guardado anteriormente (ver Validación de una API REST).
3. En el paso Objetivo, seleccione el mismo esquema que acaba de generar, ya que en este caso la estructura de origen y destino serán idénticas.
En la pantalla de asignación de transformación, asigne automáticamente los campos de origen y destino, que deben coincidir exactamente ya que utilizan la misma estructura. Esto pasará por todos los campos devueltos por la API.

Si desea transformar alguno de los datos, puede hacerlo en este momento. Sin embargo, es típico simplemente pasar los datos obtenidos de un GET para que pueda ver lo que devuelve la API y posiblemente usar esos datos en una operación posterior. También puede asignar directamente a otros extremos configurados.
Cuando esté listo, desplegar y ejecute la operación. Haga doble clic en los íconos de estado en el monitor de operación para ver información sobre el estado de la operación. Si la operación se completó correctamente, verá este estado, así como la respuesta de la API que configuró para escribir en el registro de operación.

Dado que eliminamos campos de nuestra estructura de muestra antes de generar el XSD para la transformación, el estado muestra una finalización exitosa con advertencias. Las advertencias se incluyen más abajo en el mensaje de registro.

También puede hacer clic derecho en la operación y seleccionar Registro de operación para ver las advertencias directamente en el registro de operación:

Estructuras de Solicitud y Respuesta

Este patrón se aplica a los métodos en los que proporciona estructuras de solicitud y respuesta. Este suele ser el caso con los métodos POST, en los que solicita que se creen datos y luego recibe información sobre lo que se creó. La respuesta de la API se puede usar de cualquier manera, pero a menudo se usa el nuevo ID de objeto en una operación posterior.

Muchas API REST tienen métodos POST o PUT que le permiten crear solo un registro a la vez. En esa situación, si tiene una fuente con varios registros, llama a un método para crear o actualizar un registro a la vez. Por este motivo, este patrón no utiliza una fuente de elemento de proyecto como suele verse en las operaciones de Harmony. En su lugar, usamos una secuencia de comandos para recorrer múltiples registros, introduciéndolos en la misma operación para que se procesen uno a la vez.

En este ejemplo del patrón, recorremos varios registros de origen para realizar una solicitud para cada uno mediante un método POST y escribimos los datos devueltos por la API en un objetivo de variable global, que luego escribimos en el registro de operación para analizar la respuesta e informar sobre los datos devueltos. Para ello, encadenamos tres operaciones, que se tratan en detalle en los siguientes subapartados:

Crear un bucle de registros. En la primera operación, "1.0 Bucle para enviar", usamos un secuencia de comandos ("Crear datos de muestra") para crear una variable global que luego usamos como fuente ("Fuente CSV") para la transformación ("Bucle"), donde escribimos valores de campo para cada registro de origen en variables globales.
Enviar la Solicitud. En la segunda operación, "2.0 Create Jira Issue", luego usamos esas variables globales en nuestra transformación ("Create Issue") para escribir en nuestro objetivo ("POST Jira Issue") donde guardamos la respuesta de la API en un variable global.
Analizar la respuesta. En la tercera operación, "Respuesta de análisis 3.0", usamos esa respuesta en una fuente de variable global ("Respuesta") y en nuestra transformación ("Respuesta de creación de análisis de análisis") escribimos esos valores en el registro de operación.

Solicitud y Respuesta 1

Tenga en cuenta que cualquier otro objetivo podría usarse, y que el método y lo que devuelve depende de la API específica. Este patrón se puede modificar dependiendo de cómo le gustaría proporcionar datos y utilizar los datos de respuesta devueltos por la API.

Crear un Bucle de Registros

Cree una operación de transformación usando la fuente de datos que desea usar en su llamada a la API. A los efectos de este ejemplo, creamos un secuencia de comandos que define la variable global source.csv con varios registros para usar y escribió la variable global en una fuente de variable global. Para una implementación real, este tipo de datos probablemente provendría de otro extremo conectado; se puede utilizar cualquier fuente.
```
<trans>
$source.csv = 'TEST,Research My API,Become familiar with my REST API endpoint.,High,Task
TEST,Add Missing Fields,Iterate using Postman to make sure all desired fields are generated.,Highest,Bug
TEST,Build Operations in Jitterbit,Use Jitterbit to design the REST API integration.,Medium,Task'
</trans>
```
Haga doble clic en el marcador de posición de la transformación y cree una nueva transformación. Aquí es donde crearemos el bucle para procesar cada registro de origen individualmente.
1. En el paso Nombre del asistente de transformación, seleccione el formato adecuado para su origen y destino. En este ejemplo, seleccionamos "Texto" para ambos, pero puede usar cualquier formato.
2. En el paso Origen, especifica la estructura que se utiliza para sus datos de origen. Como seleccionamos un formato de texto, creamos un nuevo formato de archivo definición para que coincida con la estructura de nuestros datos. Ya sea que use un formato de archivo u otra estructura, debe coincidir con la estructura de sus datos de origen.
3. En el paso Objetivo es donde crearemos el bucle. Para esto, debe tener un campo que se usará para recorrer cada registro. Como usamos un formato de texto, creamos una nueva definición de formato de archivo con un solo campo.
En el mapeo de transformación, agregue un secuencia de comandos de transformación en el Loop y defina cada uno de los campos de origen como variables globales. Posteriormente agregaremos un RunOperation() función en el secuencia de comandos para iniciar la siguiente operación utilizando los datos de cada registro.
```
<trans>
$jira.key = key;
$jira.summary = summary;
$jira.description = description;
$jira.priority = priority;
$jira.issuetype = issuetype;
</trans>
```

Enviar la Solicitud

Cree una segunda operación de transformación utilizando un objetivo HTTP con el Verbo HTTP y la URL para la solicitud de API específica. Si desea utilizar la respuesta recibida de la API, en Opciones utilice el campo "Escribir respuesta a (opcional)" para establecer el objetivo de su elección. En este ejemplo, escribimos la respuesta devuelta a un destino de variable global con una variable llamada "Respuesta".
En la segunda operación, haga clic con el botón derecho en el marcador de posición de la fuente y seleccione Eliminar del gráfico, ya que vamos a usar una secuencia de comandos para insertar registros como fuente en lugar de definir una fuente de elemento de proyecto para usar en la transformación
En la segunda operación, haga doble clic en el marcador de posición de la transformación y cree una nueva transformación. Aquí es donde proporcionaremos las estructuras de solicitud y respuesta de muestra para que Harmony sepa cómo procesar los datos.
1. En el paso Nombre del asistente de transformación, seleccione "Ninguno" para la fuente de datos, ya que no estamos usando una fuente tradicional para la operación. Seleccione "JSON" para el destino de los datos, ya que Jira acepta solicitudes en este formato.
2. En el paso Objetivo, seleccione la opción para crear una nueva estructura a partir de un archivo de muestra. En la siguiente pantalla, proporcione el archivo de solicitud de muestra que guardó al validar la API para este tipo de solicitud, luego genere el XSD a partir de ese archivo de muestra. En nuestro ejemplo, generamos el XSD a partir de la Jira_POST_CreateIssue_Request.json solicitud de muestra que habíamos guardado anteriormente (ver Validación de una API REST).

En la pantalla de asignación de transformación, no debería ver una estructura en el lado de la fuente. En el lado de destino, crearemos un secuencia de comandos de transformación en cada campo al que queramos asignar que proporcione datos para cada registro. En este ejemplo, usamos las variables globales que definimos previamente a partir de nuestros datos de origen.

Campo objetivo	Secuencia de Comandos de mapeo
`json$fields$project$key$`	`<trans>` `$jira.key` `</trans>`
`json$fields$summary$`	`<trans>` `$jira.summary` `</trans>`
`json$fields$description$`	`<trans>` `$jira.description` `</trans>`
`json$fields$priority$name`	`<trans>` `$jira.priority` `</trans>`
`json$fields$issuetype$name`	`<trans>` `$jira.issuetype` `</trans>`

Enviar la Solicitud 1

Ahora que se creó la segunda operación, regrese al secuencia de comandos de transformación en el ciclo que se usa en la primera operación y agregue la función RunOperation() para ejecutar la segunda operación que acaba de crear. Esto hará que, a medida que la primera operación procese cada registro, la segunda operación se ejecute para cada registro, haciendo un bucle efectivo en todos los registros.
```
<trans>
$jira.key = key;
$jira.summary = summary;
$jira.description = description;
$jira.priority = priority;
$jira.issuetype = issuetype;
RunOperation("<TAG>Operations/POST/2.0 Create Jira Issue</TAG>");
</trans>
```
Cree una tercera operación que analice la respuesta de la API que se ejecuta cuando la segunda operación tiene éxito. Para hacerlo, haga clic con el botón derecho en el fondo de la segunda operación y seleccione En caso de éxito > Operación > Crear nueva operación y cree una nueva operación de transformación.
En la tercera operación, use como fuente donde haya especificado que la respuesta API se guardará durante el objetivo HTTP configuración; en el ejemplo, usamos una variable global. Para usar la misma variable global como fuente, en el árbol de elementos del proyecto, haga clic con el botón derecho en el destino de la variable global y seleccione Copiar a nueva fuente para crear una fuente de variable global usando la misma variable global ($Response) como fuente.

Analizar la Respuesta

En la tercera operación, utilice el destino al que le gustaría escribir la respuesta. Para el ejemplo, más adelante escribiremos la respuesta en el registro de operación en lugar de un objetivo de elemento de proyecto real. Haga clic con el botón derecho en el marcador de posición de destino y seleccione Eliminar del gráfico.
Haga doble clic en el marcador de posición de la transformación y cree una nueva transformación. Aquí es donde proporcionaremos las estructuras de solicitud y respuesta de muestra para que Harmony sepa cómo procesar los datos.
1. En el paso Nombre del asistente de transformación, seleccione "JSON" para la fuente de datos, ya que estamos usando los datos de respuesta de nuestra API, que viene en formato JSON. Para el ejemplo, seleccionamos "JSON" como el destino de los datos para escribir la respuesta usando la misma estructura, pero puede elegir cualquier tipo aquí dependiendo de cómo desee escribir los datos.
2. En el paso Fuente, seleccione la opción para crear una nueva estructura a partir de un archivo de muestra. En la siguiente pantalla, proporcione el archivo de respuesta de muestra que guardó al validar la API para este tipo de solicitud, luego genere el XSD a partir de ese archivo de muestra. En nuestro ejemplo, generamos el XSD a partir de la Jira_POST_CreateIssue_Response.json respuesta de muestra que habíamos guardado anteriormente (ver Validación de una API REST).
3. En el paso Objetivo, seleccione el mismo esquema que acaba de generar, ya que solo estamos pasando por la respuesta de la API.
En la pantalla de mapeo de transformación, mapee los campos que desea que se escriban. En el ejemplo, agregamos un secuencia de comandos de transformación en el objetivo id campo que escribe los valores devueltos en variables globales que luego se escriben en el registro de operación. También puede colocar un secuencia de comandos de transformación en cada campo de destino, pero debido a que solo se usan para escribir en el registro de operación, como atajo, los colocamos todos en el secuencia de comandos de un campo.
```
<trans>
$jira.id = json$id$;
$jira.key = json$key$;
$jira.link = json$self$;
WriteToOperationLog("Issue ID: " + $jira.id);
WriteToOperationLog("Issue Key: " + $jira.key);
WriteToOperationLog("Issue Link: " + $jira.link);
</trans>
```
Cuando esté listo, desplegar y ejecute la operación. Si la operación es exitosa, haga clic derecho en la tercera operación y seleccione Registro de operación para confirmar que los registros se escribieron en el registro de operación. Debido a que cada registro se procesó por separado, habrá una línea en el registro de operación para cada registro. También puede verificar el extremo para ver que se ha creado el nuevo registro o hacer un GET en el identificador del nuevo objeto.

Solo una Estructura de Solicitud

Este patrón se aplica a los métodos en los que proporciona una estructura de solicitud, pero la API REST no devuelve datos estructurados. Para las API que solo tienen una estructura de solicitud, esto no significa que la API no responda; significa que la respuesta de la API puede ser tan simple como un código de estado.

En este ejemplo del patrón, proporcionamos una fuente para la solicitud en una transformación ("Editar problema") y luego realizamos una solicitud usando un método PUT ("PUT Jira Issue") para actualizar y agregar varios campos en un solo registro. Al igual que con POST, puede ser común que una API específica permita la actualización de solo un registro a la vez. Para recorrer los datos, consulte la parte de bucle del patrón anterior para Estructuras de solicitud y respuesta.

Una estructura de solicitud solo 1

Si el código de estado está en el rango 200, Harmony lo informará como exitoso. Para otros códigos que indiquen errores, el código devuelto se informará en el registro de operación. Si recibe un error, también puede configurar cadenas de operación para que se ejecuten en caso de falla (por ejemplo, para enviar un mensaje de Slack o un correo que informe que la operación no tuvo éxito).

Cree una operación de transformación usando un objetivo HTTP con el Verbo HTTP y la URL para la solicitud de API específica.
En la operación, utilice una fuente apropiada para su caso de uso. En el ejemplo, como proporcionaremos los datos de origen en un secuencia de comandos, hacemos clic con el botón derecho en el marcador de posición de origen y seleccionamos Eliminar del gráfico.
En la operación, haga doble clic en el marcador de posición de la transformación y cree una nueva transformación. Aquí es donde proporcionaremos la estructura de solicitud de muestra.
1. En el paso Nombre del asistente de transformación, seleccione el formato de su fuente y destino de datos. En el ejemplo, seleccionamos "(Ninguno)" como fuente de datos, ya que no estamos usando una fuente tradicional para la operación. Seleccionamos "JSON" para el destino de los datos, ya que Jira acepta solicitudes en este formato. Si necesita realizar un bucle de varios registros de origen, consulte la parte de bucle del patrón anterior para Estructuras de solicitud y respuesta.
2. En el paso Objetivo, seleccione la opción para crear una nueva estructura a partir de un archivo de muestra. En la siguiente pantalla, proporcione el archivo de solicitud de muestra que guardó al validar la API para este tipo de solicitud, luego genere el XSD a partir de ese archivo de muestra. En nuestro ejemplo, generamos el XSD a partir de la Jira_PUT_EditIssue_Request.json solicitud de muestra que habíamos guardado anteriormente (ver Validación de una API REST).
En la pantalla de asignación de transformación, no debería ver una estructura en el lado de la fuente. En el lado de destino, crearemos un secuencia de comandos de transformación en cada campo al que queramos asignar que proporcione datos para cada campo. En este ejemplo, codificamos los valores de la actualización para agregar un comentario, cambiar la prioridad y agregar una etiqueta. Para esta solicitud, el ID del objeto se proporciona en la URL, por lo que no asignamos ninguna clave aquí. Para ver un ejemplo de mapeo usando variables, consulte el patrón anterior para Estructuras de solicitud y respuesta.
Cuando esté listo, desplegar y ejecute la operación. Haga doble clic en los íconos de estado en el monitor de operación para ver información sobre el estado de la operación. Si el código de estado está en el rango 200, Harmony informará que la operación se completó con éxito. También puede verificar su extremo o hacer otro GET para ver que se han realizado las actualizaciones.

Si hubo otros códigos de estado, encabezados de respuesta o cualquier mensaje de error devuelto por la API, se informará.

Ni una Solicitud Ni una Estructura de Respuesta

Este patrón se aplica a los métodos que no aceptan datos de entrada estructurados ni devuelven datos de salida estructurados. En tales casos, la solicitud generalmente se especifica completamente con la URL y los encabezados de la solicitud; la respuesta es normalmente un código de estado.

En este ejemplo del patrón, hacemos una solicitud utilizando un método DELETE, donde eliminamos los registros que se crearon y actualizaron en los patrones anteriores, utilizando el ID del objeto (clave de emisión de Jira). Para minimizar la cantidad de piezas requeridas, esta operación se realiza completamente dentro de un secuencia de comandos ("Eliminar problema"). Si bien la secuencia de comandos de este patrón se incluye en su propia operación, también se puede hacer referencia a ella en una secuencia de comandos de transformación incluida en otra operación (por ejemplo, en un nodo de bucle para eliminar registros que cumplen determinadas condiciones).

Ni una Solicitud ni una Estructura de Respuesta 1

Cree un objetivo HTTP con el Verbo HTTP y la URL para la solicitud de API específica. Recuerde borrar el tipo de contenido, ya que no se envían datos estructurados a la API.
Cree una operación de secuencia de comandos con un nuevo Jitterbit Script que proporciona el registro a eliminar (anulando la variable del proyecto valor que definimos previamente) luego llama al destino HTTP que acabamos de crear para enviar la solicitud.
```
<trans>
$jira.issueKey = "TEST-11";
WriteFile("<TAG>Targets/DELETE Jira Issue</TAG>", "");
</trans>
```
Implementar y ejecutar la operación. Haga doble clic en los íconos de estado en el monitor de operación para ver información sobre el estado de la operación. Si la operación no tiene éxito, el código de estado, los encabezados de respuesta y cualquier mensaje de error devuelto por la API se informarán en el registro de la operación. También puede verificar en su extremo o confirmar si los registros se han eliminado haciendo un GET.