Référentiel Liberty[8.5.5.6 ou ultérieure]

Administration des API REST par lots

Le profil Liberty de WebSphere Application Server comporte une interface de gestion RESTful qui vous permet de gérer vos travaux par lots.

Les opérations de base qui sont associées à un travail par lots concernent la soumission (démarrage), l'arrêt, le redémarrage et l'affichage du statut. Vous pouvez effectuer ces opérations à l'aide de n'importe quel client REST HTTP. Les données qui sont soumises dans le cadre d'une demande ou retournées dans le cadre d'une réponse sont au format JSON.

Les exemples ci-après illustrent les fonctions que vous pouvez exécuter avec l'API REST.

A faire : Les adresses Web de l'interface REST par lots commencent toutes par l'adresse Web racine : https://{host}:{port}/ibm/api/batch.

Instances de travail

GET /ibm/api/batch/jobinstances/
Cette URI retourne une liste d'instances de travail. Les paramètres de la requête sont:
  • page=[page number] : indique la page (sous-ensemble d'enregistrements) à retourner. La valeur par défaut est 0.
  • pageSize=[number of records per page] : indique le nombre d'enregistrements par page. La valeur par défaut est 50.
Exemples de demandes :

https://localhost:9443/ibm/api/batch/jobinstances

https://localhost:9443/ibm/api/batch/jobinstances?page=13&pagesize=20

Exemple de réponse :
[
    {
        "jobName":"test_sleepyBatchlet",
        "instanceId":7,
        "appName":"SimpleBatchJob#SimpleBatchJob.war",
        "submitter":"bob",
        "batchStatus":"COMPLETED",
        "jobXMLName":"test_sleepyBatchlet",
        "instanceState":"COMPLETED",
        "_links":[
            {
                "rel":"self",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/7"
            },
            {
                "rel":"job logs",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/joblogs"
            }
        ]
    },
    {
        "jobName":"test_sleepyBatchlet",
        "instanceId":6,
        "appName":"SimpleBatchJob#SimpleBatchJob.war",
        "submitter":"bob",
        "batchStatus":"COMPLETED",
        "jobXMLName":"test_sleepyBatchlet",
        "instanceState":"COMPLETED",
        "_links":[
            {
                "rel":"self",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/6"
            },
            {
                "rel":"job logs",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/6/joblogs"
            }
        ]
    }
]
GET /ibm/api/batch/jobinstances/job instance id
Cet URI retourne des informations détaillées sur l'instance de travail spécifiée, par exemple toutes les exécutions qui sont associées à une instance de travail spécifique. Les résultats sont renvoyés dans l'ordre du plus récent au plus ancien. Le résultat le plus récent est affiché en premier dans la liste.
Exemple de réponse :
{
    "jobName":"test_sleepyBatchlet",
    "instanceId":7,
    "appName":"SimpleBatchJob#SimpleBatchJob.war",
    "submitter":"bob",
    "batchStatus":"COMPLETED",
    "jobXMLName":"test_sleepyBatchlet",
    "instanceState":"COMPLETED",
    "_links":[
        {
            "rel":"self",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7"
        },
        {
            "rel":"job logs",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/joblogs"
        },
        {
            "rel":"job execution",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/jobexecutions/7"
        }
    ]
}
POST /ibm/api/batch/jobinstances/
Utilisez cet URI pour soumettre (démarrer) un nouveau travail.
L'exemple suivant illustre le corps de demande pour la soumission d'un travail packagé dans un module WAR, au format JSON :
{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJob.war",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}
L'exemple suivant illustre le corps de demande pour la soumission d'un travail packagé dans un module EJB, au format JSON :
{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJobEJB.jar",
  "componentName" : "MyEJB",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}

Le paramètre applicationName identifie l'application par lots. Il est obligatoire sauf si moduleName est spécifié, auquel cas la valeur du paramètre applicationName est dérivée du paramètre moduleName par le retrait du suffixe .war ou .jar de la valeur de moduleName. Par exemple, si vous n'indiquez aucun applicationName et moduleName=SimpleBatchJob.war, applicationName devient par défaut SimpleBatchJob.

moduleName identifie le module au sein de l'application par lots qui contient les artefacts de travail, par exemple JSL. Le travail est soumis sous le contexte du composant de module. moduleName est obligatoire sauf si applicationName est spécifié, auquel cas moduleName est dérivé de applicationName par l'ajout de .war à applicationName. Par exemple, si vous indiquez applicationName=SimpleBatchJob et nom moduleName, moduleName devient par défaut SimpleBatchJob.war.

componentName identifie le composant EJB au sein du module EJB de l'application par lots. S'il est spécifié, le travail est soumis sous le contexte de composant d'EJB.
Remarque : componentName est obligatoire uniquement lorsque le module est un module EJB. Lorsque le module est un module WAR, componentName n'est pas obligatoire.

Vous devez entrer une valeur pour jobXMLName. La valeur de jobParameters est facultative.

L'exemple de réponse suivant illustre une soumission de travail qui a abouti :
{
    "jobName": "test_sleepyBatchlet",
    "instanceId": 10,
    "appName": "SimpleBatchJob#SimpleBatchJob.war",
    "submitter": "bob",
    "batchStatus": "STARTING",
    "jobXMLName": "test_sleepyBatchlet",
    "instanceState": "SUBMITTED",
    "_links": [
        {
            "rel": "self",
            "href": "https://localhost:9443/ibm/api/batch/jobinstances/10"
        },
        {
            "rel": "job logs",
            "href": "https://localhost:9443/ibm/api/batch/jobinstances/10/joblogs"
        }
    ]
}
PUT /ibm/api/batch/jobinstances/job instance id?action=stop
Cet URI vous permet d'arrêter l'exécution de travail la plus récente qui est associée à cette instance de travail si celle-ci est en cours d'exécution. Si ce n'est pas le cas, l'API renvoie une erreur.
PUT /ibm/api/batch/jobinstances/job instance id?action=restart
Cet URI vous permet de redémarrer à partir de l'exécution de travail la plus récente qui est associée à cette instance de travail uniquement si elle est à l'état ARRETE OU ECHOUE. Si aucune exécution de travail n'est associée à cette instance, ou si la dernière exécution du travail se trouve dans l'état TERMINE, l'API renvoie une erreur.
PUT /ibm/api/batch/jobinstances/job instance id?action=restart&reusePreviousParams=true
Cet URI vous permet de redémarrer l'exécution de travail la plus récente et de réutiliser les paramètres de travail des exécutions précédentes qui est associée à cette instance de travail. L'exécution précédente doit être à l'état ARRETE ou ECHOUE. Si aucune exécution de travail n'est associée à cette instance, ou si la dernière exécution du travail se trouve dans l'état TERMINE, l'API renvoie une erreur. Notez que le paramètre reusePreviousParams est facultatif. Le paramètre par défaut est reusePreviousParams=false.
Remarque : Lorsque reusePreviousParams=true, tous les paramètres de travail qui sont soumis dans le cadre de la demande de redémarrage en cours ont priorité sur mes paramètres de travail précédents. Les paramètres en cours remplacent les paramètres précédents avec le même nom de clé de paramètre de travail.
DELETE /ibm/api/batch/jobinstances/job instance id
Cet URI vous permet de purger toutes les entrées de base de données et les journaux de travaux associés à cette instance de travail. Cette API renvoie une erreur si l'instance de travail comporte des exécutions de travail actives. Si une erreur se produit lors de la suppression de journaux de travail, aucune tentative n'est effectuée pour supprimer les données d'instance de travail de la base de données du magasin de travaux.
DELETE /ibm/api/batch/jobinstances/job instance id?purgeJobStoreOnly=true
Cet URI vous permet de purger uniquement les entrées de base de données du magasin de travaux associées à cette instance de travail. Lorsque purgeJobStoreOnly=true, aucune tentative n'est effectuée pour purger les journaux de travail associés à cette instance de travail. Le paramètre par défaut est purgeJobStoreOnly=false. Cette API renvoie une erreur si l'instance de travail comporte des exécutions de travail actives.

Exécutions de travail

GET /ibm/api/batch/jobexecutions/job execution id
Cet URI retourne des informations détaillées sur une exécution de travail spécifique et elle inclut des liens vers les exécutions d'étapes et les historiques de travail associés.
Exemple de demande :

http://localhost:9443/ibm/api/batch/jobinstances/9/jobexecutions/9

Exemple de réponse :
{
    "jobName":"test_sleepyBatchlet",
    "executionId":9,
    "instanceId":9,
    "batchStatus":"COMPLETED",
    "exitStatus":"COMPLETED",
    "createTime":"2015/05/07 16:09:41.025 -0400",
    "endTime":"2015/05/07 16:09:52.127 -0400",
    "lastUpdatedTime":"2015/05/07 16:09:52.127 -0400",
    "startTime":"2015/05/07 16:09:41.327 -0400",
    "jobParameters":{
    },
    "restUrl":"https://localhost:9443/ibm/api/batch",
    "serverId":"localhost/C:/ibm/RAD_workspaces/Liberty7/build.image/wlp/usr/server1",
    "logpath":"C:\\ibm\\Liberty\\wlp\\usr\\servers\\server1\\logs\\joblogs\\test_sleepyBatchlet\\2015-05-07\\instance.9\\execution.9\\",
    "stepExecutions":[
        {
            "stepExecutionId":9,
            "stepName":"step1",
            "batchStatus":"COMPLETED",
            "exitStatus":"SleepyBatchlet:i=10;stopRequested=false",
            "stepExecution":"https://localhost:9443/ibm/api/batch/jobexecutions/9/stepexecutions/step1"
        }
    ],
    "_links":[
        {
            "rel":"self",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9"
        },
        {
            "rel":"job instance",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/9"
        },
        {
            "rel":"step executions",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9/stepexecutions"
        },
        {
            "rel":"job logs",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9/joblogs"
        },
        {
            "rel":"stop url",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9?action=stop"
        }
    ]
}
GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number
Cette URI retourne des informations détaillées sur une exécution de travail spécifique et elle inclut des liens vers les exécutions d'étapes et les historiques de travail associés.
PUT /ibm/api/batch/jobexecutions/job execution id?action=stop
Cette URI vous permet d'arrêter l'exécution de travail en cours spécifiée. Les paramètres obligatoires incluent action = stop, restart.
PUT /ibm/api/batch/jobexecutions/job execution id?action=restart
Cet URI vous permet de redémarrer l'exécution de travail spécifiée. Les paramètres obligatoires incluent action = stop, restart.

Exécutions d'étape

GET /ibm/api/batch/jobexecutions/job execution id/stepexecutions
Cet URI renvoie un tableau JSON comportant tous les détails d'exécution d'étape pour l'exécution de travail spécifiée. Si votre travail contient une étape partitionnée, les informations de partition seront renvoyées avec chaque étape.
Exemple de demande :

https://localhost:8020/ibm/api/batch/jobexecutions/40/stepexecutions

L'exemple suivant illustre une réponse pour une étape partitionnée.
[ 
   { 
      "stepExecutionId":47,
      "executionId":39,
      "instanceId":35,
      "stepName":"step1",
      "batchStatus":"COMPLETED",
      "startTime":"2015/03/30 11:10:08.652 -0400",
      "endTime":"2015/03/30 11:10:09.817 -0400",
      "exitStatus":"COMPLETED",
      "metrics":{ 
         "READ_COUNT":"0",
         "WRITE_COUNT":"0",
         "COMMIT_COUNT":"0",
         "ROLLBACK_COUNT":"0",
         "READ_SKIP_COUNT":"0",
         "PROCESS_SKIP_COUNT":"0",
         "FILTER_COUNT":"0",
         "WRITE_SKIP_COUNT":"0"
      },
      "partitions":[ 
         { 
            "partitionNumber":0,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.579 -0400",
            "endTime":"2015/03/30 11:10:09.706 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":1,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.257 -0400",
            "endTime":"2015/03/30 11:10:09.302 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":2,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.469 -0400",
            "endTime":"2015/03/30 11:10:09.548 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         }
      ]
   },
   { 
      "stepExecutionId":51,
      "executionId":39,
      "instanceId":35,
      "stepName":"step2",
      "batchStatus":"COMPLETED",
      "startTime":"2015/03/30 11:10:09.915 -0400",
      "endTime":"2015/03/30 11:10:10.648 -0400",
      "exitStatus":"COMPLETED",
      "metrics":{ 
         "READ_COUNT":"0",
         "WRITE_COUNT":"0",
         "COMMIT_COUNT":"0",
         "ROLLBACK_COUNT":"0",
         "READ_SKIP_COUNT":"0",
         "PROCESS_SKIP_COUNT":"0",
         "FILTER_COUNT":"0",
         "WRITE_SKIP_COUNT":"0"
      },
      "partitions":[ 
         { 
            "partitionNumber":0,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.324 -0400",
            "endTime":"2015/03/30 11:10:10.417 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":1,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.260 -0400",
            "endTime":"2015/03/30 11:10:10.347 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":2,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.507 -0400",
            "endTime":"2015/03/30 11:10:10.557 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         {
            "_links":[
            {
               "rel":"job execution",
               "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9"
            },
            {
               "rel":"job instance",
               "href":"https://localhost:9443/ibm/api/batch/jobinstances/9"
            }
        ]
    }
] 
GET /ibm/api/batch/jobexecutions/job execution id/stepexecutions/step name
Cet URI renvoie un tableau JSON comportant les détails d'exécution d'étape pour l'exécution de travail spécifiée et le nom de l'étape.
GET /ibm/api/batch/jobeinstances/job instance id/jobexecutions/job execution sequence number/stepexecutions/step name
Cet URI renvoie un tableau JSON comportant les détails d'exécution d'étape pour l'instance de travail spécifiée, l'exécution de travail et le nom de l'étape.
GET /ibm/api/batch/stepexecutions/step execution id
Cet URI renvoie un tableau JSON comportant les détails d'exécution d'étape pour l'exécution d'étape spécifiée.

Journaux de travaux

GET /ibm/api/batch/jobinstances/job instance id/joblogs
Cet URI renvoie un tableau JSON avec des liens REST vers toutes les parties du journal de travail pour l'instance de travail spécifiée.
GET /ibm/api/batch/jobexecutions/job execution id/joblogs
Cette URI renvoie un tableau JSON avec des liens REST vers toutes les parties du journal de travail pour l'exécution de travail spécifiée.
Important : L'exemple ci-après illustre le format des liens REST.
Si votre exécution de travail comporte les parties de journal de travail suivantes,
joblogs/instance.inst-id/execution.exec-id/part.1.log
joblogs/instance.inst-id/execution.exec-id/part.2.log
joblogs/instance.inst-id/execution.exec-id/step.step-name/partition.0/part.1.log
joblogs/instance.inst-id/execution.exec-id/step.step-name/partition.1/part.1.log
les liens REST correspondants sont les suivants :
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=part.1.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=part.2.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=step.step-name/partition.0/part.1.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=step.step-name/partition.1/part.1.log
GET /ibm/api/batch/jobexecutions/job execution id/joblogs
Les paramètres facultatifs sont les suivants :
type = text
Renvoie tous les journaux de travaux sous forme de texte en clair. Toutes les parties du journal de travail sont regroupées. La partie délimitant les enregistrements d'en-tête et de pied de page sont insérées dans le flux afin de délimiter les différentes parties dès lors qu'elles sont regroupées. Type = text est le paramètre par défaut.
type = zip
Renvoie tous les journaux de travaux pour l'instance de travail ou l'exécution de travail spécifiée sous forme de fichier compressé. La structure de répertoire des journaux de travaux est conservée dans le fichier compressé.
GET /ibm/api/batch/jobexecutions/job execution id/joblogs?part=path to part&type=text|zip
Cet URI renvoie les parties du journal de travail sous la forme de texte en clair (type=text) ou dans un fichier compressé (type=zip). Le paramètre par défaut est type=text.

Codes retour HTTP

Voici les codes retour HTTP pour l'API REST.
  • HTTP 200 OK
  • HTTP 201 Successfully created a new resource.
  • HTTP 202 Accepted request, but processing is not complete.
  • HTTP 400 Bad Request with invalid parameters. See returned message for details.
  • HTTP 401 Unauthorized to access this resource.
  • HTTP 403 Authentication failed.
  • HTTP 404 The requested resource cannot be found or does not exist.
  • HTTP 409 The request conflicts with the current state of the resource. See returned message for details.
  • HTTP 500 Internal Server Error.

Demandes STOP dans un environnement de traitement par lots distribué

Les demandes d'arret envoyées à l'API REST par lots doivent être adressées directement au programme d'exécution sur lequel s'exécute le travail. Si une demande d'arrêt est envoyée à un répartiteur ou un programme d'exécution sur lequel le travail n'est pas en cours d'exécution, la demande est redirigée vers le programme d'exécution approprié par un message de réponse de réacheminement HTTP 302. La zone location d'une réponse de réacheminement HTTP 302 indique l'URL correcte à utiliser pour la demande d'arrêt.

Demandes JOBLOGS dans un environnement de traitement par lots distribué

Les demandes de consignation de travail envoyées à l'API REST par lots doivent être adressées directement au programme d'exécution sur lequel s'exécute le travail. Si une demande de consignation est envoyée à un répartiteur ou un programme d'exécution sur lequel le travail n'est pas en cours d'exécution, la demande est redirigée vers le programme d'exécution approprié par un message de réponse de réacheminement HTTP 302. La zone location d'une réponse de réacheminement HTTP 302 indique l'URL correcte à utiliser pour la demande de consignation.
Remarque : Les demandes de consignation de travail envoyées à l'API REST par lots pour l'intégralité d'une instance de travail ne fonctionnent que si toutes les exécutions de travail de cette instance se sont exécutées sur le même programme d'exécution. Si les exécutions se sont exécutées sur différents programmes d'exécution, les demandes de consignation pour l'instance échouent. Dans ce cas, vous devez extraire les consignations de travail pour chaque exécution séparément.

Demandes de purge dans un environnement de traitement par lots distribué

Les demandes de purge envoyées à l'API REST par lots doivent être adressées directement au programme d'exécution sur lequel s'exécute le travail. Si une demande de purge est envoyée à un répartiteur ou un programme d'exécution sur lequel le travail n'est pas en cours d'exécution, la demande est redirigée vers le programme d'exécution approprié par un message de réponse de réacheminement HTTP 302. La zone location d'une réponse de réacheminement HTTP 302 indique l'URL correcte à utiliser pour la demande de purge.
Remarque : Les demandes de purge envoyées à l'API REST par lots pour l'intégralité d'une instance de travail ne fonctionnent que si toutes les exécutions de travail de cette instance se sont exécutées sur le même programme d'exécution. Si les exécutions se sont exécutées sur différents programmes d'exécution, les demandes de purge pour l'instance échouent.

Icône indiquant le type de rubrique Rubrique de référence

Dispositions pour les centres de documentation | Commentaires


Icône d'horodatage Dernière mise à jour: Wednesday, 2 September 2015
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_batch_rest_api
Nom du fichier : rwlp_batch_rest_api.html