Liberty リポジトリー[8.5.5.6 以降]

バッチ REST API 管理

WebSphere Application Server Liberty プロファイルには、バッチ・ジョブを管理するための RESTful 管理インターフェースが含まれています。

バッチ・ジョブに関連する基本操作は、実行依頼 (開始)、停止、再開、および状況の表示です。任意の HTTP REST クライアントを使用して、これらの操作を実行できます。要求の一部として実行依頼されるデータまたは応答の一部として返されるデータはすべて、JSON フォーマットです。

以下の例では、REST API で実行できる機能を示します。

要確認: バッチ REST インターフェースの Web アドレスはすべて、ルート Web アドレス https://{host}:{port}/ibm/api/batch で開始します。

ジョブ・インスタンス

GET /ibm/api/batch/jobinstances/
この URI は、ジョブ・インスタンスのリストを返します。照会パラメーターには、以下のものがあります。
  • page=[ページ番号]: 返すページ (レコードのサブセット) を指定します。デフォルトは 0 です。
  • pageSize=[1 ページ当たりのレコード数]: 1 ページ当たりのレコード数を指定します。デフォルトは、50 です。
要求の例:

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

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

応答の例:
[
    {
        "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
この URI は、指定したジョブ・インスタンスに関連したすべての実行など、指定したジョブ・インスタンスに関する詳細情報を返します。結果は、最も新しいものから古いものへの順に返されます。最新の結果は、リストの先頭に表示されます。
応答の例:
{
    "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/
この URI を使用して新規ジョブを実行依頼 (開始) します。
以下の例では、WAR モジュールにパッケージされたジョブを実行依頼するための要求本体 (JSON フォーマット) を示します。
{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJob.war",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}
以下の例では、EJB モジュールにパッケージされたジョブを実行依頼するための要求本体 (JSON フォーマット) を示します。
{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJobEJB.jar",
  "componentName" : "MyEJB",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}

applicationName は、バッチ・アプリケーションを指定しています。moduleName が指定されていない場合、これは必須です。指定されている場合、applicationName は、moduleName の .war または .jar 接尾部を省くことで、moduleName から派生されます。例えば、applicationName を指定せず、moduleName=SimpleBatchJob.war の場合、applicationName はデフォルトで SimpleBatchJob になります。

moduleName は、JSL などのジョブ成果物が含まれている、バッチ・アプリケーション内のモジュールを指定しています。ジョブは、モジュールのコンポーネント・コンテキストの下で実行依頼されます。applicationName が指定されていない場合、moduleName は必須です。 指定されている場合、moduleName は、applicationName に .war を追加することで、applicationName から派生されます。例えば、applicationName=SimpleBatchJob を指定し、moduleName を指定しなかった場合、moduleName はデフォルトで SimpleBatchJob.war になります。

componentName は、バッチ・アプリケーション EJB モジュール内の EJB コンポーネントを識別するものです。指定した場合、ジョブは、EJB のコンポーネント・コンテキストの下で実行依頼されます。
注: componentName は、モジュールが EJB モジュールの場合にのみ必須です。モジュールが WAR モジュールの場合は、componentName は必須ではありません。

jobXMLName に値を入力する必要があります。jobParameters の値はオプションです。

以下の応答例では、ジョブの実行依頼が正常に行われた場合を示します。
{
    "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
この URI を使用して、当該ジョブ・インスタンスに関連付けられている最新のジョブ実行が実行中の場合、そのジョブ実行を停止します。そうではない場合、API はエラーを返します。
PUT /ibm/api/batch/jobinstances/job instance id?action=restart
この URI を使用して、当該ジョブ・インスタンスに関連付けられている最新のジョブ実行が STOPPED または FAILED 状態の場合にのみ、そのジョブ実行を再開します。当該インスタンスに関連付けられているジョブ実行がない場合、または最新のジョブ実行が COMPLETED 状態の場合、API はエラーを返します。
PUT /ibm/api/batch/jobinstances/job instance id?action=restart&reusePreviousParams=true
この URI を使用して、最新のジョブ実行を再始動して、このジョブ・インスタンスに関連付けられている直前の実行からのジョブ・パラメーターを再利用します。以前の実行が STOPPED または FAILED 状態になっている必要があります。このインスタンスに関連付けられているジョブ実行がない場合、または最新のジョブ実行が COMPLETED 状態にある場合、API はエラーを返します。なお、reusePreviousParams はオプションの設定です。デフォルト設定は reusePreviousParams=false です。
注: reusePreviousParams=true の場合、現行再始動要求の一部として実行依頼されるすべてのジョブ・パラメーターは、それより前のジョブ・パラメーターよりも優先されます。現在のパラメーターは、同じジョブ・パラメーター・キー名を持つ以前のパラメーターをオーバーライドします。
DELETE /ibm/api/batch/jobinstances/job instance id
この URI を使用して、当該ジョブ・インスタンスに関連付けられているすべてのデータベース項目およびジョブ・ログをパージします。この API は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。ジョブ・ログの削除中にエラーが発生した場合、ジョブ・ストア・データベースからのジョブ・インスタンス・データの削除試行は行われません。
DELETE /ibm/api/batch/jobinstances/job instance id?purgeJobStoreOnly=true
この URI を使用して、当該ジョブ・インスタンスに関連付けられているジョブ・ストア・データベース項目のみをパージします。 purgeJobStoreOnly=true の場合、当該ジョブ・インスタンスに関連付けられているジョブ・ログのパージ試行は行われません。デフォルト設定は purgeJobStoreOnly=false です。この API は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。

ジョブ実行

GET /ibm/api/batch/jobexecutions/job execution id
この URI は、指定したジョブ実行に関する詳細な情報を返します。関連するステップ実行およびジョブ・ログへのリンクも含まれます。
要求の例:

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

応答の例:
{
    "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
この URI は、指定したジョブ実行に関する詳細な情報を返します。関連するステップ実行およびジョブ・ログへのリンクも含まれます。
PUT /ibm/api/batch/jobexecutions/job execution id?action=stop
この URI を使用して、指定した実行中のジョブ実行を停止します。必須パラメーターには、action = stop, restart があります。
PUT /ibm/api/batch/jobexecutions/job execution id?action=restart
この URI を使用して、指定したジョブ実行を再開します。必須パラメーターには、action = stop, restart があります。

ステップ実行

GET /ibm/api/batch/jobexecutions/job execution id/stepexecutions
この URI は、指定したジョブ実行のすべてのステップ実行詳細が含まれた JSON 配列を返します。 ジョブに区分ステップが含まれている場合、区分情報が返され、各ステップ内にリストされます。
要求の例:

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

以下の例では、パーティション・ステップに対する応答を示します。
[ 
   { 
      "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
この URI は、指定したジョブ実行およびステップ名に対するステップ実行詳細が含まれた JSON 配列を返します。
GET /ibm/api/batch/jobeinstances/job instance id/jobexecutions/job execution sequence number/stepexecutions/step name
この URI は、指定したジョブ・インスタンス、ジョブ実行、およびステップ名に対するステップ実行詳細が含まれた JSON 配列を返します。
GET /ibm/api/batch/stepexecutions/step execution id
この URI は、指定したステップ実行のステップ実行詳細が含まれた JSON 配列を返します。

ジョブ・ログ

GET /ibm/api/batch/jobinstances/job instance id/joblogs
この URI は、指定したジョブ・インスタンスのすべてのジョブ・ログ・パートへの REST リンクが含まれた JSON 配列を返します。
GET /ibm/api/batch/jobexecutions/job execution id/joblogs
この URI は、指定したジョブ実行のすべてのジョブ・ログ・パートへの REST リンクが含まれた JSON 配列を返します。
重要: 以下の例では、REST リンクのフォーマットを示します。
ジョブ実行に以下のジョブ・ログ・パートが含まれている場合:
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
その場合、対応する REST リンクは、以下のとおりです。
/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
オプション・パラメーターには、以下のものがあります。
type = text
text を指定した場合、すべてのジョブ・ログをプレーン・テキストとして返します。すべてのジョブ・ログ・パートは一緒に集約されます。一緒に集約される際に異なるパーツを区切るために、パートを区切るヘッダーおよびフッター・レコードがストリームに挿入されます。type = text はデフォルト設定です。
type = zip
zip を指定した場合、指定したジョブ・インスタンスまたはジョブ実行のすべてのジョブ・ログを圧縮ファイルとして返します。 圧縮ファイルでは、ジョブ・ログのディレクトリー構造が保持されます。
GET /ibm/api/batch/jobexecutions/job execution id/joblogs?part=path to part&type=text|zip
この URI は、プレーン・テキスト (type=text) または圧縮ファイル (type=zip) としてジョブ・ログ・パートを返します。デフォルト設定は type=text です。

HTTP 戻りコード

REST API に対して以下の HTTP 戻りコードが返されます。
  • HTTP 200 OK
  • HTTP 201 新規リソースが正常に作成されました。
  • HTTP 202 要求を受け入れましたが、処理は完了していません。
  • HTTP 400 無効なパラメーターが指定された、正しくない要求。詳しくは、返されたメッセージを参照してください。
  • HTTP 401 当該リソースにアクセスする権限がありません。
  • HTTP 403 認証が失敗しました。
  • HTTP 404 要求されたリソースが見つからないか、存在しません。
  • HTTP 409 要求がリソースの現在の状態に矛盾しています。詳しくは、返されたメッセージを参照してください。
  • HTTP 500 内部サーバー・エラー。

分散サーバー・バッチ環境での STOP 要求

バッチ REST API に送信される停止要求は、ジョブが実行されている executor に直接送信する必要があります。ディスパッチャー、またはジョブが実行されていない executor に停止要求が送信された場合、HTTP 302 リダイレクト応答メッセージによって、要求は正しい executor にリダイレクトされます。HTTP 302 リダイレクト応答の location フィールドが、停止要求で使用するのに正しい URL を示します。

分散サーバー・バッチ環境での JOBLOGS 要求

バッチ REST API に送信されるジョブ・ログ要求は、ジョブが実行されている executor に直接送信する必要があります。ディスパッチャー、またはジョブが実行されていない executor にジョブ・ログ要求が送信された場合、HTTP 302 リダイレクト応答メッセージによって、要求は正しい executor にリダイレクトされます。HTTP 302 リダイレクト応答の location フィールドが、ジョブ・ログ要求で使用するのに正しい URL を示します。
注: ジョブ・インスタンス全体についてバッチ REST API に送信されたジョブ・ログ要求が機能するのは、当該インスタンスのすべてのジョブ実行が同じ executor で実行された場合のみです。それぞれ異なる executor で実行が行われた場合、当該インスタンスに対するジョブ・ログ要求は失敗します。この場合、各実行のジョブ・ログを個別にフェッチする必要があります。

分散サーバー・バッチ環境でのパージ要求

バッチ REST API に送信されるパージ要求は、ジョブが実行されている executor に直接送信する必要があります。ディスパッチャー、またはジョブが実行されていない executor にパージ要求が送信された場合、HTTP 302 リダイレクト応答メッセージによって、要求は正しい executor にリダイレクトされます。HTTP 302 リダイレクト応答の location フィールドが、パージ要求で使用するのに正しい URL を示します。
注: ジョブ・インスタンス全体についてバッチ REST API に送信されたパージ要求が機能するのは、当該インスタンスのすべてのジョブ実行が同じ executor で実行された場合のみです。それぞれ異なる executor で実行が行われた場合、当該インスタンスに対するパージ要求は失敗します。

トピックのタイプを示すアイコン 参照トピック

インフォメーション・センターに関するご使用条件 | フィードバック


タイム・スタンプ・アイコン 最終更新: 2015 年 6 月 17日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_batch_rest_api
ファイル名: rwlp_batch_rest_api.html