Verwenden von Geoverarbeitungs-Tasks in Webanwendungen

Anhand der ArcGIS API for JavaScript können Webbrowser mit ArcGIS Server-Services kommunizieren, geographische Informationen darstellen und Analysen durchführen.

Es muss keine Bibliothek heruntergeladen werden, da der Zugriff über eine Web-URL erfolgt. Die ArcGIS API for JavaScript-Dokumentation bietet Codebeispiele, Lernprogramme, Handbücher und detailliertes Referenzmaterial.

Geoverarbeitungs-Tasks in Webanwendungen

Mit Geoverarbeitungsservices können Sie Webanwendungen Geoverarbeitungs- und Datenanalysefunktionen hinzufügen. Jeder Geoverarbeitungsservice umfasst einen oder mehrere Tasks für die Geoverarbeitung.

Bei der Navigation durch das ArcGIS Server-Services-Verzeichnis können Sie nach Geoverarbeitungsservices, den Tasks im Service sowie den Parametern und Eigenschaften der einzelnen Tasks suchen. Das Thema zu Geoverarbeitungs-REST-Services enthält Informationen zur Hierarchie von REST-Ressourcen, und im Thema Einführung in Geoverarbeitungs-Tasks werden weitere Informationen zu Geoverarbeitungs-Tasks, den zugehörigen Parametern und dem Zugriff auf diese Parameter zur Verfügung gestellt. Die ArcGIS API for JavaScript bietet praktische Objekte und Methoden, um auf Geoverarbeitungs-Tasks zuzugreifen und die Funktionen auszuführen.

Führen Sie die folgenden vier Schritte aus, um eine von einem Task in Ihrer Webanwendung bereitgestellte Geoverarbeitungsfunktion hinzuzufügen:

1. Initialisieren des Geoverarbeitungs-Tasks
2. Festlegen der Task-Parameter
3. Ausführen des Tasks
4. Rendern der Ergebnisse

Diese vier Schritte ermöglichen es der Anwendung, mit dem Server zu kommunizieren, den Task erfolgreich auszuführen und die Ergebnisse gemäß den jeweiligen Anforderungen in der Anwendung visuell darzustellen.

Verwenden von Geoverarbeitungs-Tasks in der ArcGIS API for JavaScript

Mit den folgenden vier Schritten können Sie Geoverarbeitungsfunktionen erfolgreich über die ArcGIS API for JavaScript hinzufügen.

Schritt 1: Initialisieren des Geoverarbeitungs-Tasks

Zum Initialisieren eines Geoverarbeitungs-Tasks müssen Sie die Task-URL kennen. Die Struktur für eine Geoverarbeitungs-Task-URL lautet https://<arcgis-host>/<gpservicename>/GPServer/<gptask-name>. Fügen Sie Ihrer JavaScript-Anwendung den nachfolgend dargestellten Code hinzu, um einen Geoverarbeitungs-Task zu initialisieren.

Achten Sie bei der Initialisierung darauf, für die Eigenschaft outSpatialReference der Geoverarbeitungs-Task-Instanz den Raumbezug der Webkarte anzugeben. Die Datasets von Geoverarbeitungs-Tasks können einen unterschiedlichen Raumbezug aufweisen, sodass sich auch die Ausgaben in unterschiedlichen Raumbezügen befinden können. Bei Webanwendungen wird jedoch davon ausgegangen, dass die Task-Ausgaben denselben Raumbezug aufweisen wie die Karte. Entsprechend kann es bei der Darstellung von Ausgaben zu unerwartetem Verhalten kommen. Aus diesem Grund müssen Sie die Ausgabe-Raumbezugseigenschaft des Geoverarbeitungs-Tasks festlegen. Die Ausgaben werden vom Server in dem Raumbezug zurückgegeben, der in der Eigenschaft outSpatialReference angegeben ist.

Initialisieren des Geoverarbeitungs-Tasks

// 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;

Schritt 2: Festlegen der Task-Parameter

Bei der Ausführung eines Geoverarbeitungs-Tasks müssen die Parameterwerte für den Geoverarbeitungs-Task von der Webanwendung angegeben werden. Die Parameteranforderungen eines Tasks erhalten Sie, indem Sie die Task-URL kopieren und in die Adresszeile eines Webbrowsers einfügen, um die Task-Seite des Services-Verzeichnisses zu öffnen. Auf der Task-Seite werden alle Task-Parameter mit den zugehörigen Datentypen aufgeführt. Auf der Task-Seite gibt es außerdem eine Hilfe-URL, über die Sie weitere Informationen zu Geoverarbeitungsfunktionen sowie zu Zugriff und Verwendung finden.

Weitere Informationen zu Task-Parameter-Eigenschaften

