API REST par lots

WebSphere Application Server Liberty 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.

Remarque : L'API REST par lots est versionnée URL par URL. Les URL sans numéro de version sont considérées comme étant en version 1 de l'API. Les adresses Web de l'interface REST par lots commencent toutes par l'adresse Web racine : https://{host}:{port}/ibm/api/batch/{version}/.
A faire : Les adresses Web de l'interface REST par lots commencent toutes par l'adresse Web racine : https://{host}:{port}/ibm/api/batch.

API REST avec un ID utilisateur qui est uniquement un émetteur

Les résultats renvoyés par les URL GET ("lecture") sont filtrés lorsque l'ID utilisateur qui appelle l'API REST sur HTTPS n'a accès qu'au rôle batchSubmitter. L'émetteur voit uniquement les données d'instance et d'exécution associées aux instances de travail qu'il a soumises. En revanche, les ID utilisateur affectés aux rôles batchAdmin et batchMonitor peuvent visualiser toutes les données d'instance et d'exécution (renvoyées par n'importe quelle URL avec un jeu de paramètres quelconque).

Un ID utilisateur affecté au rôle batchSubmitter voit les résultats après leur filtrage par les paramètres standard, comme décrit dans la documentation de l'URL concernée. Un filtrage supplémentaire est ensuite effectué en ne renvoyant que les données d'instance et d'exécution associées aux instances de travail qu'il a lui-même soumis.

Pour plus d'informations, voir Sécurisation de l'environnement de traitement par lots Liberty.

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) à renvoyer. 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/v2/jobinstances/
Cette URI retourne une liste d'instances de travail filtrée par les paramètres de requête suivants :
  • jobInstanceId=[instanceId]:[instanceId] : Retourne les instances de travail égales à et comprises dans la plage d'instanceId.
  • jobInstanceId=>[instanceId] : Retourne les instances de travail supérieures et égales à l'instanceId fourni.
  • jobInstanceId=<[instanceId] : Retourne les instances de travail inférieures et égales à l'instanceId fourni.
  • jobinstanceId=[instanceId],[instanceId],[instanceId] : Retourne les instances de travail spécifiées.
  • createTime=[yyyy-MM-dd]:[yyy-MM-dd] : Retourne les instances de travail comprises dans la plage de dates inclusive.
  • createTime=[yyyy-MM-dd]: Retourne les instances de travail à la date indiquée.
  • createTime=>3d : Retourne les instances de travail crées il y a trois jours ou depuis. Par exemple, createTime est supérieur ou égal au début du jour il y a trois jours.
  • createTime=<3d : Retourne les instances de travail crées il y a trois jours ou avant. Par exemple, createTime est inférieur ou égal à la fin du jour il y a trois jours.
  • instanceState=[state],[state] : Retourne les instances de travail avec l'état fourni. Les états d'instance valides sont : SUBMITTED, JMS_QUEUED, JMS_CONSUMED, DISPATCHED, FAILED, STOPPED, COMPLETED et ABANDONED.
  • exitStatus=[string] : Retourne les instances de travail qui correspondent à la chaîne de statut d'exit. Le critère de chaîne peut inclure le caractère générique (*) d'un côté ou de l'autre.
  • page=[page number] : Indique la page (sous-ensemble d'enregistrements) à renvoyer. 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.
Remarque : Rôle du fuseau horaire par défaut du serveur dans les requêtes impliquant createTime

Lorsque vous soumettez un travail, la valeur de l'instance de travail est stockée dans le référentiel des travaux et normalisée sur UTC. Lorsque vous spécifiez des dates sous le format aaaa-MM-jj, comme dans createTime=[aaaa-MM-jj] ou createTime=[aaaa-MM-jj]:[aaa-MM-jj]:, vous devez convertir la chaîne de date aaaa-MM-jj en une plage spécifique d'heures UTC pour qu'elle corresponde aux valeurs createTime dans les enregistrements de table de l'instance de travail. Pour ce faire, l'application utilise le fuseau horaire par défaut du serveur qui traite la requête REST. Ce fuseau horaire est celui utilisé pour convertir la chaîne de date en plage UTC pour comparaison.

Le tableau ci-après illustre les données retournées par les paramètres de requête jobInstanceId=10:13.
JOBINSTANCEID CREATETIME(* d'après le fuseau horaire de server1) INSTANCESTATE EXITSTATUS
10 11-05-2015.01:10:00 COMPLETED SUCCESS
11 11-08-2014.02:20:00 COMPLETED SUCCESS
12 11-10-2015.03:30:00 FAILED FAILURE
13 11-11-2015:04:40:00 COMPLETED SUCCESS
*Etant donné que le référentiel des travaux stocke la valeur createTime au format UTC, il est important de comprendre que cette valeur est affichée dans les données du tableau compte tenu du fuseau horaire par défaut du serveur concerné (par exemple, "server1"). Si nous avions élaboré un tableau similaire depuis la perspective d'un second serveur (avec un fuseau horaire différent de celui de "server1"), le tableau présenterait un autre ensemble de valeurs de colonne CREATETIME, la différence étant imputable aux fuseaux horaires distincts. Le fuseau horaire par défaut du serveur traitant la requête REST est celui utilisé dans les exemples suivants pour mapper les paramètres de chaîne de date aaaa-MM-jj à des valeurs createTime UTC dans la base de données.
Les commandes suivantes retournent le même résultat quel que soit le serveur sur lequel elles sont émises :
  • jobInstanceId=11:13 renverrait les JOBINSTANCEID 11, 12 et 13.
  • jobInstanceId=>12 renverrait les JOBINSTANCEID 12 et 13.
  • jobInstanceId=<12 renverrait les JOBINSTANCEID 11 et 12.
  • jobInstanceId=11,12 renverrait les JOBINSTANCEID 11 et 12.
  • instanceState=FAILED renverrait JOBINSTANCEID 12..
  • exitStatus=SUCCESS renverrait les JOBINSTANCEID 10, 11 et 13.
Les commandes suivantes peuvent renvoyer des résultats différents pour des serveurs avec des fuseaux horaires par défaut différents. Dans ces exemples, elles sont émises vis à vis de "server1" (le serveur utilisé pour alimenter le tableau précédent) à la date et heure : 11-11-2015:07:00:00 dans le fuseau horaire par défaut du serveur.
  • createTime=>2d renverrait les JOBINSTANCEID 12 et 13 (il y a 2 jours, soir le 9 novembre 2015, ou après)
  • createTime=<2d renverrait les JOBINSTANCEID 10 et 11 (il ya 2 jours, soir le 9 novembre 2015, ou après)
  • createTime=2015-11-08:2015-11-11 renverrait des enregistrements avec JOBINSTANCEID 11,12 et 13.
  • createTime=2015-11-10 renverrait un enregistrement avec JOBINSTANCEID 12.
Exemples de demandes :
https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=20:50
https://localhost:9443/ibm/api/batch/jobinstances?createTime=>2d
https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=4,12,17&instanceState=COMPLETED
https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=4500:4600&createTime=2015-11-27&instanceState=COMPLETED&exitStatus=*JOB*&page=0&pageSize=1000
[16.0.0.4 et ultérieur]GET /ibm/api/batch/v3/jobinstances/
[16.0.0.4 et ultérieur]En plus de toutes les fonctions de l'URI GET /ibm/api/batch/v2/job instances/, cet URI renvoie une liste des instances de travail filtrée par les paramètres de requête suivants :
  • lastUpdatedTime=[yyyy-MM-dd]: renvoie les dernières instances de travail mises à jour à la date donnée. Cette valeur temporelle est mise à jour lors des transitions de l'état d'instance. Par exemple, de SUBMITTED à DISPATCHED.
  • jobParameter.[paramName]=[paramValue]: renvoie les instances de travail avec les exécutions ayant la paire nom:valeur fournie comme paramètre de travail. Par exemple : jobParameter.jesJobName=myJobName.
  • sort=[string],[string]: spécifie le paramètre ou les paramètres utilisés pour trier les résultats. L'utilisation du caractère - comme préfixe du paramètre indique que le tri sera effectué par ordre décroissant. Par exemple,sort=submitter trie les résultats par émetteur par ordre croissant. La spécification de sort=submitter,-lastUpdatedTime trie d'abord les résultats par émetteur par ordre croissant, puis par lastUpdatedTime, par ordre décroissant.
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.

Comme alternative à l'utilisation de la définition de travail JSL qui est fournie au sein de votre application par lots sous META-INF/batch-jobs, vous pouvez transmettre votre JSL en ligne dans le cadre de votre demande de soumission de travail REST. Le JSL qui est soumis en ligne remplace toujours tout JSL qui est fourni avec l'application par lots. Vous pouvez utiliser deux méthodes pour soumettre votre JSL en ligne dans le cadre de votre demande HTTP.
  1. Incluez votre JSL en tant que propriété JSON dans votre demande de soumission de travail. Ajoutez la propriété jobXML à l'objet JSON et ajoutez l'intégralité du contenu du fichier JSL en tant que chaîne JSON comme valeur de la propriété.
    Remarque : Vous devez correctement mettre en échappement la chaîne XML pour qu'elle puisse être analysée syntaxiquement par un analyseur JSON. La plupart des bibliothèques JSON effectuent cette opération à votre place.
    L'exemple ci-après illustre le corps de la demande pour la soumission d'un travail utilisant une demande HTTP à un seul élément avec le JSL transmis en ligne par JSON.
    {
      "applicationName":"SimpleBatchJob",
      "jobXMLName":"test_multiPartition_3Steps",
      "jobXML":"<?xml version=\"1.0\" encoding=\"UTF-8\" 
    standalone=\"yes\"?>
      \r\n<job id=\"test_multiPartition_3Steps\"
      xmlns=\"http://xmlns.jcp.org/xml/ns/javaee\"r\n\tversion=\"1.0>
      \r\n\t<step id=\"step1"\" next=\"step2\">
      \r\n\t\t<batchlet ref=\"simpleBatchlet\"/>
      \r\n\t\t<partition>\r\n\t\t\t<plan  partitions=\"3\"/>
      \r\n\t\t</partition>\r\n\t</step>
      \r\n\t<step  id=\"step2\" next=\"step3\">
      \r\n\t\t<batchlet ref=\"simpleBatchlet\" />
      \r\n\t\t<partition>\r\n\t\t\t<plan  partitions=\"3\" />
      \r\n\t\t</partition>\r\n\t</step>\r\n\t<step  id=\"step3\">
      \r\n\t\t<batchlet ref=\"simpleBatchlet\" />\r\n\t\t<partition>
      \r\n\t\t\t<plan partitions=\"3\"/>
      \r\n\t\t</partition>\r\n\t</step>\r\n</job>"
    }
    Remarque : La zone jobXML doit être analysée par un analyseur JSON et convertie en un objet JSON valide. La zone jobXMLName est facultative, car les informations d'ID de travail dans le JSL en ligne sont utilisées pour le nom de travail.
  2. Utilisez un formulaire à plusieurs parties HTTP. :Lorsque vous utilisez un formulaire HTTP à plusieurs parties, les données de soumission de travail JSON et la définition de travail XML doivent être soumises dans deux parties distinctes du corps HTTP. La partie JSON du formulaire à plusieurs parties doit être nommée jobdata et la partie XML du formulaire doit être nommée jsl. Il n'est pas nécessaire que la partie XML soit convertie en chaîne JSON lors de l'utilisation d'un formulaire à plusieurs parties.
    L'exemple suivant illustre une requête HTTP pour soumission d'un travail utilisant un formulaire HTTP à plusieurs parties, le JSL étant transmis en ligne via la portion de message JSL.
    Content-Type: multipart/form-data;boundary=---------------------------49424d5f4a4241544348
    
    -----------------------------49424d5f4a4241544348
    Content-Disposition: form-data; name="jobdata"
    Content-Type: application/json; charset=UTF-8
    {  
      "applicationName" : "SimpleBatchJob", 
      "moduleName" : "SimpleBatchJob.war",  
      "jobXMLName" : "test_multiPartition"
    }
    
    -----------------------------49424d5f4a4241544348
    Content-Disposition: form-data; name="jsl" 
    Content-Type: application/xml; charset=UTF-8
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <job id="test_multiPartition" xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    version="1.0">
    <step id="step1">
    <batchlet ref="simpleBatchlet" />
    <partition>    
      <plan partitions="3" />    
      </partition>
    </step>
    </job>
    
    -----------------------------49424d5f4a4241544348--
        
    Remarque : La zone jobXMLName est facultative, car les informations d'ID de travail dans le JSL en ligne sont utilisées pour le nom de travail.
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 que son exécution la plus récente indique COMPLETED (Terminée), 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 que son exécution la plus récente indique COMPLETED (Terminée), 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 purge 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. Les paramètres de la requête sont:
  • purgeJobStoreOnly=true|false : 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.
    Remarque : Aucun message de réponse de purge n'est renvoyé lorsque vous utilisez l'API de purge unique.
DELETE /ibm/api/batch/v2/jobinstances/
Cet URI purge toutes les entrées de base de données et les journaux de travaux associés aux instances de travail retournées par les paramètres de filtre de purge suivants :
Remarque : Avant d'exécuter l'interface DELETE pour les purger, il est recommandé d'utiliser l'interface GET pour afficher la liste des travaux et vérifier qu'il s'agit bien des travaux à purger.
  • page=[page number] : Indique la page (sous-ensemble d'enregistrements) à renvoyer. 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.
  • purgeJobStoreOnly=true|false : 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.
  • jobInstanceId=[instanceId]:[instanceId] : Purge les instances de travail égales à et comprises dans la plage d'instanceId.
  • jobInstanceId=>[instanceId] : Purge les instances de travail supérieures et égales à l'instanceId fourni.
  • jobInstanceId=<[instanceId] : Purge les instances de travail inférieures et égales à l'instanceId fourni.
  • jobinstanceId=[instanceId],[instanceId],[instanceId] : Purge les instances de travail spécifiées.
  • createTime=[yyyy-MM-dd]:[yyy-MM-dd] : Retourne les instances de travail comprises dans la plage de dates inclusive.
  • createTime=[yyyy-MM-dd]: Retourne les instances de travail à la date indiquée.
  • createTime=>3d : Retourne les instances de travail crées il y a trois jours ou depuis. Par exemple, createTime est supérieur ou égal au début du jour il y a trois jours.
  • createTime=<3d : Retourne les instances de travail crées il y a trois jours ou avant. Par exemple, createTime est inférieur ou égal à la fin du jour il y a trois jours.
  • instanceState=[state],[state] : Purge les instances de travail avec l'état fourni. Les états d'instance valides sont : SUBMITTED, JMS_QUEUED, JMS_CONSUMED, DISPATCHED, FAILED, STOPPED, COMPLETED et ABANDONED.
  • exitStatus=[string] : Retourne les instances de travail qui correspondent à la chaîne de statut d'exit. Le critère de chaîne peut inclure le caractère générique (*) d'un côté ou de l'autre.
Remarque : Par défaut, à moins que les paramètres page et pageSize soient spécifiés, 50 enregistrements au maximum sont purgés.
Remarque : Rôle du fuseau horaire par défaut du serveur dans les requêtes impliquant createTime

Lorsque vous soumettez un travail, la valeur de l'instance de travail est stockée dans le référentiel des travaux et normalisée sur UTC. Lorsque vous spécifiez des dates sous le format aaaa-MM-jj, comme dans createTime=[aaaa-MM-jj] ou createTime=[aaaa-MM-jj]:[aaa-MM-jj]:, vous devez convertir la chaîne de date aaaa-MM-jj en une plage spécifique d'heures UTC pour qu'elle corresponde aux valeurs createTime dans les enregistrements de table de l'instance de travail. Pour ce faire, l'application utilise le fuseau horaire par défaut du serveur qui traite la requête REST. Ce fuseau horaire est celui utilisé pour convertir la chaîne de date en plage UTC pour comparaison.

Le tableau ci-après illustre les données retournées par les paramètres de requête jobInstanceId=10:13.
JOBINSTANCEID CREATETIME(* d'après le fuseau horaire de server1) INSTANCESTATE EXITSTATUS
10 11-05-2015.01:10:00 COMPLETED SUCCESS
11 11-08-2014.02:20:00 COMPLETED SUCCESS
12 11-10-2015.03:30:00 FAILED FAILURE
13 11-11-2015:04:40:00 COMPLETED SUCCESS
*Etant donné que le référentiel des travaux stocke la valeur createTime au format UTC, il est important de comprendre que cette valeur est affichée dans les données du tableau compte tenu du fuseau horaire par défaut du serveur concerné (par exemple, "server1"). Si nous avions élaboré un tableau similaire depuis la perspective d'un second serveur (avec un fuseau horaire différent de celui de "server1"), le tableau présenterait un autre ensemble de valeurs de colonne CREATETIME, la différence étant imputable aux fuseaux horaires distincts. Le fuseau horaire par défaut du serveur traitant la requête REST est celui utilisé dans les exemples suivants pour mapper les paramètres de chaîne de date aaaa-MM-jj à des valeurs createTime UTC dans la base de données.
Les commandes suivantes retournent le même résultat quel que soit le serveur sur lequel elles sont émises :
  • jobInstanceId=11:13 renverrait les JOBINSTANCEID 11, 12 et 13.
  • jobInstanceId=>12 renverrait les JOBINSTANCEID 12 et 13.
  • jobInstanceId=<12 renverrait les JOBINSTANCEID 11 et 12.
  • jobInstanceId=11,12 renverrait les JOBINSTANCEID 11 et 12.
  • instanceState=FAILED renverrait JOBINSTANCEID 12..
  • exitStatus=SUCCESS renverrait les JOBINSTANCEID 10, 11 et 13.
Les commandes suivantes peuvent renvoyer des résultats différents pour des serveurs avec des fuseaux horaires par défaut différents. Dans ces exemples, elles sont émises vis à vis de "server1" (le serveur utilisé pour alimenter le tableau précédent) à la date et heure : 11-11-2015:07:00:00 dans le fuseau horaire par défaut du serveur.
  • createTime=>2d renverrait JOBINSTANCEID’s 12 et 13 (il y a 2 jours, à savoir le 9 novembre 2015, ou après)
  • createTime=<2d renverrait JOBINSTANCEID’s 10 et 11 (il y a 2 jours, à savoir le 9 novembre 2015, ou après)
  • createTime=2015-11-08:2015-11-11 renverrait des enregistrements avec JOBINSTANCEID’s 11,12 et 13.
  • createTime=2015-11-10 renverrait un enregistrement avec JOBINSTANCEID 12.
Exemple de réponse :
[{"instanceId":394,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":395,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":396,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":397,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":398,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""}]
Les valeurs purgeStatus suivantes peuvent être retournées :
COMPLETED
Indique que la purge du travail s'est intégralement terminée.
FAILED
Indique que la purge du travail a échoué.
STILL_ACTIVE
Indique que la purge du travail a échoué car ce dernier était encore actif.
JOBLOGS_ONLY
Indique que la purge de base de données a échoué mais que la purge des journaux de travaux a abouti.
NOT_LOCAL
Indique que la purge du travail a échoué car ce dernier n'est pas local.

Exécutions de travail

GET /ibm/api/batch/jobexecutions/job execution id
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.
Exemple de demande :

https://localhost:9443/ibm/api/batch/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/jobexecutions/job execution id/jobinstance
Cet URI retourne des informations détaillées sur l'instance de travail qui sont associées à une execution de travail spécifique.
GET /ibm/api/batch/jobinstances/job instance id/jobexecutions
Cet URI retourne des informations détaillées sur les exécutions de travail relatives à une instance de travail spécifiée. Cela inclut des liens vers des exécutions d'étape associées et des journaux de travaux.
GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number
Cet URI retourne des informations détaillées sur l'exécution de travail spécifiée relative à l'ID d'instance de travail spécifié. Cela inclut des liens vers des exécutions d'étape associées et des journaux de travaux.
Remarque : Le numéro de séquence d'exécution de travail signifie l'exécution de travail 0, 1, 2, etc. relative à l'instance de travail spécifiée.
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 pour 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
Cette URI renvoie un tableau JSON contenant les détails d'exécution de l'étape pour l'exécution de travail et le nom d'étape spécifiés.
GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number/stepexecutions/step name
Cette URI renvoie un tableau JSON contenant les détails d'exécution de l'étape pour l'instance de travail, l'exécution du travail et le nom d'étape spécifiés.
GET /ibm/api/batch/stepexecutions/step execution id
Cette URI renvoie un tableau JSON contenant les détails d'exécution de l'é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
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 = 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/jobinstances/job instance id/joblogs?type=text|zip
GET /ibm/api/batch/jobexecutions/job execution id/joblogs?type=text|zip
Le comportement de ces deux URI avec le paramètre type spécifié varie en fonction des valeurs.
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 = 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
Lorsque le paramètre part est spécifié, 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 requêtes Joblogs soumises à l'API REST par lots doivent être envoyées directement au programme d'exécution sur lequel est réalisé 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 requêtes Joblogs soumises à l'API REST par lots pour une instance de travail complète ne fonctionnent que si toutes les exécutions de travail pour cette instance ont été réalisé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

Nom du fichier : rwlp_batch_rest_api.html