Utilisation de tâches de géotraitement dans des applications Web

ArcGIS API for JavaScript permet aux navigateurs Web de communiquer avec les services ArcGIS Server, d'afficher des données géographiques et d’effectuer des analyses.

Il n'est pas nécessaire de télécharger la bibliothèque puisqu'elle est accessible via une URL Web. La ArcGIS API for JavaScriptdocumentation propose des exemples de code, des didacticiels, des guides et des références détaillées.

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 utilisant des services de géotraitement. Chaque service de géotraitement comporte une ou plusieurs tâches de géotraitement.

Parcourez le répertoire de services ArcGIS Server, pour trouver les 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 sur la hiérarchie des ressources REST, et la rubrique Présentation des tâches de géotraitement fournit des informations sur les tâches de géotraitement, leurs paramètres et la façon d'y accéder. ArcGIS API for JavaScript offre 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 :

1. Initialisation de la tâche de géotraitement.
2. Configuration des paramètres pour la tâche.
3. Exécution de la tâche.
4. 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.

Utilisation des tâches de géotraitement dans ArcGIS API for JavaScript

Ces quatre étapes vous permettent d’ajouter des fonctions de géotraitement utilisant ArcGIS API for JavaScript.

Etape 1 : initialisation de 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 d'une URL de tâche de géotraitement est https://<arcgis-host>/<gpservicename>/GPServer/<gptask-name>. Ajoutez le code ci-après à votre application JavaScript pour initialiser une tâche de géotraitement.

Lors de l'initialisation, veillez à 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="https://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 : configuration des paramètres pour 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;
}

Remarque :

Les paramètres GPFeatureRecordSetLayer et GPRecordSetLayer ont une structure par défaut définie par la tâche. Vous trouverez la structure des paramètres sur la page Tâches. Une structure de paramètre GPFeatureRecordSetLayer est constitué d'une géométrie, d'une référence spatiale, de champs et d'entités. Pour obtenir de meilleurs résultats, il est recommandé de vérifier que les paramètres GPFeatureRecordSetLayer possèdent toutes les propriétés définies dans la structure.

Etape 3 : exécution de 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 et le client doit vérifier l'état de la tâche auprès du service. 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.

Pour en savoir plus sur les tâches, les ID de tâche, l'état des tâches et la communication serveur-client dans les opérations submitJob reportez-vous à la rubrique Opération de tâche : submitJob. Le code suivant illustre la façon dont vous pouvez soumettre une tâche au serveur et gérer les événements.

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 : affichage des 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 le Service de carte obtenu et l'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 une matrice de tous les paramètres en sortie de la tâche, et les entrées de la matrice apparaissent toujours dans l'ordre présenté sur 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 reconnu comme une sortie GPFeatureRecordSetLayer et par conséquent le code indique 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) }