Zur erfolgreichen Ausführung des Tasks müssen Sie die Werte aller erforderlichen Eingabeparameter (esriGPParameterTypeRequired) des Tasks entsprechend der Beschreibung auf der Task-Seite angeben. Normalerweise stammen die Werte des Tasks aus einer oder mehreren der folgenden Quellen:

• vom Benutzer über die Webanwendung eingegebene Werte
• Werte aus einem der aktuellen Feature-Layer oder Grafik-Layer der Webkarte
• Ergebnisse anderer Tasks wie Abfragen, Routen-Tasks usw.
• Ergebnisse von anderen Geoverarbeitungs-Tasks

Der nachfolgend aufgeführte JavaScript-Code zeigt ein Beispiel zum Erstellen von Eingabe-Features, einen GPFeatureRecordsetLayer-Parameter aus einem FeatureLayer, der der Webkarte hinzugefügt wurde, und zum Erstellen von buffDistance, einem GPLinearUnit-Parameter, der aus einer Dojo-Texteingabe mit einer id="distance" abgeleitet wird. Es wird davon ausgegangen, dass der Benutzer den Entfernungswert interaktiv eingibt. Nach der Erstellung der Task-Parameter wird ein JSON-Konstrukt mit Name-Wert-Paaren der Parameter erstellt und an den Server gesendet.

Setup-Parameter

//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;
}

Hinweis:

Für die Parameter GPFeatureRecordSetLayer und GPRecordSetLayer wird ein Standardschema vom Task definiert. Das Schema für die Parameter finden Sie auf der Task-Seite. Ein Schema eines GPFeatureRecordSetLayer besteht aus Geometrie, Raumbezug, Feldern und Features. Es empfiehlt sich, sicherzustellen, dass die GPFeatureRecordSetLayer-Parameter über alle im Schema definierten Eigenschaften verfügen, um brauchbare Ergebnisse zu erhalten.

Schritt 3: Ausführen des Tasks

Verwenden Sie die Methode execute oder submitJob der Geoprozessor-Instanz (gpTask), abhängig vom unterstützten Vorgang des Geoverarbeitungs-Tasks, um einen Task auszuführen. Den unterstützten Vorgang des Tasks finden Sie auf der Task-Seite. In den Themen Taskvorgang "execute" und Taskvorgang "submitJob" wird der Unterschied zwischen den Vorgängen und der Server- und Clientkommunikation für die Vorgänge erläutert.

Taskvorgang "execute"

Wenn der unterstützte Vorgang des Tasks "Task ausführen" ist, muss die execute-Methode der Geoprozessor-Instanz verwendet und die Parameter müssen übergeben werden. Sie müssen Ereignishandler definieren, um die Anwendung bei erfolgreichen und fehlerhaften Anfragen zu steuern. Das Ereignis onExecuteComplete wird aufgerufen, wenn der Task erfolgreich ausgeführt wird und das Ergebnis sowie Geoverarbeitungs-Meldungen ausgegeben werden. Das Ereignis onError wird aufgerufen, wenn eine Task-Ausführung fehlerhaft ist. Wenn der Task fehlschlägt, gibt der Server ggf. eine Fehlerinstanz mit HTML-Fehlercode und Geoverarbeitungsmeldungen aus.

Taskvorgang "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); 
}

Taskvorgang "submitJob"

Wenn der unterstützte Vorgang des Tasks der Vorgang submitJob ist, muss die Geoprocessor.submitJob-Methode verwendet werden und die Parameter müssen übergeben werden. Bei submitJob werden drei Ereignisse aufgerufen, die in der Webanwendung entsprechend verarbeitet werden müssen:

onStatusUpdate	Bei Empfang des aktuellen Auftragsstatus
onJobComplete	Bei erfolgreicher Fertigstellung des Auftrags
onError	Bei Fehlschlagen des Auftrags

