HTTPAsyncRequest node
Use the HTTPAsyncRequest node with the HTTPAsyncResponse node to construct a pair of message flows that interact with a web service asynchronously.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Express
- Scale
- Adapter
This topic contains the following sections:
Purpose
The HTTPAsyncRequest node sends a web service request, but the node does not wait for the associated web service response to be received. The web service response is received by the HTTPAsyncResponse node, which can be in a separate message flow but must be in the same integration server. The nodes are used as a pair, and correlate responses against the original requests using a unique identifier. The HTTPAsyncRequest node passes the request socket to the HTTPAsyncResponse node for the backend server to use for the response. If the latency of the backend server is high, it might not respond within the socket timeout.
Passing the HTTP socket to the HTTPAsyncResponse node enables the message flow to retrieve the next message from the queue without waiting for the response, and thereby uses threads and storage more efficiently than a synchronous message flow.
Depending on the configuration, this node constructs an HTTP or an HTTP over SSL (HTTPS) request from the specified contents of the input message, and sends this request to the web service. The HTTPAsyncResponse node receives the response from the web service, and parses the response for inclusion in its output tree. The HTTPAsyncRequest node generates HTTP headers if they are required by your configuration.
The HTTPAsyncRequest node is contained in the HTTP drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:
Using the HTTPAsyncRequest node to issue a request to a web service
- The URL of a service.
- A stream of data that the remote server processes in order to send back a response, which is often a SOAP or other web service message in XML.
The URL is of the format http://<address>[:<port>]/<function>; for example, http://localhost:7080/request. This URL can be specified statically in the HTTPAsyncRequest node parameters as a field in the message itself, or dynamically as a field in the local environment.
The data must be in CCSID 1208 format for most requests. If the request is successful, the HTTPResponse is returned to the paired HTTPAsyncResponse node.
You can use an HTTP proxy to route a request through an intermediate site. You can run tools as a proxy to see the request and the response, and thereby debug your flows. The HTTP destination is as seen by the proxy; if you specify the HTTP destination of localhost, and your HTTP proxy is running on a different computer, the request is routed to the remote proxy computer, not the computer from which the original request was issued.
Timeouts
You can specify a timeout interval, so that if the whole request-response operation takes longer than the specified duration, the request is propagated to the Failure terminal on one of the paired nodes. The timeout interval applies to the interval that starts with the request being sent by the HTTPAsyncRequest node, and ends with the response being completely received by the HTTPAsyncResponse node.
For each request that the HTTPAsyncRequest node processes it uses a connection to send the request, and passes the connection to the paired HTTPAsyncResponse node for the response. If the timeout interval is specified, the socket is closed if the interval expires. This closure ensures that a request gets only the correct response, and any response data for a request that has timed out is discarded.
The request-response processing is split between the HTTPAsyncRequest node and the HTTPAsyncResponse node. If a timeout occurs during the request phase of processing, the request and an exception are propagated to the Failure terminal of the HTTPAsyncRequest node. Similarly, if a timeout occurs during the response phase of processing, an exception is propagated to the Failure terminal of the HTTPAsyncResponse node.
In most cases the timeout would occur when waiting for a server response, in which case the Failure terminal of the HTTPAsyncResponse node is used. In rare cases a timeout might occur when the request node sends data to the server. In this case, the Failure terminal of the HTTPAsyncRequest node is used.
Using the HTTPAsyncRequest node in a message flow
The HTTPAsyncRequest node can be used in any message flow that must send an HTTP request and receive a response asynchronously. The most common example is a message flow that calls a web service.
For more information about working with HTTP, see Processing HTTP messages.
Handling errors
The node interacts directly with an external service using TCP/IP; therefore it can experience errors that are generated by TCP/IP. For example, no route to host or connection refused. If the node detects these errors, it generates an exception, populates the exception list with the error information that is received, and routes the input message unchanged to the Failure terminal.
Behavior of a node that adds a request to a group
When a supported node successfully processes a message for output, it adds the information about the request that was just sent to the group that was most recently created in the message flow. The reply ID that the group expects is determined automatically from the transport, and the folder name is taken from the Folder name attribute.
Overrides
By default, the output node adds the request to the most recently created group. If multiple groups are being constructed in the same thread, a local environment override can be used to specify the group ID of the target group: LocalEnvironment.Destination.GroupScatter.RequestNode.GroupId. Requests can only be added to a group that is in construction in the current message flow thread. An exception is issued if no such group is available.
Transactions
Where a transport is transactional, the message obeys the usual transactional rules for the given transport. However, the group information is updated outside of the scope of the transaction. Therefore, if the transaction and output message are rolled back, the request is still added to the group.
Error
If Add Request to Group is true, and Folder name is blank, a configuration exception is issued. The thread context is used to determine which group to add a request to.
If Add Request to Group is true but no group is in construction in this thread, an exception is issued.
If a group ID override is specified and the ID is invalid, or does not correspond to a group that is in construction in the current thread, an exception is issued.
Terminals and properties
The HTTPAsyncRequest node terminals are described in the following table.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing by the node. |
Failure | The output terminal to which the message is routed if a failure is detected during processing in the node. |
Out | The output terminal to which the message is routed if it represents successful completion of the web service request, and if further processing is required within this message flow. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk on the panel if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).
The HTTPAsyncRequest node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type, HTTPAsyncRequest | The name of the node. |
Short description | No | No | A brief description of the node. | |
Long description | No | No | Text that describes the purpose of the node in the message flow. |
The HTTPAsyncRequest node Basic properties are described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Unique identifier | Yes | No | This property is the unique identifier that links a pair of HTTPAsyncRequest and HTTPAsyncResponse nodes. | asyncResponseCorrelator | |
Web service URL | Yes | Yes | The URL for the web service. You must provide
this in the form http://hostname[:port]/[path] where
The HTTPAsyncRequest node determines the URL for the web service to which it sends a request. Select one of the following three options; the node checks these in the order shown (that is, the first always overrides the second, the second overrides the third):
The first two options provide dynamic methods to set a URL for each input message as it passes through the message flow. To use either of these options, include a Compute node in the message flow, before the HTTPAsyncRequest node, to create and initialize the required value. The third option provides a value that is fixed for every message that is received in this node. Set this property to contain a default setting that is used if the other fields have not been created, or contain a null value. If either field contains a value, the setting of this property is ignored. The Web service URL property must contain a valid URL or the deployment fails. Ensure that the value that you set in X-Original-HTTP-URL or the LocalEnvironment.Destination.HTTP.RequestURL is also a valid URL; if it is not, the node uses the default setting from the Web service URL property. |
URLSpecifier | |
Request timeout (sec) | Yes | Yes | 120 | The value of the wait time for the remote web
server to send a response to the HTTPAsyncResponse node. The
valid range is 1 through (231)-1. You cannot enter a value
that represents an unlimited wait. For more information about timeout behavior, see Timeouts. |
timeoutForServer |
The HTTPAsyncRequest node HTTP Settings properties are described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
HTTP(S) proxy location | No | Yes | The proxy server to which requests are sent.
This value must be in the form hostname:port. If the configured proxy server requires
authentication, the credentials must be set by using the mqsisetdbparms command with
the resource name |
httpProxyLocation | |
HTTP method | No | No | POST | The HTTP method. Valid values are POST, GET, PUT, DELETE, and HEAD. By default, the HTTPAsyncRequest node uses the HTTP POST method when it connects to the remote web server. HEAD is used to determine whether a service is available - for example, by a Network Dispatcher trying to work out which servers are available - and sends back the correct headers (including content-length) but no body data. | |
Use compression | No | Yes | None | This property controls whether the content of
the HTTP request is compressed. You can choose a value from none, gzip, zlib (deflate), and deflate. If the request is compressed,
the Content-Encoding header is set to indicate that the content is
compressed. zlib (deflate) represents RFC 1950 + RFC 1951 combined. deflate represents RFC 1951 only. The default value is none, meaning that the content of the request is not compressed. |
requestCompressionType |
The HTTPAsyncRequest node SSL properties are described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Protocol | No | Yes | TLS | Specify the SSLProtocol property
to use when making an HTTPS request. Both ends of an SSL connection
must agree on the protocol to use. Therefore, the selected protocol
must be one that the remote server can accept. The following options
are available:
|
protocol |
Allowed SSL ciphers | No | Yes | A comma-separated list of ciphers to use when
making an SSL request. Use this setting to specify a single cipher (such as SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA) or a list of ciphers that are the only ones used by the connection. This set of ciphers must include one or more that are accepted by the remote server. A comma is used as a separator between the ciphers. The default value is an empty string, which enables the node to use any, or all, of the available ciphers during the SSL connection handshake. This method gives the greatest scope for making a successful SSL connection. |
allowedCiphers | |
Enable SSL certificate hostname checking | No | Yes | Yes | This property specifies whether the host name of the server that is receiving the request must match the host name in the SSL certificate. | hostnameChecking |
SSL client authentication key alias | No | Yes | (empty string) | This property specifies an SSL authentication alias for the client-side of an HTTPAsyncRequest connection. Taking the default value means that the first appropriate key is chosen for you automatically. | keyAlias |
Enable certificate revocation list checking | No | Yes | Not selected | This property specifies whether CRL checking should be enabled for SSL connections | enableCRLCheck |
The HTTPAsyncRequest node Advanced properties are described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Generate default HTTP headers from input | No | No | Selected | If you select this check box, an HTTPRequestHeader
is generated. If you clear this check box, a valid HTTPRequestHeader
must exist in the input message. To control the contents of the HTTPRequestHeader that is included in the request message, include a Compute node that adds an HTTPRequestHeader to the input message before this HTTPAsyncRequest node in the message flow, and clear this check box.
If you have selected Use
compression or Accept compressed
responses by default, the Content-Encoding and Accept-Encoding
HTTP header fields are populated regardless of whether you have selected Generate default HTTP headers from input:
|
|||||||||
Accept compressed responses by default | No | Yes | Cleared | This property indicates whether the HTTPAsyncResponse node handles
compressed responses by default. If the request header does not contain
an Accept-Encoding header and this option is selected, the node sets
the Accept-Encoding header to "gzip, deflate", and any compressed
response that is received is decompressed by the response node. If the message propagated to the HTTPAsyncResponse node includes an Accept-Encoding header, the message flow or client application should handle any compressed response. Therefore selecting this option has no effect in that case. |
acceptCompressedResponses |
Property | M | C | Default | Description |
---|---|---|---|---|
Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |
Local environment overrides
Setting | Description |
---|---|
Compression | Overrides the Use
compression property on the node. For example: To set a minimum size (in bytes)
at which compression is applied, use the following override:
|
ProxyConnectHeaders | Specifies
additional headers that are used if the outbound request is an SSL
connection through a proxy. These additional headers are sent with
the initial CONNECT request to the proxy. For example, you can send
proxy authentication information to a proxy server when you are using
SSL. You can send multiple headers but each one must be separated
by a carriage return and a line feed (ASCII 0x0D 0x0A), in accordance
with RFC2616; for example: This setting is used only if the request is an SSL request
through a proxy server. To send proxy authentication information for
a non-SSL request, specify the individual headers in the HTTPRequestHeader
folder, as shown in the following example:
|
ProxyURL | Overrides the HTTP(S) proxy location property
on the node. For example:
|
QueryString | Allows the setting of outbound query string
parameters. Each parameter must be set individually. For example: The
above ESQL results in the following query string being encoded (according
to http://tools.ietf.org/html/rfc3986) and sent
with the outbound request: If
the destination URL already has one or more query parameters, additional
parameters specified here are appended to the existing list. |
QueryStringCCSID | Specifies that, before encoding, the query string
parameters must be converted into a character set other than the default,
which is UTF-8. Any query string parameters are first converted into
the specified CCSID before the resulting string is encoded, according
to RFC3986.
For example: The
above ESQL results in any QueryString parameters being converted to
the 943 code page before they are encoded. Note: Any query string
parameters must contain the data in unicode. |
QueryStringPercentEncodeSpace | Specifies that any space character in the QueryString
be percent encoded and then sent with outbound request. By default
any space character in the QueryString is converted to "+ "
character. For example:
|
QueryStringSendWithRedirect | Specifies that the QueryString be sent with
HTTP(S) redirect. For example:
|
QueryStringDoNotPercentEncodeCharacters | Specifies any characters in the QueryString
that are not to be percent encoded while the URI is built. For example:
|
QueryStringSemicolonSeparator | Specifies that the semicolon be used as a separator
between query strings instead of "& ". For example: |
RequestLine.RequestURI | Overrides the RequestURI , which
is the path after the URL and port. For example:
|
RequestLine.HTTPVersion | Overrides the HTTP
version property on the node. For example:
|
RequestLine.Method | Overrides the HTTP
method property on the node. For example:
|
RequestURL | Overrides the Web
service URL property on the node. For example:
|
SSL authentication alias | Overrides the SSL
authentication alias for the client-side of an HTTP connection
on the node. For example:
|
SSLProtocol | Overrides the SSLProtocol.
For example:
Valid
values are: SSL, SSLv3, TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, and
SSL_TLSv2
Note: SSLv3
is disabled by default in IBM Integration Bus Version 10.0, because SSLv3
is no longer considered secure; see Migrating a flow that uses SSLv3 for
more information.
|
SSLCiphers | Overrides the Allowed
SSL Ciphers property on the node. For example:
|
UserContext | You can store BLOB context data in the following
location in the local environment. The HTTPAsyncResponse node can
later retrieve this data. Data
stored in the UserContext must be in BLOB format. |
Enable CRL checking | Overrides the Enable
Certificate Revocation List checking property on the node.
For example:
|
Working with WrittenDestination data
WrittenDestination = (
HTTP = (
RequestURL = 'http://127.0.0.1:7800/HTTPFLOW' (CHARACTER)
Compression = (
OriginalSize = 53 (INTEGER)
CompressedSize = 71 (INTEGER)
)
)
)