Verwenden von Geoverarbeitungs-Tasks in Webanwendungen
ArcGIS Web Mapping-APIs
Ein Framework für Web-GIS unterstützt Sie bei den ersten grundlegenden Schritten mit GIS-basierten Webanwendungen. ArcGIS-Web-APIs ermöglichen die Kommunikation zwischen Webbrowsern und ArcGIS for Server GIS Services und das Rendern (Darstellen) geographischer Daten sowie die Durchführung von Analysen. Die ArcGIS-Web-APIs werden in drei verschiedenen Ausführungen angeboten. Hierbei handelt es sich um:
- ArcGIS API for JavaScript
- ArcGIS API for Flex
- ArcGIS API for Microsoft Silverlight/WPF
Die drei APIs verfügen über ähnliche Funktionen, sie wurden jedoch für unterschiedliche Programmiersprachen entwickelt. Um Webanwendungen mit Flex oder Silverlight entwickeln zu können, müssen Sie die Bibliotheken auf der Website ArcGIS for Developers herunterladen. Bei JavaScript-Web-APIs muss keine Bibliothek heruntergeladen werden, da über eine Web-URL auf die Bibliothek zugegriffen wird. Die ArcGIS for Developers-Website bietet Codebeispiele, Lernprogramme, Handbücher und detailliertes Referenzmaterial für die ArcGIS Web-APIs.
Geoverarbeitungs-Tasks in Webanwendungen
Mit ArcGIS-Geoverarbeitungs-Services können Sie Webanwendungen Geoverarbeitungs- und Datenanalysefunktionen hinzufügen. Jeder Geoverarbeitungs-Service umfasst einen oder mehrere Tasks für die Geoverarbeitung. Bei der Navigation durch das Services-Verzeichnis eines ArcGIS-Servers können Sie nach Geoverarbeitungs-Services, den Tasks im Service und 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 Web-APIs bieten 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:
- Initialisieren Sie den Geoverarbeitungs-Task.
- Richten Sie Parameter für den Task ein.
- Führen Sie den Task aus.
- Rendern Sie die 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. Im folgenden Abschnitt wird die Umsetzung der vier Schritte erläutert, um erfolgreich Geoverarbeitungsfunktionen mit ArcGIS Web API for JavaScript hinzuzufügen. Die Objektdeklarationen, Methodensyntax und Ereignisverarbeitung sind in den anderen beiden Web-APIs zwar anders, das Muster aus vier Schritten ist jedoch in allen Web-APIs gleich. Anhand dieser Schritte können Sie die Empfehlungen für die Verwendung von Geoverarbeitungs-Tasks in Webanwendungen nachvollziehen.
Verwenden von Geoverarbeitungs-Tasks in der JavaScript-Anwendung
Die ArcGIS Web API for JavaScript ist eine der verfügbaren ArcGIS-Web-APIs. Wenn Sie die JavaScript-API noch nicht kennen, besuchen Sie die ArcGIS API for JavaScript-Site. Die Site enthält viele Codebeispiele und Sie können nach Beispielen für Geoverarbeitung suchen.
In den restlichen Abschnitten dieses Themas werden die vier oben beschriebenen Schritte vorgestellt, mit denen Geoverarbeitungs-Tasks mit der ArcGIS-JavaScript-API in Webanwendungen aufgenommen werden können.
Schritt 1: Initialisieren des Geoverarbeitungs-Tasks
Zum Initialisieren eines Geoverarbeitungs-Tasks müssen Sie die Task-URL kennen. Ein Muster einer Geoverarbeitungs-Task-URL ist http://<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, die Eigenschaft outSpatialReference der Geoverarbeitungs-Task-Instanz zum Raumbezug der Webkarte hinzuzufügen. 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="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;
Schritt 2: Einrichten 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 angezeigte 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 eine JSON-Konstruktion 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 Task
Verwenden Sie die Methode execute oder submitJob der Geoprozessor-Instanz (gpTask), abhängig von der unterstützten Operation des Geoverarbeitungs-Tasks, um einen Task auszuführen. Die unterstützte Operation des Tasks finden Sie auf der Task-Seite. In den Themen Task-Operation: ausführen und Task-Operation: submitJob wird der Unterschied zwischen den Operationen und der Server- und Clientkommunikation für die Operation erläutert.
In den Themen Task-Operation: execute
Wenn die unterstützte Operation des Tasks der Execute-Task ist, müssen Sie die Parameter mit der execute-Methode der Geoprozessor-Instanz weitergeben. 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.
In den Themen Task-Operation: 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);
}
In den Themen Task-Operation: submitJob
Wenn die unterstützte Operation des Tasks submitJob ist, müssen Sie die Parameter mit der Geoprocessor.submitJob-Methode weitergeben. 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-Operationen 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 Client zurückgegeben, wenn die Operation 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 eine submitJob-Anfrage oder Statusanfrage abläuft oder der Geoverarbeitungs-Task fehlgeschlagen ist. Es wird eine Fehlerinstanz mit HTML-Fehlercode vom Ereignis zurückgegeben.
In den Themen Task-Operation: 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 des Ergebnisses
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 Geoverarbeitungs-Ergebnis 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 Karten-Service des Ergebnisses darstellen. Weitere Informationen finden Sie unter Karten-Service des Ergebnisses und Verwenden eines Karten-Service 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
Bei der Operation 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)
}
Flex- und Silverlight-API
Die vier oben beschriebenen Schritte für JavaScript-Anwendungen gelten auch für Flex- und Silverlight-APIs. Code-Beispiele für die Verwendung von Geoverarbeitungs-Tasks in der Flex-API und Silverlight-API finden Sie in den entsprechenden Online-SDKs.