This task calls a remote server to make a service call or retrieve an URL.

It is also called the RetrieveURL Task.

Call service / retrieve URL

Description

Contains a description of the task, enter the reason for its existence here.

JSON key: description
Default value: Blank

Destination

Destination to send request to, or leave blank to connect directly to URL without using a destination. Please note that connections are pooled and reused when using a destination, also specific HTTPS settings and HTTP/2 can be used.

JSON key: destination
Default value: Blank

Method

HTTP Request method to use when making the call.

JSON key: method
Default value: GET

URI

Please enter the URI, or complete URL in case destination is not used.

JSON key: uri
Default value: None

Body

Enter the request body contents - see Scripts and Macros for details on how to specify macro content.

JSON key: body
Default value: None

Completed attr name

Name of "completed requests" attribute to store result of service call within. This result is stored within the context for the currently executing request.

JSON key: completed.name
Default: None

Timeout

Timeout in seconds - maximum time to give the server to respond - if not specified, the default settings for the destination will be used. If no destination is set, the timeout will be 30 seconds.

JSON key: timeout
Default value: None

Max retries

If a destination is selected, this is the max number of attempts used to find a working server.

JSON key: retry.count
Default value: 1

Headers

HTTP Request headers can be specified in the JSON Property "request.headers", exactly like HTTP headers are configured for Locations.

Do this by selecting the item "Headers" in the sub-tree, where you can add, remove or edit header content. For each header value, You can use Scripts and Macros to produce it.

JSON Configuration

Below is a set of example configuration.

{
  "completed.name": "lang_da",
  "request.headers": [{
    "name": "Accept",
    "value": "application/json"
  }],
  "method": "GET",
  "body": null,
  "destination": "restcountries.eu",
  "description": "Get information for countries speaking danish",
  "class": "io.ceptor.pipeline.tasks.RetrieveURLTask",
  "uri": "https://restcountries.eu/rest/v2/lang/da"
}

Retrieving the Results

Once the task is completed, the result is stored in the context (see Plugins and Scripts and Macros) in the completedRequests map, using the  value of the configured completed.name attribute as key

public HashMap<String, CompletedRequest> completedRequests = new HashMap<>();


// CompletedRequest contains the result of a service call task within a pipeline
public final class CompletedRequest {
    public volatile long startedAt = System.currentTimeMillis();
    public volatile long endedAt;
    public volatile int tries;
    public volatile boolean isCancelled;
    public volatile Exception exception;
    public volatile byte[] response;
    public volatile int responseCode;
    public volatile String responseReason;
    public volatile HeaderMap responseHeaders;
 
    /* Returns the response converted to a string in the character set indicated by the content-type response header */
    public String getResponseAsString();
}

To access the results, you can either go into the structure directly from a script, e.g.

var response = context.completedRequests.get("lang_da").getResponseAsString();
var httpResponseCode = context.completedRequests.get("lang_da").responseCode;

or you can use the macros to refer to the result, e.g. %{compreq.response:lang_da} or from a script:

context.macro('%{compreq.response:lang_da}')

or from a script, call:

These macros are the relevant ones:

A macro is in the format %{<name>} or %{<prefix>:<name>}
The following prefixes related to accessing the result of a completed request exist:

• compreq.cancelled - true, if the completed request was cancelled, e.g. because of timeout, and false if not.
• compreq.exception - If the completed request failed with an exception, this contains the toString() output from the exception.
• compreq.response - The response for the completed request, converted to a string.
• compreq.response.code - Response code for a completed request, e.g. 200.
• compreq.response.reason - Response reason for a completed request, e.g. OK.
• compreq.response.headers - A JSON object containing all the response headers.
• compreq.response.header - The header value (or JSON array of values) of the response header - the name of the header stake from the # in the name, e.g. %{compreq.response.header:sample#Content-Length} returns the Content-Length header for the completed response named "sample".