Invoke
Apply the Invoke policy to call another
service from within your assembly. The response from the backend is stored either in the variable
message.body or in the response object variable if it is defined. The policy can be
used with JSON or XML data, and can be applied multiple times within your assembly.
Gateway support
| Gateway | Policy version |
|---|---|
| DataPower® Gateway (v5 compatible) | 1.0.0 |
| DataPower API Gateway | 2.0.0 2.1.0 (DataPower API Gateway Version 10.0.1.1-eus or later) 2.2.0 (DataPower API Gateway Version 10.0.2.0 or later) 2.3.0 (DataPower API Gateway Version 10.0.1.4-eus or later) |
This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see invoke.
About
- If the HTTP request made by the invoke or proxy gets a redirect
(3xx) response:
- invoke returns the response from following the redirect response.
- proxy does not follow 3xx responses, and the redirect response is returned.
- The IBM API Connect test tool shows that proxy was used, but invoke appears in the Analytics latency records.
- The response from the proxy can contain different whitespace or escaping than a response from invoke. Despite the differences in the response, it is still valid.
Properties
The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.
| Property label | Required | Description | Data type |
|---|---|---|---|
| Title | Yes | The title of the policy. The default value is |
string |
| Description | No | A description of the policy. | string |
| URL | Yes | Specifies a URL for the target service. For a SOAP API, a URL is added by default. Where possible, the Invoke URL value is pre-supplied from information that is defined in the imported WSDL. |
string |
 Backend type |
