The iServer Processing Automation Service currently offers several tools such as track reconstruction, overlay analysis, etc. All functions available to use REST API to create Processing Automation Service tasks by executing REST requests. System administrators can also create GPA models in iServer by accessing the GPA model builder, and then publish the GPA service.
The following describes how to execute the GPA tool through the REST API. There are two execution modes: asynchronous execution and synchronous execution. You can choose the appropriate execution mode according to your needs.
Note: Only users with the default ADMIN role can create GPA jobs. If users in other roles want to access and use the service, security configuration is required.
Note: To access a protected GPA service resource, it need to carry a Token in the URI. For details, see Accessing a Protected REST Service Resource by Token
The request method for asynchronous execution of the GPA tool is POST. The GPA tool, which executes asynchronously, returns the GPA task status information in real time after the request is sent.
To view GPA task information and results submitted by the executed GPA tool, it needs to be obtained through the GET request according to the task ID in the GPA task status information.
To asynchronously execute the GPA tool and view GPA task information and results:
Review the list of GPA tools under the GPA service root node to determine which tools are required for your application.
Check the description of the required tool in the GPA service list to determine the tool ID, the parameter ID to be passed, and so on. Build a POST request URI and request parameters for the asynchronously executed GPA tool based on the ID of the tool and the parameters that need to be passed to request the resource.
The POST request URI for executing the GPA tool asynchronously is as follows:
http://<server>:<port>/iserver/services/geoprocessing/restjsr/gp/v2/<ToolID>/jobs?token=<TokenValue>
According to the parameter ID of the tool and the parameter value to be set, the parameters of the POST request are as follows (if the reserved parameters are checked in Publish Model, only the parameters to be adjusted can be set, and the remaining parameters use the reserved values when publishing):
{
"parameter":{
"ParameterID1":"Value1",
"ParameterID2":"Value2",
"ParameterID3":"Value3",
"ParameterID4":"Value4"
},
"environment ":{
"type":"BDT_Spark_Environment"，
"master":"spark://127.0.0.1:7077",
"appName":"geoprocessing",
"settings":["spark.cores.max=4"," spark.driver.host=136.0.8.1","spark.executor.memory=16g"]
}
}
The following is the JSON structure parsing of the POST request parameters of the Geo-Processing Automation (GPA) tool for asynchronous execution:
| Name | Type | Interpretation |
| parameter | String | Parameter Settings when executing the GPA tool in the form { "ParameterID1":"Value1", "ParameterID2":"Value2", … … }, where ParameterID is the parameter ID of the tool, which can be determined by the corresponding GPA tool description, and Value is the value of the parameter. The required parameters must be filled in, and the optional parameters can be filled in or not filled in as required. |
| environment | String | Parameter Settings, the environment in which the GPA tool is executed, contains the following fields:
Environment parameters need to be set when GPA analysis using the cluster is required. Do not set if not required. |
With an asynchronously executed POST request, you can GPA task ID for this execution in the status information returned. Based on this task ID and the GPA tool ID, you can view the relevant task information and results via GET request.
The following is a GET request URI to view information about GPA tasks that execute asynchronously:
http://<server>:<port>/iserver/services/geoprocessing/restjsr/gp/v2/<ToolID>/jobs/<jobID>.rjson?token=<TokenValue>
The following is the RJSON structure parsing of the GPA task information of the request response:
| Field | Type |
Explain |
| jobID | String | GPA Task ID. |
| processID | String | The tool ID of the GPA task. |
| processTitle | String | Tool name for the GPA task. |
| messages | String | Details of the execution of the task. |
| state | SparkJobState | The status of the task, including execution status, start and end time, time consumption, etc. |
The following is the GET request URI to view the results of a GPA task executed asynchronously:
http://<server>:<port>/iserver/services/geoprocessing/restjsr/gp/v2/<ToolID>/jobs/<jobID>/results(/ParameterID)?token=<TokenValue>
ParameterID is the Output ResultID of the tool. When the tool runs with multiple results, the required result can be obtained by specifying the Output ResultID; if this parameter is not set, all results will be returned.
The request method for synchronous execution of the GPA tool is GET. The synchronous execution of the GPA tool gets a response message containing the tool Result after the tool is Executed.
The steps to synchronously execute the GPA tool are as follows:
Review the list of GPA tools under the GPA service root node to determine which tools are required for your application.
Check the description of the required tool in the GPA service list to determine the tool ID, the parameter ID to be passed, and so on. Build a POST request URI and request parameters for the asynchronously executed GPA tool based on the ID of the tool and the parameters that need to be passed to request the resource.
The GET request URI for the synchronous execution of the GPA tool is as follows:
The GPA tool has reserved parameters. Use the reserved parameters to synchronously execute the GPA tool:
http://<server>:<port>/iserver/services/geoprocessing/restjsr/gp/v2/<ToolID>/execute?token=<TokenValue>
Pass parameters to synchronously execute the GPA tool:
http://<server>:<port>/iserver/services/geoprocessing/restjsr/gp/v2/<ToolID>/execute?parameter=json&environment=json&token=<TokenValue>
The following is the JSON structure resolution of the parameters in the GET request URI of the synchronous execution GPA tool:
| Name | Type | Interpretation |
| parameter | JSON | Parameter Settings. Executing the GPA tool in the form { "ParameterID1":"Value1", "ParameterID2":"Value2", … … }, where ParameterID is the parameter ID of the tool, which can be determined by the corresponding GPA tool description, and Value is the value of the parameter. The required parameters must be filled in, and the optional parameters can be filled in or not filled in as required. |
| environment | JSON | Environment parameters need to be set when GPA analysis using the cluster is required. Do not set if not required. |
Note: The parameter and environment parameters format is the same as the asynchronous GPA tool parameter format.
The request URI for synchronous execution of the GPA tool is format-sensitive. Avoid using extra spaces and line breaks in the URI. Copy the URI to the browser for validation. If some special characters in the parameter need to be encoded, the encoding tool can be used for processing.
For an introduction to the REST API, refer to geoprocessing .