Service Callout

Al igual que con el interceptor Internal API Call, Service Callout permite invocar una llamada con base en configuraciones predefinidas. La diferencia es que, mientras que Internal API Call redirige a APIs que están en la Plataforma Sensedia, Service Callout permite invocar una llamada externa.

Configuración del interceptor

Las imágenes y texto a continuación presentan las informaciones necesarias para configurar el interceptor.

Variable name: define el nombre del Service Callout, siendo único por flujo. La respuesta a la llamada se recupera dentro del mapa $call.contextVariables utilizando el nombre informado aquí. Se requiere un custom interceptor para esto, como se muestra abajo.
URL: define la URL de la petición externa
Method: define el método HTTP que se utilizará en la petición externa;
Expected status: define el status code esperado;
Preserve query string: si es marcado, la cadena de consulta presente en la petición será transmitida para la llamada externa.
Preserve body: si es marcado, el cuerpo contenido en la petición será transmitido para la llamada externa. El campo es habilitado cuando el método es diferente de GET.
Body: permite la inserción de un cuerpo. El campo es habilitado cuando el method es diferente de GET y el campo Preserve body es desmarcado.
- En este punto, es posible utilizar variables de entorno (environment variables), sin embargo, no es posible utilizar más de una. Para obtener más información sobre las variables de entorno, haga clic aquí.
Preserve headers: si es marcado, los headers presentes en la petición serán transmitidas para la llamada externa.
Headers: permite la inserción de headers.

El header de Transfer-Encoding es removido quando la solicitud viaja a través del gateway, tanto en response como en request. Para obtener más información sobre la eliminación de headers, haga clic aquí.

Service Callout puede realizar llamadas síncronas o asíncronas En el segundo caso, una llamada síncrona será enviada para la nueva URL y el interceptor quedará aguardando el resultado de esta llamada para continuar la ejecución del flujo. Para llamadas asíncronas, seleccionar el campo Asynchronous.

Para capturar la respuesta de llamadas asíncronas, es necesario utilizar el interceptor Service Mashup en el flujo.

Las llamadas asíncronas pueden ser del tipo Fire and Forget o no, basta el usuario seleccionar el campo del mismo nombre o dejarlo en blanco. Si se selecciona el campo, el interceptor enviará la llamada y la olvidará. En este caso, no habrá ningún retorno de la nueva llamada.

Cuando no sea marcada la opción Fire and Forget, podrá ser configurado un tiempo de espera (Timeout) para la llamada a ser realizada. Esta llamada será realizada de forma paralela y será cerrada en el caso que el timeout alcance su límite o ella retorne un resultado.

Abort request if fail: aborta el proceso en el caso que la petición falle. Se caracteriza una falla cuando el status code de la petición es diferente del esperado. El campo es habilitado cuando la petición sea síncrona.

Códigos de estado de error

Los códigos de estado devueltos por Service Callout cuando se produce un error, y las razones para ellos, son:

417: si el estado esperado es diferente del estado devuelto por la llamada.
408: si la llamada supera el límite de tiempo (timeout).
500: cualquier otro caso distinto de los mencionados.

Funcionamiento

Para mostrar cómo funciona el Service Callout, consideremos el siguiente caso:

Una organización, la LSA (Lost Souls' Alliance), desarrollará una API central, LSA Communication, que podrá enviar, vía POST, el mismo mensaje (o comando) a personas dentro y fuera de la organización. Esta API estará registrada bajo el dominio lsa.org.mx.

El mensaje, enviado como JSON en el cuerpo de la llamada, será:

{
  "message": "Join or Die! Viva la revolución!",
  "author": "Salvador Limones"
}

En el caso de la comunicación externa, existe una API expuesta, bajo el dominio lsa-spies.org.mx y externa a la plataforma de Sensedia, que permite el envío del mensaje por el sistema externo (pigeons). Este sistema cuenta con dos recursos para ello: pigeons/pigeon-manny y pigeons/pigeon-meche. Para aprovechar esta API, utilizamos Service Callout.

Como son dos recursos diferentes, se utilizarán dos interceptores Service Callout. Las siguientes imágenes muestran, respectivamente, la secuencia de interceptores en el flujo de la API y la configuración utilizada en el interceptor que hace la llamada POST a pigeons/pigeon-manny, siendo similar la configuración para pigeons/pigeon-meche:

Es importante destacar que, al estar configurados para actuar de forma sincrónica, el segundo interceptor Service Callout sólo se ejecutará cuando el primero haya terminado de ejecutarse. Cuando el tiempo de ejecución es una cuestión relevante, se recomienda utilizar llamadas asíncronas, como se ejemplifica en el uso de Service Mashup.

La llamada a pigeons/pigeon-manny devuelve, con código de estado 200, el siguiente cuerpo:

{
  "message": "I'm already dead...",
  "author": "Manuel Calavera"
}

Ya la llamada a pigeons/pigeon-meche devuelve, también con código de estado 200, el siguiente cuerpo:

{
  "message": "Only if it has cars, as I was given one purpose, one skill, one desire: to DRIVE!",
  "author": "Glottis"
}

Después de cada llamada sincrónica, el interceptor devolverá un objeto de tipo RESTResponse que se almacenará en las variables del contexto de la llamada. Para recuperar la respuesta, es necesario crear un custom interceptor que acceda a $call.contextVariables.get(“Variable Name”).

A continuación se muestra el código para el custom JavaScript interceptor que se utilizará para capturar las respuestas e incluir los cuerpos y los estados en la respuesta final:

// Captura las respuestas de los Service Callouts
var respManny = $call.contextVariables.get('mannyMessage');
var respMeche = $call.contextVariables.get('mecheMessage');

// Crea un objeto ApiResponse para esta llamada
$call.response = new com.sensedia.interceptor.externaljar.dto.ApiResponse();
$call.response.addHeader('Content-Type', 'application/json');

// Plantilla JSON para los mensajes devueltos
var respBody = JSON.parse(`{
    "pigeonManny": {"status": 0, "body": {}},
    "pigeonMeche": {"status": 0, "body": {}}}
`);

// El estado devuelto es Object, no Number
var statusManny = respManny.getStatus();
var statusMeche = respMeche.getStatus();

// Se llama al método intValue para obtener un objeto Number
respBody.pigeonManny.status = statusManny.intValue();
respBody.pigeonMeche.status = statusMeche.intValue();

// Se inserta un cuerpo sólo si se devuelve un estado 200
if (statusManny == 200){
    respBody.pigeonManny.body = JSON.parse(respManny.getResponseText());
}

if (statusMeche == 200){
    respBody.pigeonMeche.body = JSON.parse(respMeche.getResponseText());
}

// Inserta el cuerpo modificado en el ApiResponse
$call.response.getBody().setString(JSON.stringify(respBody), "UTF-8");

// Establece el estado de retorno como 200
$call.response.setStatus(200);

Finalmente, el cuerpo de la respuesta de la llamada POST al recurso external-messages de LSA Communication será:

{
  "pigeonManny": {
    "status": 200,
    "body": {
      "message": "I'm already dead...",
      "author": "Manuel Calavera"
    }
  },
  "pigeonMeche": {
    "status": 200,
    "body": {
      "message": "Only if it has cars, as I was given one purpose, one skill, one desire: to DRIVE!",
      "author": "Glottis"
    }
  }
}

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]