AWS.Request — AWS SDK for JavaScript (original) (raw)

We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Class: AWS.Request

Inherits:

Object

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 Summarycollapse

Request Building Eventscollapse

Request Sending Eventscollapse

Data Parsing Eventscollapse

Completion Eventscollapse

HTTP Eventscollapse

HTTP Propertiescollapse

Operation Propertiescollapse

Sending a Requestcollapse

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 theresponse.error.retryable property to true, and optionally setresponse.error.retryDelay to the millisecond delay for the next attempt. In the case of a redirect, response.error.redirect should be set totrue 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 mostConfig.maxRetries times (based on the service object's config). Similarly, a request that is redirected will only redirect at mostConfig.maxRedirects times.

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.

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 andresponse.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.errorshould be checked, since the request may have failed.

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)

Note:

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)

Note:

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

Returns the raw HTTP request object containing request headers and body information sent by the service.

startTime ⇒ Date

Returns the time that the request started.

Method Details

abort() ⇒ AWS.Request

Note:

This feature is not supported in the browser environment of the SDK.

Aborts a request, emitting the error and complete events.

createReadStream() ⇒ Stream

Note:

The data read from a readable stream contains only the raw HTTP body contents.

Note:

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

Note:

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.

send(callback = null) ⇒ void