• onStatusUpdate: Im Gegensatz zu execute wird bei submitJob ein Auftrag vom Server erstellt und eine jobId zugewiesen. Bei submitJob-Vorgängen erhält der Client keine Benachrichtigung, wenn ein Auftrag abgeschlossen wurde, sodass der Client selbst beim Service den Status des Auftrags prüfen muss. Standardmäßig werden jede Sekunde Statusanfragen von Webanwendungen an den Server gesendet, um den Status des Tasks zu bestimmen. Bei jedem Eingang einer Statusantwort wird das Ereignis onStatusUpdate aufgerufen. Sie können das Statusprüfintervall ggf. über die Geoprocessor.setUpdateDelay-Methode verlängern oder verkürzen. Das Ereignis onStatusUpdate wird bei jeder Prüfung des Auftragsstatus aufgerufen. Der Ereignishandler erhält eine JobInfo-Instanz mit der Auftrags-ID, dem Auftragsstatus und allen vom Server zurückgegebenen GPMessages. Mit diesen Informationen können Sie den Fortschritt des Tasks nachverfolgen.
• onJobComplete: Bei JobInfo.jobStatus = STATUS_SUCCEEDED wird das Ereignis onJobComplete aufgerufen. Die Ergebnisse werden nicht automatisch an den Kunden zurückgegeben, wenn der Vorgang abgeschlossen ist. Stattdessen werden sie auf dem Server gespeichert; der Kunde muss eine Anfrage senden, um sie abzurufen. Die Ergebnisse können im Ereignishandler onJobComplete durch Aufruf der Geoprocessor.getResultData-Methode abgerufen werden. Jeder Ausgabeparameter ist eine unabhängige Ressource, deshalb muss die getResultData-Methode der Geoprozessor-Instanz für jeden Ausgabeparameter des Tasks aufgerufen werden. Sie müssen die vom Ereignishandler zurückgegebene jobId und den Namen des Ausgabeparameters in der getResultData-Methode angeben. Außerdem müssen Sie einen Ereignishandler für das Ereignis onGetResultDataComplete erstellen. Das Ereignis onGetResultDataComplete wird aufgerufen, wenn der Ergebniswert des Ausgabeparameters von der Webanwendung empfangen wird.
• onError: Das Ereignis onError wird aufgerufen, wenn für eine submitJob-Anfrage oder Statusanfrage ein Timeout auftritt oder der Geoverarbeitungs-Task fehlgeschlagen ist. Es wird eine Fehlerinstanz mit HTML-Fehlercode vom Ereignis zurückgegeben.

Weitere Informationen zu Aufträgen, Auftrags-IDs, Auftragsstatus und der Server-Client-Kommunikation in submitJob-Vorgängen finden Sie unter Taskvorgang "submitJob". Der nachfolgende Code zeigt, wie Sie einen Auftrag an den Server senden und die Ereignisse verarbeiten können.

Taskvorgang "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); 
}

Schritt 4: Rendern der Ergebnisse

Die Ergebnisse eines Geoverarbeitungs-Tasks werden abhängig vom Datentyp des Ausgabeparameters gerendert.

GPFeatureRecordSetLayer	Die Ausgabe-Features werden auf der Webkarte normalerweise als Grafik-Layer dargestellt, um das Geoverarbeitungsergebnis anzuzeigen.
GPRecordSet	Die Ausgabedatensätze werden in einem Gitternetz angezeigt, oder es werden Diagramme und Schaubilder mit den Werten erstellt.
GPRasterDataLayer	Ausgabe-Raster können heruntergeladen, jedoch nicht auf der Karte dargestellt werden. Sie können die Raster-Daten jedoch mit einem Kartenservice des Ergebnisses darstellen. Weitere Informationen finden Sie unter Kartenservice des Ergebnisses und Verwenden eines Kartenservice des Ergebnisses in Webanwendungen.
GPDataFile	Ausgabedateien können heruntergeladen und Dateien wie .gpx und .csv von der Webanwendung verarbeitet werden.
GPBoolean, GPDataFile, GPLong, GPDouble, GPString, GPLinearUnit, GPDate	Die Ausgabe wird in HTML oder mit anderen Widgets angezeigt.

Ergebnisse aus dem Ereignishandler onExecuteComplete

Beim Vorgang execute werden vom Ereignis onExecuteComplete die Ergebnisse und Meldungen des Geoverarbeitungs-Tasks zurückgegeben. Die Ergebnisinstanz ist ein Array aus allen Ausgabeparametern des Tasks, und die Einträge im Array befinden sich immer in derselben Reihenfolge wie auf der Task-Seite. Entsprechend können die Parameterwerte über ihre Position im Array identifiziert werden. Jeder Ausgabeparameter im Array verfügt über einen Parameternamen, einen Datentyp und einen Wert. Im nachfolgenden Code wird der Zugriff auf den ersten Ausgabeparameter in den Ergebnissen dargestellt. Im folgenden Code ist der Ausgabeparameter eine GPFeatureRecordSetLayer-Ausgabe, deshalb gibt der Code an, wie diese als Grafik-Layer gerendert und zur Webanwendung hinzugefügt wird.

Rendern von Ergebnissen aus dem Ereignishandler "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)
}

Ergebnisse aus dem Ereignishandler "onGetResultDataComplete"

Das Ereignis onGetResultDataComplete gibt eine Ergebnisinstanz an. Im Gegensatz zu den Ergebnissen aus dem Ereignis onExecuteComplete verfügt die Ergebnisinstanz nur über Werte für den angeforderten Parameter. Das Parameterergebnis enthält den Namen, Datentyp und Wert des angeforderten Parameters. Der Parameterwert wird aus dem Ergebnis abgerufen und nach Bedarf verwendet. Im nachfolgenden Code wird das Rendern der Ergebnisse eines GPFeatureRecordSetLayer-Parameters von einer Parameter-Ergebnisinstanz dargestellt.

Ergebnisse aus dem Ereignishandler "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) }