Web アプリケーションでのジオプロセシング タスクの使用
ArcGIS Web マッピング API
Web GIS のフレームワークは GIS ベースの Web アプリケーションを理解する上で参考となります。Web ブラウザは、ArcGIS Web API の利用によって ArcGIS Server の GIS サービスと通信し、地理データをレンダリング（描画）して解析を実行できます。提供される ArcGIS Web API には次の 3 種類があります。
- ArcGIS API for JavaScript
- ArcGIS API for Flex
- ArcGIS API for Microsoft Silverlight/WPF
これらの 3 つの API は同じ機能を備えていますが、それぞれ異なる開発言語を対象としています。Flex または Silverlight を使用して Web アプリケーションの開発を開始するには、ArcGIS Resource Center からライブラリをダウンロードする必要があります。ただし、JavaScript Web API の場合、Web URL を介してライブラリにアクセス可能なため、このライブラリをダウンロードする必要はありません。ArcGIS Resource Center は、ArcGIS Web API の使用を開始するためのサンプルおよび解説書を提供するとともに、ユーザの環境に合った適切な Web API を選択できるようになっています。
Web アプリケーションにおけるジオプロセシング タスク
ArcGIS ジオプロセシング サービスを使用して、ジオプロセシング機能およびデータの解析を Web アプリケーションに追加できます。各ジオプロセシング サービスには、1 つ以上のジオプロセシング タスクが含まれています。ArcGIS Services Directory 内を調べると、ジオプロセシング サービス、ジオプロセシング タスク、およびそのパラメータとプロパティを確認できます。トピック「ジオプロセシング REST サービス」では REST リソースの階層に関する情報を提供し、トピック「ジオプロセシング タスクの概要」ではジオプロセシング タスク、それらのタスク パラメータ、およびタスクへのアクセス方法に関する情報を提供しています。ジオプロセシング タスクにアクセスし機能を実行するための便利なオブジェクトとメソッドが Web API に用意されています。
タスクによって提供されるジオプロセシング機能を Web アプリケーションに追加するには、次の 4 つのステップに従います。
- ジオプロセシング タスクの初期化
- タスクのパラメータの設定
- タスクの実行
- 結果のレンダリング
これらの 4 つのステップを実行すると、アプリケーションでサーバと通信してタスクを正常に実行し、必要に応じて結果を視覚化できます。次のセクションでは、ArcGIS Web API for Javascript を使用してジオプロセシング機能を正常に追加するためにこれらの 4 つのステップを実施する方法を示します。オブジェクトの宣言、メソッドの構文、およびイベント処理は他の 2 つの Web API では異なりますが、4 つのステップのパターンは、すべての Web API に共通し適用することができます。これらのステップは、Web アプリケーションでのジオプロセシング タスクの使用に関するベスト プラクティスを理解するのに役立ちます。
JavaScript アプリケーションでのジオプロセシング タスクの使用
ArcGIS Web API for JavaScript は ArcGIS Web API の 1 つです。JavaScript API を始めて使用する場合は、オンライン SDK のトピック「ArcGIS API for JavaScript の取得」および「ArcGIS JavaScript での最初のアプリケーションの作成」が JavaScript API の使用開始に役立ちます。また、この SDK で、さまざまなジオプロセシング タスクのサンプルおよび概念をいろいろと調べることもできます。このトピックでは、ArcGIS JavaScript API を使用してジオプロセシング タスクを Web アプリケーションに組み込むための上記の 4 つのステップを順番に説明します。
ステップ 1:ジオプロセシング タスクの初期化
ジオプロセシング タスクを初期化するには、タスクの URL を知っておく必要があります。ジオプロセシング タスクの URL のテンプレートは http://<ArcGIS ホスト>/<GP サービス名>/GPServer/<GP タスク名> です。ジオプロセシング タスクを初期化するために、次に示すコードを JavaScript アプリケーションに追加します。
初期化の際は必ず、ジオプロセシング タスク インスタンスの outSpatialReference プロパティを Web マップの空間参照に設定してください。ジオプロセシング タスクのデータセットでは別の空間参照が使用されていることがあるため、タスクの出力でも同様に、別の空間参照が使用される場合があります。ただし、Web アプリケーションは、タスクの出力でマップと同じ空間参照が使用されているとみなします。これが、出力を描画するときの予期しない動作の原因になることがあります。したがって、ユーザは、ジオプロセシング タスクの出力空間参照プロパティを設定する必要があります。サーバは、outSpatialReference プロパティで指定された空間参照で出力を返します。
ジオプロセシング タスクの初期化
//esri.tasks.gp is required for using Geoprocessor.
//Add along with other dojo.require statements.
dojo.require(esri.tasks.gp);
/*Step 1: Initialize Geoprocessing Task as a global variable
(i.e) 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;
ステップ 2:タスク パラメータの設定
ジオプロセシング タスクを実行する際は、Web アプリケーションがジオプロセシング タスクのパラメータ値を提供する必要があります。タスクのパラメータ要件を確認するには、タスクの URL をコピーして Web ブラウザのアドレス バーに貼り付け、Services Directory のタスク ページを開きます。タスク ページには、すべてのタスク パラメータとパラメータのデータ タイプの一覧が表示されます。タスク ページにはまた、ジオプロセシング機能、アクセス、および使用に関する詳細情報を探すことができるヘルプの URL も示されています。
タスクを正常に実行するには、タスク ページの記載どおりに、タスクのすべての必須入力パラメータ（esriGPParameterTypeRequired）の値を指定する必要があります。通常、タスクの値は、次の 1 つ以上のソースから取得されます。
- Web アプリケーションを使用してユーザが入力した値
- 現在の Web マップ フィーチャ レイヤまたはグラフィックス レイヤの 1 つから取得された値
- クエリ、ルート タスクなどの他のタスクの結果
- 他のジオプロセシング タスクの結果
次の JavaScript コードは入力フィーチャの作成例を示しています。FeatureLayer（フィーチャ レイヤ）からの GPFeatureRecordsetLayer パラメータが Web マップに追加されて buffDistance が作成され、GPLinearUnit パラメータが、id="distance" を示す dojo テキスト入力から取得されます。この例では、ユーザが対話的に距離値を入力することを前提としています。タスク パラメータが作成されると、JSON 構造が、パラメータの名前と値のペアを使って構築され、サーバに送信されます。
パラメータの設定
//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 a 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;
}
注意:GPFeatureRecordSetLayer パラメータと GPRecordSetLayer パラメータには、デフォルト スキーマがタスクによって定義されています。これらのパラメータのスキーマはタスク ページで探すことができます。GPFeatureRecordSetLayer のスキーマは、ジオメトリ、空間参照、フィールド、およびフィーチャから構成されます。成功の結果を得るには、GPFeatureRecordSetLayer パラメータのすべてのプロパティがスキーマ内の定義どおりであることを確認するよう推奨します。
ステップ 3:タスクの実行
タスクを実行するには、ジオプロセシング タスクでサポートされている操作に基づいてジオプロセッサ インスタンス（gpTask）の execute または submitJob メソッドを使用する必要があります。タスクでサポートされている操作はタスク ページで確認できます。トピック「タスク操作: 実行」および「タスク操作: ジョブの送信（submitJob）」では、これらの操作の違いと操作におけるサーバ/クライアント通信について説明しています。
タスク操作: 実行
タスクでサポートされている操作がタスク実行である場合は、ジオプロセシング インスタンスの execute メソッドを使用して、パラメータを渡す必要があります。リクエストの成功また失敗時にアプリケーションを操作するイベント ハンドラの定義が必要です。タスクが正常に実行され、結果とジオプロセシング メッセージが返されると、onExecuteComplete イベントが生成されます。タスクの実行に失敗すると、onError イベントが生成されます。タスクが失敗した場合、サーバは、HTML エラー コードとジオプロセシング メッセージ（ある場合）を含むエラー インスタンスを返します。
タスク操作: 実行
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,
//see more info on Rendering the results section
}
//Handler that is invoked when the Task operation has failed
function onTaskFailure(error) {
//report error to the user appropriately
alert("Error:"+ error);
}
タスク操作: ジョブの送信（submitJob）
タスクでサポートされている操作が submitJob 操作である場合は、Geoprocessor.submitJob メソッドを使用して、パラメータを渡す必要があります。submitJobの場合は、次の 3 つのイベントが生成されます。これらのイベントは Web アプリケーションで適切に処理される必要があります。
onStatusUpdate | 現在のジョブのステータスが受信された場合 |
onJobComplete | ジョブが正常に完了した場合 |
onError | ジョブが失敗した場合 |
- onStatusUpdate: execute とは異なり、submitJob の場合は、サーバがジョブを作成して jobId を割り当てます。submitJob 操作では、ジョブが完了したときにクライアントに通知されないため、サービスを確認してジョブのステータスを判断するのはクライアントの役目です。デフォルトでは、Web アプリケーションがステータス リクエストをサーバに毎秒送信して、タスクのステータスを判断します。ステータス応答が受信されるたびに、onStatusUpdate イベントが生成されます。必要に応じて、Geoprocessor.setUpdateDelay メソッドを通じてステータス確認の間隔を長くしたり、短くしたりできます。ジョブのステータスの確認が行われるたびに onStatusUpdate イベントが生成されます。イベント ハンドラは、ジョブ ID、ジョブのステータス、およびサーバによって返された GPMessages を含む JobInfo インスタンスを受け取ります。ユーザは、この情報を使って、タスクの進行状況を追跡できます。
- onJobComplete: JobInfo.jobStatus = STATUS_SUCCEEDED である場合は、onJobComplete イベントが生成されます。操作の完了時に、結果は、自動的にクライアントに返されるのではなく、サーバ上に保存されます。クライアントは、その結果を取得するためにリクエストを送信しなければなりません。onJobComplete イベント ハンドラ内で、Geoprocessor.getResultData メソッドを呼び出して結果を取得できます。各出力パラメータは独立したリソースであるため、ジオプロセシング インスタンスの getResultData メソッドは、タスクの出力パラメータごとに呼び出す必要があります。ユーザは、イベント ハンドラによって返された jobId と出力パラメータの名前を getResultData メソッドに指定する必要があります。また、onGetResultDataComplete イベント用のイベント ハンドラも作成する必要があります。Web アプリケーションで出力パラメータの結果値が受信されると、onGetResultDataComplete イベントが生成されます。
- onError: submitJob リクエストまたはステータス リクエストがタイムアウトになった場合や、ジオプロセシング タスクが失敗した場合は、onError イベントが生成されます。このイベントでは、HTML エラー コードを含むエラー インスタンスが返されます。
タスク操作: ジョブの送信（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 to the user appropriately
alert("Error:"+ error);
}
ステップ 4:結果のレンダリング
ジオプロセシング タスクの結果は、出力パラメータのデータ タイプに基づいてレンダリングされます。
GPFeatureRecordSetLayer | 出力フィーチャは、通常、ジオプロセシング結果を表示するためにグラフィックス レイヤとして Web マップ上に描画されます。 |
GPRecordSet | 出力レコードがグリッドで表示されるか、またはチャートとグラフの作成に値が使用されます。 |
GPRasterDataLayer | 出力ラスタをダウンロードできますが、マップ上には描画できません。ただし、結果マップサービスを使用してラスタ データを視覚化できます。 詳細については、「結果マップ サービス」と「Web アプリケーションでの結果マップ サービスの使用」をご参照ください。 |
GPDataFile | 出力ファイルをダウンロードできるか、*.gpx や *.csv などのファイルを Web アプリケーションで処理できます。 |
GPBoolean、GPDataFile、GPLong、GPDouble、GPString、GPLinearUnit、GPDate | 出力は、HTML または他のウィジェットを使用して表示されます。 |
onExecuteComplete イベント ハンドラからの結果
execute 操作の場合は、onExecuteComplete イベントによって、ジオプロセシング タスクの結果とメッセージが返されます。結果のインスタンスは、タスクのすべての出力パラメータの配列であり、配列内のエントリは常に、タスク ページに表示されている順序どおりになります。このため、配列内の位置によってパラメータ値を識別できます。配列内の出力パラメータごとに、パラメータ名、パラメータのデータ タイプ、および値が示されます。次のコードは、結果内の最初の出力パラメータにアクセスする方法を示しています。次のコードでは、出力パラメータが GPFeatureRecordSetLayer 出力であることがわかっているため、コードは、その出力をグラフィック レイヤとしてレンダリングし、Web アプリケーションに追加する方法を示しています。
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)
}
onGetResultDataComplete イベント ハンドラからの結果
onGetResultDataComplete イベントは結果のインスタンスを提供します。onExecuteComplete イベントからの結果とは異なり、結果のインスタンスには、要求されたパラメータの値のみが含まれます。パラメータ結果には、要求されたパラメータの名前、データ タイプ、および値が示されます。パラメータ値は、必要に応じて結果から取得して使用されます。次のコードは、パラメータ結果のインスタンスからの GPFeatureRecordSetLayer パラメータ結果のレンダリングを示しています。
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 と Silverlight の API
JavaScript アプリケーション用の前述の 4 つのステップは Flex と Silverlight の API にも適用されます。Flex API と Silverlight API でジオプロセシング タスクを使用するためのコード サンプルは、それぞれのオンライン SDK で探すことができます。