Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Function: esri/request
[ AMD Module Require | Legacy Module Require ]
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
| Name | Return type | Summary |
|---|---|---|
| esriRequest(request, options?) | Deferred | Retrieve data from a remote server or upload a file from a user's computer. |
| esriRequest.setRequestPreCallback(callbackFunction) | None | 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. |
Method Details
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:
DeferredParameters:
< |
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. |
< |
Optional | See the object specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
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. |
< |
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:
|
< |
Required | Indicates the request should be made using HTTP POST method. Default is false i.e., determined automatically based on the request size. |
< |
Required | Indicates the request should use the proxy. Default is false i.e., determined automatically based on the domain of the request url |
<
request>< |
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'. |
< |
Required | If the request URL points to a web server that requires parameters, specify them here. The default value is null. |
< |
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. |
< |
Required | Response format. Valid values are 'json', 'xml', 'text', 'blob', 'arraybuffer', 'document'. The default value is 'json'. |
< |
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. |
< |
Required | Request URL. (required) |
Sample:
Get the list of all sub-layers in the map service
require([
"esri/request", ...
], function(esriRequest, ... ) {
var layerUrl = "http://sampleserver1.arcgisonline.com/ArcGIS/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);
});
...
});
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:
< |
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);
...
});