API de cartographie Web ArcGIS
La rubrique Infrastructure pour les applications cartographiques SIG Web vous aidera à démarrer et comprendre les applications Web de SIG. Les API Web ArcGIS permettent aux navigateurs Web de communiquer avec les services SIG d'ArcGIS Server, d'afficher (dessiner) les données géographiques et d'effectuer des analyses. Les API Web d'ArcGIS sont réparties en trois types. Ces jeux sont :
- ArcGIS API for JavaScript
- ArcGIS API for Flex
- ArcGIS API for Microsoft Silverlight/WPF
Ces trois API disposent de fonctionnalités similaires, mais sont destinées à des langages de développement différents. Pour démarrer avec le développement d'applications Web à l'aide de Flex ou Silverlight, vous devez télécharger les bibliothèques sur le site ArcGIS pour les développeurs. En ce qui concerne les API Web JavaScript, il n'est pas nécessaire de télécharger la bibliothèque puisqu'elle est accessible au moyen d'une URL Web. Le site ArcGIS pour les développeurs offre des exemples de code, des didacticiels, des guides et des références détaillées pour les API Web d'ArcGIS.
Tâches de géotraitement dans les applications Web
Vous pouvez ajouter des fonctionnalités de géotraitement et d'analyse de données aux applications Web à l'aide des services de géotraitement ArcGIS. Chaque service de géotraitement comporte une ou plusieurs tâches de géotraitement. En naviguant dans le répertoire de services du serveur ArcGIS, vous trouverez des services de géotraitement, les tâches au sein du service, ainsi que les paramètres et propriétés de chaque tâche. La rubrique Services REST de géotraitement fournit des informations concernant la hiérarchie des ressources REST, et la rubrique Présentation des tâches de géotraitement fournit des informations concernant les tâches de géotraitement, leurs paramètres et la façon d'y accéder. Les API Web offrent des objets et méthodes pratiques permettant d'accéder aux tâches de géotraitement et d'exécuter les fonctionnalités.
Pour ajouter une fonctionnalité de géotraitement proposée par une tâche à votre application Web, appliquez les quatre étapes suivantes :
- Initialisation de la tâche de géotraitement.
- Configuration des paramètres pour la tâche.
- Exécution de la tâche.
- Affichage des résultats.
Ces quatre étapes permettent à l'application de communiquer avec le serveur, d'exécuter la tâche correctement et de visualiser les résultats le cas échéant dans l'application. La section ci-après montre comment mettre en œuvre ces quatre étapes afin d'ajouter des fonctionnalités de géotraitement à l'aide d'ArcGIS Web API for Javascript. Même si les déclarations d'objets, la syntaxe de la méthode et la gestion d'événements varient dans les deux autres API Web, la structure à quatre étapes concerne toutes les API Web. La procédure vous aide à comprendre les pratiques conseillées pour l'utilisation de tâches de géotraitement dans les applications Web.
Utilisation de tâches de géotraitement l'application Javascript
ArcGIS Web API for JavaScript est l'une des API Web d'ArcGIS. Si vous ne connaissez pas l'API JavaScript, consultez le site ArcGIS API for JavaScript. Le site propose de nombreux exemples de code, ainsi que des exemples de géotraitement.
La suite de cette rubrique vous guidera dans les quatre étapes décrites ci-dessus pour inclure des tâches de géotraitement dans des applications Web à l'aide de l'API Javascript d'ArcGIS.
Etape 1 : Initialiser la tâche de géotraitement
Pour initialiser une tâche de géotraitement, vous devez connaître l'URL de la tâche. Le modèle pour une URL de tâche de géotraitement est http://<hôte-arcgis>/<nomservicegéotraitement>/GPServer/<nom-tâchegéotraitement>. Ajoutez le code ci-après à votre application JavaScript pour initialiser une tâche de géotraitement.
Lors de l'initialisation, assurez-vous de définir la propriété outSpatialReference de l'instance de tâche de géotraitement sur la référence spatiale de la carte Web. Les jeux de données des tâches de géotraitement peuvent utiliser une référence spatiale différente et leurs sorties peuvent aussi utiliser une référence spatiale différente. Les applications Web considèrent toutefois que les sorties des tâches ont la même référence spatiale que celle de la carte. Cela peut entraîner un comportement inattendu lors de l'affichage de sorties. Par conséquent, vous devez définir la propriété de référence spatiale en sortie de la tâche de géotraitement. Le serveur renvoie les sorties dans la référence spatiale spécifiée par la propriété outSpatialReference.
Initialiser la tâche de géotraitement
// esri.tasks.gp is required for using Geoprocessor.
// Add it along with other dojo.require statements.
dojo.require(esri.tasks.gp);
/* Step 1: Initialize Geoprocessing Task as a global variable.
That is, declare the variable outside a function definition
since we will be using gpTask variable in other methods */
var gpTaskUrl="http://myserver/ArcGIS/rest/services/" +
"BufferPoints/GPServer/BufferPoints";
var gpTask = new esri.tasks.Geoprocessor(gpTaskUrl);
// Set output spatial reference property to map's spatial reference.
// myMap is assumed to be an instance of map container esri.map.
gpTask.outSpatialReference=myMap.spatialReference;
Etape 2 : Configurer les paramètres de la tâche
Lors de l'exécution d'une tâche de géotraitement, l'application Web doit fournir les valeurs de paramètres de la tâche de géotraitement. Pour connaître les besoins en paramètres d'une tâche, copiez et collez l'URL de la tâche dans la barre d'adresse d'un navigateur Web pour ouvrir la page Tâche du répertoire de services. La page Tâche répertorie tous les paramètres de tâches et leurs types de données. Elle comporte également l'URL de l'Aide où vous pouvez trouver davantage d'informations concernant les fonctionnalités de géotraitement, leur accès et leur utilisation.
Pour en savoir plus sur les propriétés des paramètres de tâches
Pour qu'une tâche s'exécute correctement, vous devez spécifier les valeurs de tous les paramètres en entrée requis (esriGPParameterTypeRequired) de la tâche décrits dans la page Tâche. Les valeurs de la tâche proviennent généralement d'une ou plusieurs des sources suivantes :
- les valeurs saisies par l'utilisateur à l'aide de l'application Web,
- les valeurs provenant de l'une des couches d'entités de carte Web ou de couches graphiques,
- les résultats d'autres tâches, telles que requête, tâches d'itinéraire, etc.,
- les résultats d'autres tâches de géotraitement.
Le code JavaScript ci-après est un exemple de création d'entités en entrée, un paramètre GPFeatureRecordsetLayer provenant de FeatureLayer ajouté à la carte Web, et de création de buffDistance, un paramètre GPLinearUnit dérivé d'un texte dojo en entré avec id="distance". Il est supposé que l'utilisateur saisit la valeur de distance. Une fois les paramètres de tâche créés, une construction JSON, avec des paires nom-valeur de paramètres, est créée et envoyée au serveur.
Paramètres de configuration
//Step 2: Setup Parameters of the task
function setupParameters(){
/* The code below assumes that the web map
has a featurelayer with id fLayer. */
// Get Input Parameter 1 : GPFeatureRecordSetLayer from fLayer.
var inputFeatures = new esri.tasks.FeatureSet();
inputFeatures.features = map.getLayer("fLayer").graphics;
inputFeatures.fields=map.getLayer("fLayer").fields;
// Get Input Parameter 2 : GPLinearunit from a dojo UI element
var buffDistance = new esri.tasks.LinearUnit();
buffDistance.distance=dojo.byId(“distance”).value;
buffDistance.units=”esriMiles”;
// Create Parameter list with name-value pairs.
// Names must match the parameter name in Task page.
// Parameters must be in the same-order as in Task page.
var params= {"Input_Features":inputFeatures,
"Distance":buffDistance};
// Return name-value pairs of parameters
return params;
}
Etape 3 : Exécuter la tâche
Pour exécuter une tâche, faites appel à la méthode execute ou submitJob de l'instance du géoprocesseur (gpTask) basée sur l'opération de tâche de géotraitement prise en charge. Vous trouverez l'opération de tâche prise en charge sur la page Tâche. Les rubriques Opération de tâche : execute et Opération de tâche : submitJob explique la différence entre les opérations et la communication entre le serveur et le client pour l'opération.
Opération de tâche : execute
Si l'opération de tâche prise en charge est Exécuter la tâche, vous devez faire appel à la méthode execute de l'instance du géoprocesseur et transmettre les paramètres. Vous devez définir les gestionnaires d'événements qui vont mener l'application à la suite des requêtes abouties et échouées. L'événement onExecuteComplete est déclenché lorsque la tâche s'exécute correctement et renvoie le résultat et les messages de géotraitement. L'événement onError est déclenché lorsque l'exécution d'une tâche échoue. Le serveur renvoie alors une instance d'erreur avec un code d'erreur HTML et des messages de géotraitement, le cas échéant.
Opération de tâche : execute
function myGPExecuteTask(){
// Get params from setupParameters method described above.
var params=setupParameters();
// Setup onTaskSuccess and onTaskFailure event handlers.
dojo.connect(gpTask, "onExecuteComplete",onTaskSuccess);
dojo.connect(gpTask, "onError",onTaskFailure);
// Execute gpTask with params
gpTask.execute(params);
}
// Callback when the Task operation succeeded
function onTaskSuccess(results, messages) {
// Do something with the results...
// More info on rendering the results in section below
}
// Handler that is invoked when the Task operation has failed
function onTaskFailure(error) {
// Report error
alert("Error:"+ error);
}
Opération de tâche : submitJob
Si l'opération de tâche prise en charge est submitJob, vous devez faire appel à la méthode Geoprocessor.submitJob et transmettre les paramètres. Dans le cas de submitJob, trois événements sont déclenchés, qui doivent être gérés correctement dans l'application Web.
onStatusUpdate | Lorsque l'état actuel de la tâche est reçu |
onJobComplete | Lorsque la tâche a été exécutée correctement |
onError | Lorsque la tâche échoue |
- onStatusUpdate : A la différence d'execute, dans le cas de submitJob, le serveur crée une tâche et attribue un jobId. Les opérations submitJob n'avertissent pas le client quand une tâche est terminée, il appartient donc au client de vérifier avec le service pour déterminer l'état de la tâche. Les applications Web envoient par défaut des requêtes d'état au serveur toutes les secondes pour déterminer l'état de la tâche. A chaque réception de la réponse d'état, l'événement onStatusUpdate est déclenché. Vous pouvez augmenter ou réduire l'intervalle de vérification de l'état grâce à la méthode Geoprocessor.setUpdateDelay le cas échéant. L'événement onStatusUpdate est déclenché à chaque fois que l'état de la tâche est vérifié. Le gestionnaire d'événements reçoit une instance JobInfo contenant l'identifiant de la tâche, l'état de la tâche et tous les messages GPMessages renvoyés par le serveur. Ces informations permettent de suivre l'avancement de la tâche.
- onJobComplete : Lorsque JobInfo.jobStatus = STATUS_SUCCEEDED, l'événement onJobComplete est déclenché. Les résultats ne sont pas envoyés automatiquement au client à la fin de l'opération, mais ils sont stockés sur le serveur, et le client doit envoyer une requête pour les extraire. Dans le gestionnaire d'événements onJobComplete vous pouvez appeler la méthode Geoprocessor.getResultData et obtenir les résultats. Chaque paramètre en sortie est une ressource indépendante, et la méthode getResultData de l'instance de géoprocesseur doit être appelée pour chaque paramètre en sortie de la tâche. Vous devez fournir le jobId renvoyé par le gestionnaire d'événements et le nom du paramètre en sortie de la méthode getResultData. Vous devez également créer un gestionnaire d'événements pour l'événement onGetResultDataComplete. L'événement onGetResultDataComplete est déclenché lorsque la valeur de résultat du paramètre en sortie est reçue par l'application Web.
- onError : l'événement onError est déclenché lorsqu'une demande ou une demande d'état submitJob expire ou si les tâches de géotraitement échouent. L'événement renverra une instance d'erreur avec un code d'erreur HTML.
Opération de tâche : submitJob
function myGPSubmitJob(){
// Get params from setupParameters method described above.
var params=setupParameters();
// Setup event handlers.
dojo.connect(gpTask, "onJobComplete",onTaskComplete);
dojo.connect(gpTask, "onError",onTaskFailure);
dojo.connect(gpTask, "onStatusUpdate",onTaskStatus);
gpTask.submitJob(params);
}
// Event handler for onJobComplete event
function onTaskComplete(jobInfo) {
/* Get the value of an output parameter Buffer_polygons
using getResultData. The name of the output
may vary in your gpTask*/
dojo.connect(gpTask, "onGetResultDataComplete",
onTaskResultComplete);
gpTask.getResultData(jobInfo.jobId,
"Buffer_polygons");
}
// Event handler for onStatusUpdate event
function onTaskStatus(jobInfo) {
//write status to console to help debugging
console.log(jobInfo.jobStatus);
}
// Event handler for onError event
function onTaskFailure(error) {
// Report error
alert("Error:"+ error);
}
Etape 4 : Afficher les résultats
Les résultats d'une tâche de géotraitement sont affichés en fonction du type de données du paramètre en sortie.
GPFeatureRecordSetLayer | Les entités en sortie sont généralement affichées dans la carte Web en tant que couche de graphiques pour afficher le résultat du géotraitement. |
GPRecordSet | Les enregistrements en sortie sont affichées dans une grille, ou les valeurs sont utilisées pour créer des diagrammes et des graphiques. |
GPRasterDataLayer | Les rasters en sortie peuvent être téléchargés mais ne peuvent pas être affichés sur la carte. Vous pouvez toutefois utiliser un service de carte obtenu pour visualiser les données raster. En savoir plus sur Service de carte obtenu et Utilisation de services de carte obtenus dans des applications Web |
GPDataFile | Il est possible de télécharger les fichiers en sortie, ou les fichiers tels que .gpx et .csv peuvent être gérés par l'application Web. |
GPBoolean, GPDataFile, GPLong, GPDouble, GPString, GPLinearUnit, GPDate | Les sorties s'affichent à l'aide de HTML ou d'autres widgets. |
Résultats du gestionnaire d'événements onExecuteComplete
Dans le cas de l'opération execute, l'événement onExecuteComplete renvoie les résultats et les messages de la tâche de géotraitement. L'instance de résultats est un tableau de tous les paramètres en sortie de la tâche, et les entrées du tableau sont toujours dans l'ordre présenté dans la page Tâche. Les valeurs des paramètres peuvent donc être identifiées par leur position dans le tableau. Chaque paramètre en sortie du tableau possède un nom, un type de données et une valeur. Le code ci-après montre comment accéder au premier paramètre en sortie dans les résultats. Dans ce code, le paramètre en sortie est connu comme une sortie GPFeatureRecordSetLayer et par conséquent le code montre comment l'afficher en tant que couche de graphiques et comment l'ajouter à l'application Web.
Affichage des résultats à partir du gestionnaire d'événements onExecuteComplete
function onTaskSuccess(results, messages) {
/* Retrieve the output parameter value based
on its position from the result instance.
In the case shown below, the output is the first output
parameter of the task and it
is a GPFeatureRecordSetLayer.*/
var featureset = results[0].value;
// Create a graphics layer with features
var taskResultLayer= new esri.layers.GraphicsLayer
({id:"MyGPExecuteResultLayer"});
// Create a symbol based on the geometry.
// The geometry is assumed to be polygons in the code below
var simplePolySymbol = new esri.symbol.SimpleFillSymbol();
simplePolySymbol.setOutline(new esri.symbol.SimpleLineSymbol(
esri.symbol.SimpleLineSymbol.STYLE_SOLID,
new dojo.Color([0,0,0,0.5]), 1));
simplePolySymbol.setColor(new dojo.Color([255,0,0,0.7]));
// Create graphics from features and add it graphicslayer
dojo.forEach(featureset.features,function(feature){
feature.setSymbol(simplePolySymbol);
//Add feature to the graphics layer
taskResultLayer.add(feature);});
}
// Add graphicslayer to webmap
// myMap is assumed to be an instance of map container esri.map
myMap.addLayer(taskResultLayer)
}
Résultats du gestionnaire d'événements onGetResultDataComplete
L'événement onGetResultDataComplete fournit une instance de résultat. A la différence des résultats de l'événement onExecuteComplete, l'instance de résultat contient des valeurs uniquement pour le paramètre requis. Le résultat du paramètre contient le nom, le type de donnée et la valeur du paramètre requis. La valeur du paramètre est extraite du résultat et utilisée selon les besoins. Le code ci-après illustre le rendu des résultats d'un paramètre GPFeatureRecordSetLayer à partir d'une instance de résultat de paramètre.
Résultats du gestionnaire d'événements onGetResultDataComplete
function onTaskResultComplete(paramResult) {
// Retrieve the value of the parameter from the paramresult
var featureSet = paramResult.value;
// Create a graphics layer with features
var taskResultLayer= new esri.layers.GraphicsLayer
({id:"MyGPSubmitJobResultLayer"});
// Create a symbol based on the geometry.
// The geometry is assumed to be polygons in the code below
var simplePolySymbol = new esri.symbol.SimpleFillSymbol();
simplePolySymbol.setOutline(new esri.symbol.SimpleLineSymbol(
esri.symbol.SimpleLineSymbol.STYLE_SOLID,
new dojo.Color([0,0,0,0.5]), 1));
simplePolySymbol.setColor(new dojo.Color([255,0,0,0.7]));
// Create graphics from features and add it graphicslayer
dojo.forEach(featureset.features,function(feature){
feature.setSymbol(simplePolySymbol);
//Add feature to the graphics layer
taskResultLayer.add(feature);});
}
// Add graphicslayer to webmap
// myMap is assumed to be an instance of map container esri.map.
myMap.addLayer(taskResultLayer)
}
API Flex et Silverlight
Les quatre étapes décrites ci-dessus pour les applications JavaScript concernent aussi les API Flex et Silverlight. Vous trouverez des exemples de code pour l'utilisation de tâches de géotraitement dans API Flex et API Silverlight dans leurs SDK en ligne respectifs.