Web アプリケーションでのジオプロセシング タスクの使用

ArcGIS Web マッピング API

Web GIS のフレームワークは GIS ベースの Web アプリケーションを理解する上で参考となります。Web ブラウザは、ArcGIS Web API の利用によって ArcGIS Server の GIS サービスと通信し、地理データをレンダリング(描画)して解析を実行できます。提供される ArcGIS Web API には次の 3 種類があります。

これらの 3 つの API は同じ機能を備えていますが、それぞれ異なる開発言語を対象としています。Flex または Silverlight を使用して Web アプリケーションの開発を開始するには、ArcGIS for Developers のサイトからライブラリをダウンロードする必要があります。JavaScript Web API の場合、Web URL を介してライブラリにアクセス可能なため、このライブラリをダウンロードする必要はありません。ArcGIS for Developers のサイトでは、ArcGIS Web API のサンプル コード、チュートリアル、ガイド、および詳細な参考資料が提供されています。

Web アプリケーションにおけるジオプロセシング タスク

ArcGIS ジオプロセシング サービスを使用して、ジオプロセシング機能およびデータの解析を Web アプリケーションに追加できます。各ジオプロセシング サービスには、1 つ以上のジオプロセシング タスクが含まれています。ArcGIS サーバの Services Directory から参照すると、ジオプロセシング サービス、サービス内のタスク、および各タスクのパラメータとプロパティを検索できます。トピック「ジオプロセシング REST サービス」では REST リソースの階層に関する情報を提供し、トピック「ジオプロセシング タスクの概要」ではジオプロセシング タスク、それらのタスク パラメータ、およびタスクへのアクセス方法に関する情報を提供しています。ジオプロセシング タスクにアクセスし機能を実行するための便利なオブジェクトとメソッドが Web API に用意されています。

タスクによって提供されるジオプロセシング機能を Web アプリケーションに追加するには、次の 4 つのステップに従います。

  1. ジオプロセシング タスクの初期化
  2. タスクのパラメータの設定
  3. タスクの実行
  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 の経験がない場合は、ArcGIS API for JavaScript のサイトをご参照ください。このサイトには多くのサンプル コードが含まれており、ジオプロセシングのサンプルを検索できます。

以下では、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 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;

ステップ 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 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

タスクでサポートされている操作がタスク実行である場合は、ジオプロセシング インスタンスの execute メソッドを使用して、パラメータを渡す必要があります。リクエストの成功また失敗時にアプリケーションを操作するイベント ハンドラの定義が必要です。タスクが正常に実行され、結果とジオプロセシング メッセージが返されると、onExecuteComplete イベントが生成されます。タスクの実行に失敗すると、onError イベントが生成されます。タスクが失敗した場合、サーバは、HTML エラー コードとジオプロセシング メッセージ(ある場合)を含むエラー インスタンスを返します。

タスク操作: 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); 
}

タスク操作: 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 操作におけるジョブ、ジョブ ID、ジョブ ステータス、およびサーバ/クライアント通信の詳細については、「タスク操作: ジョブの送信(submitJob)」をご参照ください。次のコードは、サーバにジョブを送信してイベントを処理する方法を示しています。

タスク操作: 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); 
}

ステップ 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 APISilverlight API でジオプロセシング タスクを使用するためのサンプル コードは、それぞれのオンライン SDK で探すことができます。

5/10/2014