ArcGIS Web Mapping-APIs
Ein Web-GIS-Framework 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, das Rendern (Darstellen) geographischer Daten sowie die Durchführung von Analysen. Die ArcGIS-Web-APIs werden unter Verwendung von JavaScript zur Verfügung gestellt. ArcGIS-APIs und -Viewer für Flex und Silverlight werden nicht mehr weiterentwickelt. Weitere Informationen finden Sie im Abschnitt Flex- und Silverlight-API.
Für die JavaScript-APIs besuchen Sie die Website ArcGIS API for JavaScript. Es muss keine Bibliothek heruntergeladen werden, da über eine Web-URL auf die Bibliothek zugegriffen wird. Die Website bietet Codebeispiele, Lernprogramme, Handbücher und detailliertes Referenzmaterial.
Geoverarbeitungs-Tasks in Webanwendungen
Mit ArcGIS-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 Services-Verzeichnis eines ArcGIS-Servers können Sie nach Geoverarbeitungsservices, 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 des Geoverarbeitungs-Tasks
- Festlegen der Task-Parameter
- Ausführen des Tasks
- 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. 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 Website ArcGIS API for JavaScript. Die Website 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. Die Struktur für eine Geoverarbeitungs-Task-URL lautet http://<ArcGIS-Host>/<GP-Servicename>/GPServer/<GP-Task-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="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: 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.
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) }Flex- und Silverlight-API
Die ArcGIS-APIs und -Viewer für Flex und Silverlight werden nicht weiterentwickelt. Auch wenn bis zum Juni 2016 noch technischer Support für die beiden APIs und Viewer besteht, wird die Wartung dieser Produkte eingestellt. Kunden, die diese Produkte zum Entwickeln verwenden, sollten die Weblösungen in Betracht ziehen, die auf JavaScript oder HTML5 basieren. Weitere Informationen finden Sie unter: Flex and Silverlight API Support Plan.