Opération de tâche : submitJob (REST)
Lorsqu'un service de géotraitement est publié en mode d'exécution asynchrone, les tâches de géotraitement du service prennent en charge l'opération de soumission de la tâche (submitJob). L'opération submitJob convient aux tâches de longue durée, qui traitent des jeux de données volumineux. Le serveur de géotraitement permet également de créer un service de carte obtenu pour une tâche exécutée avec succès. L'opération submitJob convient donc aux sorties d'outils non transportables, comme les données TIN, DAO, etc., et pour les sorties RasterData qui ne peuvent pas être affichées par les applications Web. Dans ce cas, les sorties peuvent être affichées en tant que service de carte obtenu par le serveur et les clients peuvent ajouter ce service de carte obtenu à leurs applications Web.
Soumission d'une tâche via l'opération submitJob
Le modèle d'URL pour l'opération submitJob est http://<gp-task-url>/submitJob. Le client envoie une demande d'exécution de la tâche via l'opération submitJob. Lorsque la tâche est soumise, les paramètres en entrée de la tâche sont générés sous la forme d'une URL et envoyés au serveur à l'aide d'une opération similaire à l'opération executeTask. Quand le serveur reçoit une demande de type submitJob, il crée une ressource de tâche associée à un identifiant unique, (jobId) et le renvoie au client. La réponse du serveur de l'opération de la tâche de géotraitement submitJob est également associée à un identifiant de tâche unique (jobId) et à un statut de tâche (jobStatus), comme illustré ci-dessous.
Réponse JSON à la requête submitJob
{ "jobId" : "ja892cd2a90d149db9a171fc86ff530b4",
"jobStatus": "esriJobSubmitted"}
Vérification de l'état de la tâche
L'URL de la ressource de la tâche est http://<task-url>/jobs/<jobId>. Le client peut envoyer des requêtes périodiquement via l'URL de la tâche pour déterminer son état. La réponse du serveur à la requête relative à l'état de la tâche comprend les valeurs jobId et jobStatus, ainsi que les messages de l'outil de géotraitement, qui dépendent du niveau de message du service de géotraitement. Le document JSON ci-dessous contient la réponse envoyée par le serveur à la requête concernant l'état de la tâche. Notez que chaque message est associé à un type et à une description.
Réponse JSON à la requête relative à l'état de la tâche
{
"jobId": "ja892cd2a90d149db9a171fc86ff530b4",
"jobStatus": "esriJobExecuting",
"messages": [
{
"type": "esriJobMessageTypeInformative",
"description": "Submitted."
},
{
"type": "esriJobMessageTypeInformative",
"description": "Executing..."
}
]
}
L'exemple ci-dessus indique que l'état de statut (jobStatus) est en cours d'exécution (esriJobExecuting). Les autres états de tâche sont décrits dans le tableau ci-dessous.
Codes jobStatus | Description |
esriJobWaiting | Le serveur est occupé par d'autres requêtes. |
esriJobSubmitted | Le serveur a accepté la requête relative à la tâche. |
esriJobExecuting | Le serveur exécute la tâche. |
esriJobSucceeded | Le serveur a terminé la tâche avec succès et les résultats en sortie sont disponibles. |
esriJobFailed | L'exécution de la tâche a échoué en raison de paramètres non valides ou d'autres erreurs de l'outil de géotraitement. |
esriJobCancelling | Le serveur annule l'exécution de la tâche à la demande du client. |
esriJobCancelled | La requête d'exécution de la tâche a été annulée par le client et le serveur a arrêté l'exécution de la tâche. |
Résultat de tâche positif
Lorsque la tâche a abouti (jobStatus = esriJobSucceeded), le serveur crée de nouvelles ressources pour les paramètres en entrée et en sortie accessibles via une URL. La réponse du serveur à la requête d'état inclut des informations sur l'URL des données en entrée et des résultats. Voici un exemple de réponse JSON d'une tâche de bufferisation de points avec le paramètre en sortie Output_Polygons. Notez que, contrairement à la valeur de résultat d'une tâche d'exécution, la valeur des paramètres en entrée et en sortie est une URL relative.
Réponse JSON de résultat de tâche positif
{
"jobId": "ja892cd2a90d149db9a171fc86ff530b4",
"jobStatus": "esriJobSucceeded",
"results": {
"Output_Polygons": {
"paramUrl": "results/Output_Polygons"
}
},
"inputs": {
"Input_Features": {
"paramUrl": "inputs/Input_Features"
}
},
"messages": [
]
}
Lorsque la tâche s'est terminée avec succès, le client doit envoyer une requête pour récupérer chaque paramètre en sortie. Le client peut obtenir les données en entrée ou les résultats en sortie à l'aide de leur URL respective. L'URL de résultat est http://<job-url>/results/<param-name>. L'URL des données en entrée est http://<job-url>/inputs/<param-name>. La réponse de ces ressources constitue la valeur du paramètre. Elle peut être au format de sortie JSON/KML/AMF/HTML, en fonction des requêtes des clients. Voici un exemple de réponse JSON pour le paramètre en sortie Output_Polygons du type de données GPFeatureRecordSetLayer. Notez que la réponse contient le nom, le type de donnée et la valeur du paramètre.
Réponse JSON pour un paramètre de résultat
{
"paramName": "Buffer_Polygons",
"dataType": "GPFeatureRecordSetLayer",
"value": {
"displayFieldName": "",
"geometryType": "esriGeometryPolygon",
"spatialReference": {
"wkid": 102726,
"latestWkid": 102726
},
"fields": [
{
"name": "FID",
"type": "esriFieldTypeOID",
"alias": "FID"
},
{
"name": "BUFF_DIST",
"type": "esriFieldTypeDouble",
"alias": "BUFF_DIST"
},
{
"name": "Shape_Length",
"type": "esriFieldTypeDouble",
"alias": "Shape_Length"
},
{
"name": "Shape_Area",
"type": "esriFieldTypeDouble",
"alias": "Shape_Area"
}
],
"features": [{
"attributes": {
"FID": 1,
"BUFF_DIST": 3280.83333333,
"Shape_Length": 20613.401930152133,
"Shape_Area": 3.381121258723078E7
},
"geometry": {"rings": [[
[
7643591.499937415,
684676.8331969082
],
[
7643683.927544653,
684675.5310036391
] ...more
]]}
}],
"exceededTransferLimit": false
}
}
La figure ci-dessous schématise la communication serveur/client lors d'une opération submitJob. Notez les requêtes d'état périodiques envoyées par le client pour déterminer l'état de la tâche. Le client peut définir la durée entre chaque requête d'état. Lorsque le serveur a exécuté la tâche avec succès, il crée de nouvelles ressources pour les données en entrée et les résultats accessibles via l'URL.
Si le service de géotraitement a été publié avec activation de l'option Visionner les résultats avec un service de carte, le serveur crée un service de carte obtenu pour les paramètres en sortie, une fois l'exécution de la tâche terminée avec succès. Chaque paramètre en sortie du jeu de données géographiques de la tâche correspond à une couche dans le service de carte et s'affiche en fonction de la symbologie de couche définie pour les paramètres dans la tâche.
Réponse relative à une erreur
L'exécution d'une tâche peut échouer en raison de paramètres en entrée non valides, de données de projet inaccessibles ou d'autres défaillances de l'outil de géotraitement. Quand une tâche a échoué, son état est défini sur esriJobFailed. Pour effectuer le suivi des défaillances, le client doit vérifier l'état de la tâche via l'URL de la tâche. Voici un exemple de réponse d'erreur au format JSON pour une tâche dont l'exécution a échoué.
Réponse d'erreur au format JSON contenant l'état esriJobFailed
{
"jobId": "ja892cd2a90d149db9a171fc86ff530b4",
"jobStatus": "esriJobFailed",
"messages": [
{
"type": "esriJobMessageTypeInformative",
"description": "Submitted."
},
{
"type": "esriJobMessageTypeInformative",
"description": "Executing..."
},
{
"type": "esriJobMessageTypeError",
"description": "Failed."
}
]
}
Lorsqu'une tâche a échoué, le serveur ne crée aucune ressource pour les données en entrée et les résultats. Il ne crée également aucun service de carte obtenu, même si le service de géotraitement est associé à un service de carte obtenu.
Annulation de la tâche
Le client peut décider d'abandonner l'opération submitJob à tout moment du cycle d'exécution de la tâche et l'annuler. L'URL d'annulation de la tâche est http://<gp-task-url>/cancel. Lorsque le serveur reçoit une requête d'annulation, il modifie l'état de la tâche qui passe à esriJobCancelling et tente de terminer son exécution. Le serveur renvoie un message d'état de tâche au client, tel que celui présenté ci-dessous.
Réponse JSON à la requête d'annulation
{
"jobId": "ja892cd2a90d149db9a171fc86ff530b4",
"jobStatus": "esriJobCancelling"
}
Pour suivre la progression de la requête d'annulation, le client peut continuer à interroger le serveur sur l'état de la tâche via l'URL de la tâche. Le client peut également demander l'annulation de tâches associées à un état spécifique : esriJobWaiting, esriJobSubmitted ou esriJobExecuting. Si la requête d'annulation est émise pour des tâches dont l'état est esriJobSucceeded ou esriJobFailed, le serveur renvoie un message d'erreur.