No | Select one of the following options to determine how the payload is sent to the backend:
The default value is Detect. |
string |
| GraphQL send type(policy version 2.2.0 and
later) |
Yes, if Backend type is set to GraphQL or Detect, and HTTP Method is set to POST. or Keep | Select one of the following values to determine how the GraphQL payload is sent to the back
end: Note: GraphQL send
type is supported only if Backend type is set to
GraphQL or Detect, and HTTP
Method is set to POST or Keep.
|
string |
| TLS profile | No | Specifies a TLS profile to use for the secure transmission of data. | string |
| Timeout | Yes | The time to wait before a reply back from the endpoint (in seconds). The default value is
|
integer |
| Follow redirects | No | Specifies the behavior if the back-end server returns the HTTP status code 301 Moved
Permanently. If you select this check box, the invoke policy follows the
URL redirection by making a further call to the URL specified in the Location
header in the response. If you clear this check box, the invoke saves the
301 status code and the API call is considered to be complete.Note: The
follow-redirect property is supported only by the DataPower API
Gateway. If you are using
the DataPower Gateway (v5
compatible), the
invoke always follows the URL redirection; the proxy policy (not supported by the DataPower API
Gateway) saves the
301 status code and completes the API call without following the URL
redirection. |
boolean |
| Username | No | The username to use for HTTP Basic authentication. | string |
| Password | No | The password to use for HTTP Basic authentication. | string |
| HTTP Method | Yes | The HTTP method to use for the Invoke. Valid values are:
GET. However, if set to Keep, or the
property is removed from the source, the HTTP method from the incoming request is used. |
string |
| HTTP Version (policy version 2.1.0 and
later) |
Yes | The HTTP version that will be used when connecting to the backend server. Select one of the
following values:
|
string |
| HTTP/2 Required (policy version 2.1.0 and
later) |
No | Select this check box to require that the server selects HTTP/2 during a TLS connection, otherwise the DataPower API Gateway rejects the connection and fails the request. For a non TLS connection, a warning is logged stating that the requirement can't be enforced. This setting applies only if HTTP Version is set to HTTP/2. | boolean |
| Compression | No | Select this check box to enable Content-Encoding compression on upload. The check box is cleared by default. |
boolean |
|
Cache Type |
No | The cache type determines whether to cache documents, honoring or
overriding the HTTP Cache Control directives received in the response from the target URL. This
property takes effect only when a response is received, otherwise the policy always returns the
non-expired response that was previously saved in cache. Valid values are:
The default value is Protocol. |
string |
| Time to Live | No | Specifies the amount of time in seconds that the response stays in the cache. Applies only if
the property Cache type is set to Time to Live. Enter a
value in the range 5 - 31708800. The default value is |
integer |
| Cache key | No | Specifies the unique identifier of the document cache entry. If omitted, the entire URL string is used as the key. | string |
| Allow WebSocket Upgrade (policy version 2.1.0
and later) |
No | Select this check box to allow an HTTP or HTTPS connection to be upgraded to the WebSocket
protocol if the request received by the corresponding HTTP or HTTPS handler on the DataPower API
Gateway uses WebSocket
(ws) or WebSocket Secure (wss). Note:
|
boolean |
| Inject proxy headers |
No | If you select this check box, the invoke policy injects the
X-Forwarded-For, X-Forwarded-To,
X-Forwarded-Host, and X-Forwarded-Proto headers to the request
that is sent to the target URL.The check box is cleared by default. |
boolean |
| Decode Request Params |
No | If you select this check box, any request parameters that are referenced by a variable
definition on the target URL of the invoke policy are URL-decoded. The check box is cleared by default. |
boolean |
| Queryparam Encode |
No | If you select this check box, all "+" characters in the query parameter values of the target
URL are encoded to %2F. The check box is cleared by default. |
boolean |
| Keep Payload |
No | If you select this check box, the invoke policy sends a payload on an HTTP
DELETE method.The check box is cleared by default. |
boolean |
| Restrict to HTTP 1.0 (policy version 2.0.0
only) |
No | If you select this check box, HTTP transactions are restricted to version 1.0. The check box is cleared by default. |
boolean |
| Allow chunked uploads |
No | If you select this check box, chunked-encoded documents are sent to the server. When the HTTP
1.1 protocol is used, the body of the document can be delimited by either
Content-Length or chunked encoding. While all servers can interpret
Content-Length, many applications fail to understand chunked-encoded documents. For
this reason, Content-Length is the standard method.The use of
When enabled, the server must be RFC 2616 compatible. Unlike all other HTTP 1.1 features that can be negotiated down at run time, you must know beforehand that the target server is RFC 2616 compatible. The check box is selected by default. Note: Chunked encoding is not supported by the HTTP 1.0
protocol.
|
boolean |
| Persistent Connection (policy version 2.3.0
and later) |
No | Select this check box to enable HTTP persistent connections, allowing connection
re-use. The check box is selected by default. |
boolean |
| Header control |
No | Specifies the headers in message.headers that you want to copy to the target
URL.To prevent headers from being copied, complete the following steps:
To specify headers that you want to be copied, complete the following steps:
The values that you specify are in regular expression format. For example, to specify
the Content-Type header, enter
By default, Blocklist is selected, with no blocklist entries, meaning that all headers are copied. |
string |
| Parameter control |
No | Specifies the parameters in the incoming request that you want to be copied to the target
URL. To prevent parameters from being copied, complete the following steps:
To specify parameters that you want to be copied, complete the following
steps:
The values that you specify are in regular expression format. For example, if the
incoming request is
^petid$, the target URL at run time will be
By default, Allowlist is selected, with no allowlist entries, meaning that no parameters are copied. |
string |
| Stop on error | No | Select the errors that, if thrown during the policy execution, cause the assembly flow to
stop. If there is a catch flow configured for the error, it is triggered to handle
the error thrown. If an error is thrown and there are no errors selected for the Stop on
error setting, or if the error thrown is not one of the selected errors, the policy
execution is allowed to complete, and the assembly flow continues. |
string |
|
Response object variable |
No | The name of a variable that will be used to store the response data from the request. By
default, the invoke response, that is the body, headers, statusCode and statusMessage, is saved in
the variable message. Use this property to specify an alternate location to store
the invoke response. This variable can then be referenced in other actions, such as Map. Note: If you want the response to be saved in
message, leave the Response object variable property
blank, do not supply the value message.
|
string |
Example
- invoke:
version: 2.0.0
title: get the account status
target-url: https://example.com/accounts/{id}?status={status}
cache-response: time-to-live
cache-putpost-response: true
tls-profile: MyTLSProfile
verb: POST
timeout: 60
compression: false
username: MyUser
password: MyPassword
stop-on-error:
- ConnectionError
- OperationError