Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/support
esri/workers
Function: esri/request

require(["esri/request"], function(esriRequest) { /* code goes here */ });

Description

(Added at v1.0)
Retrieve data from a remote server or upload a file.

When coding legacy (non-AMD) style, there is no need to require the module. All methods and properties are available in the namespace. For example, esri.request().

Samples

Search for samples that use this class.

Methods

NameReturn typeSummary
esriRequest(request, options?)DeferredRetrieve data from a remote server or upload a file from a user's computer.
esriRequest.setRequestPreCallback(callbackFunction)NoneDefine a callback function that will be called just before esri.request calls into dojo IO functions such as dojo.rawXhrPost and dojo.io.script.get.
Method Details

esriRequest(request, options?)

Retrieve data from a remote server or upload a file from a user's computer. Refer to the conceptual help topic on esri.request for more information about the inner-workings of esri.request.
Return type: Deferred
Parameters:
<Object> request Required The request parameter is an object with the following properties that describe the request. See the object specifications table below for the structure of the request object.
<Object> options Optional See the object specifications table below for the structure of the options object.
Object Specifications:
<options>
<Boolean> disableIdentityLookup Required If true, prevents esri.request from triggering user authentication for this request. Default is false i.e., user authentication will be performed if asked by the server.
<Boolean> returnProgress Optional Indicates whether to return upload or download progress tracking. Note that this property is only valid for POST requests. It also requires the server to support pre-flighted CORS requests if the request is cross-domain.

Example usage:
var dfd = esriRequest({
  url: url,
  content: {f: "json"},
  form: document.getElementById("formDiv")
},{
  returnProgress: true
  })
    .then(function(result) {
      console.log(result);
    }, null, function(update) { 
      console.log("progress", update); 
    }).catch(function(err) { 
      console.log(err);
    });
The returned update object contains the following properties:
  • transferType: String Possible values: "download | "upload"
  • loaded: Number
  • total: Number
<Boolean> usePost Required Indicates the request should be made using HTTP POST method. Default is false i.e., determined automatically based on the request size.
<Boolean> useProxy Required Indicates the request should use the proxy. Default is false i.e., determined automatically based on the domain of the request url
<request>
<String> callbackParamName Required Name of the callback parameter (a special service parameter) to be specified when requesting data in JSONP format. It is ignored for all other data formats. For ArcGIS services the value is always 'callback'.
<Object> content Required If the request URL points to a web server that requires parameters, specify them here. The default value is null.
<Object> form Required If the request is to upload a file, specify the form element that contains the file input control here. The default value is null. Starting at version 3.3, the form parameter can be an instance of FormData. Using FormData you can send a "multipart/form-data" request to the server without having to create an HTML form element in markup. Note that the FormData api is not available in all browsers.
<String> handleAs Required Response format. Valid values are 'json', 'xml', 'text', 'blob', 'arraybuffer', 'document'. The default value is 'json'.
<Number> timeout Required Indicates the amount of time to wait for a response from the server. The default is 60000 milliseconds (one minute). Set to 0 to wait indefinitely.
<String> url Required Request URL. (required)
Sample:
Get the list of all sub-layers in the map service
require([
  "esri/request", ... 
], function(esriRequest, ... ) {
  var layerUrl = "https://www.example.com/argis/rest/services/Demographics/ESRI_Census_USA/MapServer/layers";
  var layersRequest = esriRequest({
    url: layerUrl,
    content: { f: "json" },
    handleAs: "json",
    callbackParamName: "callback"
  });
  layersRequest.then(
    function(response) {
      console.log("Success: ", response.layers);
  }, function(error) {
      console.log("Error: ", error.message);
  });
  ...
});

esriRequest.setRequestPreCallback(callbackFunction)

Define a callback function that will be called just before esri.request calls into dojo IO functions such as dojo.rawXhrPost and dojo.io.script.get. It provides developers an opportunity to modify the request.
Parameters:
<Function> callbackFunction Required The callback function that will be executed prior to esri.request calls into dojo IO functions.
Sample:
require([
  "esri/request", ... 
], function(esriRequest, ... ) {
  function myCallbackFunction(ioArgs) {
    // inspect ioArgs
    console.log(ioArgs.url, ioArgs.content);

    // or, change some query parameters if necessary
    ioArgs.content = ioArgs.content || {};
    ioArgs.content.token = "ABCDEF123456";

    // don't forget to return ioArgs.
    return ioArgs;
  }

  // where the argument ioArgs is of type: dojo.__XhrArgs (or) dojo.io.script.__ioArgs

  esriRequest.setRequestPreCallback(myCallbackFunction);
  ...
});
Show Modal