Class: AWS.Request
- Inherits:
-
Object
- Object
- AWS.Request
- Defined in:
- lib/request.js
Overview
Asynchronous Requests
All requests made through the SDK are asynchronous and use a
callback interface. Each service method that kicks off a request
returns an AWS.Request
object that you can use to register
callbacks.
For example, the following service method returns the request object as "request", which can be used to register callbacks:
// request is an AWS.Request object
var request = ec2.describeInstances();
// register callbacks on request to retrieve response data
request.on('success', function(response) {
console.log(response.data);
});
When a request is ready to be sent, the send() method should be called:
request.send();
Since registered callbacks may or may not be idempotent, requests should only be sent once. To perform the same operation multiple times, you will need to create multiple request objects, each with its own registered callbacks.
Removing Default Listeners for Events
Request objects are built with default listeners for the various events, depending on the service type. In some cases, you may want to remove some built-in listeners to customize behaviour. Doing this requires access to the built-in listener functions, which are exposed through the AWS.EventListeners.Core namespace. For instance, you may want to customize the HTTP handler used when sending a request. In this case, you can remove the built-in listener associated with the 'send' event, the AWS.EventListeners.Core.SEND listener and add your own.
Multiple Callbacks and Chaining
You can register multiple callbacks on any request object. The callbacks can be registered for different events, or all for the same event. In addition, you can chain callback registration, for example:
request.
on('success', function(response) {
console.log("Success!");
}).
on('error', function(error, response) {
console.log("Error!");
}).
on('complete', function(response) {
console.log("Always!");
}).
send();
The above example will print either "Success! Always!", or "Error! Always!", depending on whether the request succeeded or not.
Constructor Summary collapse
-
new AWS.Request(service, operation, params) ⇒ void
constructor
Creates a request for an operation on a given service with a set of input parameters.
Request Building Events collapse
-
'validate'
function (request)
Triggered when a request is being validated.
-
'build'
function (request)
Triggered when the request payload is being built.
-
'sign'
function (request)
Triggered when the request is being signed.
Request Sending Events collapse
-
'send'
function (response)
Triggered when the request is ready to be sent.
-
'retry'
function (response)
Triggered when a request failed and might need to be retried or redirected.
Data Parsing Events collapse
-
'extractError'
function (response)
Triggered on all non-2xx requests so that listeners can extract error details from the response body.
-
'extractData'
function (response)
Triggered in successful requests to allow listeners to de-serialize the response body into
response.data
.
Completion Events collapse
-
'success'
function (response)
Triggered when the request completed successfully.
-
'error'
function (error, response)
Triggered when an error occurs at any point during the request.
-
'complete'
function (response)
Triggered whenever a request cycle completes.
HTTP Events collapse
-
'httpHeaders'
function (statusCode, headers, response, statusMessage)
Triggered when headers are sent by the remote server.
-
'httpData'
function (chunk, response)
Triggered when data is sent by the remote server.
-
'httpUploadProgress'
function (progress, response)
Triggered when the HTTP request has uploaded more data.
-
'httpDownloadProgress'
function (progress, response)
Triggered when the HTTP request has downloaded more data.
-
'httpError'
function (error, response)
Triggered when the HTTP request failed.
-
'httpDone'
function (response)
Triggered when the server is finished sending data.
HTTP Properties collapse
-
httpRequest ⇒ AWS.HttpRequest
readonly
The raw HTTP request object containing request headers and body information sent by the service.
Operation Properties collapse
-
startTime ⇒ Date
readonly
The time that the request started.
Sending a Request collapse
-
abort() ⇒ AWS.Request
Aborts a request, emitting the error and complete events.
-
createReadStream() ⇒ Stream
Sends the request and converts the request object into a readable stream that can be read from or piped into a writable stream.
-
eachItem(callback) ⇒ void
Enumerates over individual items of a request, paging the responses if necessary.
-
eachPage(callback) ⇒ void
Iterates over each page of results given a pageable request, calling the provided callback with each page of data.
-
isPageable() ⇒ Boolean
Whether the operation can return multiple pages of response data.
-
promise() ⇒ Promise
Sends the request and returns a 'thenable' promise.
-
send(callback = null) ⇒ void
Sends the request object.
Constructor Details
new AWS.Request(service, operation, params) ⇒ void
Creates a request for an operation on a given service with a set of input parameters.
Event Details
'validate' — function (request)
Triggered when a request is being validated. Listeners should throw an error if the request should not be sent.
'build' — function (request)
Triggered when the request payload is being built. Listeners should fill the necessary information to send the request over HTTP.
'sign' — function (request)
Triggered when the request is being signed. Listeners should add the correct authentication headers and/or adjust the body, depending on the authentication mechanism being used.
'send' — function (response)
Triggered when the request is ready to be sent. Listeners should call the underlying transport layer to initiate the sending of the request.
'retry' — function (response)
Triggered when a request failed and might need to be retried or redirected.
If the response is retryable, the listener should set the
response.error.retryable
property to true
, and optionally set
response.error.retryDelay
to the millisecond delay for the next attempt.
In the case of a redirect, response.error.redirect
should be set to
true
with retryDelay
set to an optional delay on the next request.
If a listener decides that a request should not be retried,
it should set both retryable
and redirect
to false.
Note that a retryable error will be retried at most Config.maxRetries times (based on the service object's config). Similarly, a request that is redirected will only redirect at most Config.maxRedirects times.
'extractError' — function (response)
Triggered on all non-2xx requests so that listeners can extract
error details from the response body. Listeners to this event
should set the response.error
property.
'extractData' — function (response)
Triggered in successful requests to allow listeners to
de-serialize the response body into response.data
.
'success' — function (response)
Triggered when the request completed successfully.
response.data
will contain the response data and
response.error
will be null.
'error' — function (error, response)
Triggered when an error occurs at any point during the
request. response.error
will contain details about the error
that occurred. response.data
will be null.
'complete' — function (response)
Triggered whenever a request cycle completes. response.error
should be checked, since the request may have failed.
'httpHeaders' — function (statusCode, headers, response, statusMessage)
Triggered when headers are sent by the remote server
'httpData' — function (chunk, response)
Triggered when data is sent by the remote server
'httpUploadProgress' — function (progress, response)
This event will not be emitted in Node.js 0.8.x.
Triggered when the HTTP request has uploaded more data
'httpDownloadProgress' — function (progress, response)
This event will not be emitted in Node.js 0.8.x.
Triggered when the HTTP request has downloaded more data
'httpError' — function (error, response)
Triggered when the HTTP request failed
'httpDone' — function (response)
Triggered when the server is finished sending data
Property Details
httpRequest ⇒ AWS.HttpRequest (readonly)
Returns the raw HTTP request object containing request headers and body information sent by the service.
startTime ⇒ Date (readonly)
Returns the time that the request started.
Method Details
abort() ⇒ AWS.Request
This feature is not supported in the browser environment of the SDK.
Aborts a request, emitting the error and complete events.
createReadStream() ⇒ Stream
The data read from a readable stream contains only the raw HTTP body contents.
This feature is not supported in the browser environment of the SDK.
Sends the request and converts the request object into a readable stream that can be read from or piped into a writable stream.
eachItem(callback) ⇒ void
This function is part of an experimental API. You can use this function, but it may be removed or be changed in the future.
Enumerates over individual items of a request, paging the responses if necessary.
eachPage(callback) ⇒ void
This operation can generate multiple requests to a service.
Iterates over each page of results given a pageable request, calling
the provided callback with each page of data. After all pages have been
retrieved, the callback is called with null
data.
isPageable() ⇒ Boolean
Returns whether the operation can return multiple pages of response data.
promise() ⇒ Promise
Sends the request and returns a 'thenable' promise.
Two callbacks can be provided to the then
method on the returned promise.
The first callback will be called if the promise is fulfilled, and the second
callback will be called if the promise is rejected.