Batch REST API
WebSphere Application Server Liberty には、バッチ・ジョブを管理するための RESTful 管理インターフェースが含まれています。
バッチ・ジョブに関連する基本操作は、実行依頼 (開始)、停止、再開、および状況の表示です。任意の HTTP REST クライアントを使用して、これらの操作を実行できます。要求の一部として実行依頼されるデータまたは応答の一部として返されるデータはすべて、JSON フォーマットです。
以下の例では、REST API で実行できる機能を示します。
実行依頼者のみであるユーザー ID による REST API
HTTPS で REST API を呼び出すユーザー ID に batchSubmitter ロールへのアクセス権限のみが付与されている場合、 GET ("read") URL で戻された結果はフィルタリングされます。 実行依頼者は、自分が実行依頼したジョブ・インスタンスに関連付けられたインスタンスおよび実行のデータのみを参照します。これに対し、batchAdmin および batchMonitor のロールへのアクセス権限が付与されたユーザー ID は、(任意のパラメーター・セットで任意の URL によって戻された) すべてのインスタンスおよび実行のデータを参照することができます。
batchSubmitter ロールのみに対するアクセス権限を持つユーザー ID が参照する結果は、まず、所定の URL の文書に記述されているように、標準パラメーターでフィルタリングされます。その後、さらにフィルタリングが実行され、その実行依頼者自身が実行依頼したジョブ・インスタンスに関連付けられたインスタンスおよび実行のデータのみが返されます。
詳しくは、『Liberty プロファイル・バッチ環境の保護』を参照してください。
ジョブ・インスタンス
- 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/v2/jobinstances/
- この URI は、以下の照会パラメーターによってフィルタリングされたジョブ・インスタンスのリストを返します。
- jobInstanceId=[instanceId]:[instanceId]: instanceId 範囲内 (両端含む) のジョブ・インスタンスを返します。
- jobInstanceId=>[instanceId]: 指定した instanceId 以上のジョブ・インスタンスを返します。
- jobInstanceId=<[instanceId]: 指定した instanceId 以下のジョブ・インスタンスを返します。
- jobinstanceId=[instanceId],[instanceId],[instanceId]: 指定したジョブ・インスタンスを返します。
- createTime=[yyyy-MM-dd]:[yyy-MM-dd]: 日付範囲内 (両端含む) のジョブ・インスタンスを返します。
- createTime=[yyyy-MM-dd]: 指定日のジョブ・インスタンスを返します。
- createTime=>3d: 3 日前の日以降に作成されたジョブ・インスタンスを返します。例えば、createTime は、3 日前の日の開始時以降になります。
- createTime=<3d: 3 日前の日以前に作成されたジョブ・インスタンスを返します。例えば、createTime は、3 日前の日の終了時以降になります。
- instanceState=[state],[state]: 指定した状態のジョブ・インスタンスを返します。有効なインスタンス状態は、SUBMITTED、JMS_QUEUED、JMS_CONSUMED、DISPATCHED、FAILED、STOPPED、COMPLETED、および ABANDONED です。
- exitStatus=[string]: 終了状況ストリングに一致するジョブ・インスタンスを返します。ストリング基準では、ストリング内の任意の場所でワイルドカード (*) 演算子を使用できます。
- page=[ページ番号]: 返すページ (レコードのサブセット) を指定します。デフォルトは 0 です。
- pageSize=[1 ページ当たりのレコード数]: 1 ページ当たりのレコード数を指定します。デフォルトは、50 です。
注: createTime に関する照会におけるサーバー・デフォルト・タイム・ゾーンの役割ジョブを実行依頼すると、ジョブ・インスタンスの createTime がジョブ・リポジトリーに保管され、UTC に正規化されます。createTime=[yyyy-MM-dd] や createTime=[yyyy-MM-dd]:[yyy-MM-dd]: のように yyyy-MM-dd を使用して日付を指定する際には、ジョブ・インスタンス・テーブル・レコード内の createTime 値に対して突き合わせるために、yyyy-MM-dd 日付ストリングを特定の UTC 時刻範囲に変換する必要があります。この機能を実行するために、アプリケーションは、REST 要求を処理するサーバーのデフォルト・タイム・ゾーンを使用します。突き合わせ対象とする UTC 時刻範囲に日付ストリングを変換するために使用されるのはこのサーバーのタイム・ゾーンです。
以下の表に、照会パラメーター jobInstanceId=10:13 によって返されるデータを示します。
*ジョブ・リポジトリーは createTime を UTC 形式で保管するため、この表のデータが、特定のサーバー (例えば、「server1」) のサーバー・デフォルト・タイム・ゾーンを使用してフォーマット設定された createTime を示していることを理解することが重要になります。「server1」とは異なる別のデフォルト・タイム・ゾーンを持つ別のサーバーの観点から同様の表を作成した場合、対応するタイム・ゾーン・ベースの差異を持つ異なる CREATETIME 列値セットを示すことになります。以下の例でデータベースの UTC createTime 値に yyyy-MM-dd 日付ストリング・パラメーターをマップするのに使用されるのは、REST 要求を処理するサーバーのデフォルト・タイム・ゾーンです。JOBINSTANCEID CREATETIME(* 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 以下のコマンドでは、発行対象サーバーに関係なく、同じ結果が返されます。- jobInstanceId=11:13 は JOBINSTANCEID 11、12、および 13 を返します。
- jobInstanceId=>12 は JOBINSTANCEID 12 および 13 を返します。
- jobInstanceId=<12 は JOBINSTANCEID 11 および 12 を返します。
- jobInstanceId=11,12 は JOBINSTANCEID 11 および 12 を返します。
- instanceState=FAILED は JOBINSTANCEID 12 を返します。
- exitStatus=SUCCESS は JOBINSTANCEID 10、11、および 13 を返します。
以下のコマンドでは、デフォルト・タイム・ゾーンが異なるサーバーに対して異なる結果が返される可能性があります。これらの例では、日時 11-11-2015:07:00:00 (サーバー・デフォルト・タイム・ゾーン) に「server1」(上の表にデータを取り込むために使用したのと同じサーバー) に対して発行されます。- createTime=>2d は、(2 日前の 11-09-2015 以降の) JOBINSTANCEID 12 および 13 を返します。
- createTime=<2d は、(2 日前の 11-09-2015 以前の) JOBINSTANCEID 10 および 11 を返します。
- createTime=2015-11-08:2015-11-11 は、JOBINSTANCEID が 11、12、および 13 のレコードを返します。
- createTime=2015-11-10 は、JOBINSTANCEID 12 のレコードを返します。
- 要求の例:
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
GET /ibm/api/batch/v3/jobinstances/
GET /ibm/api/batch/v2/job instances/ URI のすべての関数の他に、 この URI は、以下の照会パラメーターによってフィルタリングされたジョブ・インスタンスのリストを返します。
- lastUpdatedTime=[yyyy-MM-dd]: 指定日に最終更新されたジョブ・インスタンスを返します。 この時刻値は、インスタンスの状態の遷移に応じて更新されます。例えば、SUBMITTED から DISPATCHED です。
- jobParameter.[paramName]=[paramValue]: 提供された名前と値のペアを ジョブ・パラメーターとして持つ実行を指定してジョブ・インスタンスを返します。例えば、 jobParameter.jesJobName=myJobName です。ストリング基準では、ストリング内の任意の場所でワイルドカード (*) 演算子を使用できます。
- sort=[string],[string]: 結果をソートするパラメーター (複数可) を指定します。パラメーターの接頭部に - 文字を使用すると、 ソートが降順に行われるように指定されます。例えば、sort=submitter は、 結果をサブミッターにより昇順でソートします。sort=submitter,-lastUpdatedTime を指定すると、結果はサブミッターによりまず昇順でソートされてから、 次に lastUpdatedTime により降順でソートされます。
GET /ibm/api/batch/v4/jobinstances/
GET /ibm/api/batch/v3/job instances/ URI のすべての関数の他に、この URI は、以下の照会パラメーターによってフィルタリングされたジョブ・インスタンスのリストを返します。
- submitter=[user]: 指定されたユーザーによりサブミットされたジョブ・インスタンスをすべて返します。ストリング基準では、ストリング内の任意の場所でワイルドカード (*) 演算子を使用できます。
- appName=[name]: 指定されたアプリケーション名を持つすべてのジョブ・インスタンスを返します。 単純なアプリケーション名でも、完全なアプリケーション-モジュール-コンポーネント名でもかまいません。例えば、 MyApp または MyApp#MyApp.war を検索すると、アプリケーション名 MyApp とモジュール名 MyApp.war を持つジョブ・インスタンスが返されます。ストリング基準では、ストリング内の任意の場所でワイルドカード (*) 演算子を使用できます。
- jobName=[name]: 指定されたジョブ名を持つすべてのジョブ・インスタンスを返します。ストリング基準では、ストリング内の任意の場所でワイルドカード (*) 演算子を使用できます。
- ignoreCase=true: デフォルトでは、すべてのテキスト・マッチングは大/小文字を区別します。このオプションを指定すると、 すべてのテキスト検索語において大/小文字が区別されない設定に変更されます。
- lastUpdatedTime=[yyyy-MM-dd]:[yyyy-MM-dd]: 日付範囲内 (両端含む) に最終更新されたジョブ・インスタンスを返します。
- lastUpdatedTime=>3d: 3 日前の日以降に最終更新されたジョブ・インスタンスを返します。例えば、lastUpdatedTime は、3 日前の日の開始時以降になります。
- lastUpdatedTime=<3d: 3 日前の日以前に最終更新されたジョブ・インスタンスを返します。例えば、lastUpdatedTime は、3 日前の日の終了時以降になります。
注: appName、exitStatus、 jobName、および submitter の各パラメーターは、複数回適用できます。この結果には、指定された値と一致するジョブ・インスタンスおよび指定された値のジョブ・インスタンスがすべて含まれます。例えば、 jobinstances?submitter=Alice&submitter=Bob を指定すると、Alice または Bob がサブミットしたジョブ・インスタンスがすべて返されます。- 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 の値はオプションです。
- バッチ・アプリケーション内で META-INF/batch-jobs の下にパッケージされている JSL ジョブ定義を使用する代わりに、REST ジョブ実行依頼要求の一部としてインラインで JSL を渡すことができます。インラインで実行依頼された JSL は常に、バッチ・アプリケーションでパッケージされている JSL をオーバーライドします。HTTP 要求の一部としてインラインで JSL を実行依頼する場合、2 つの方法を使用できます。
- ジョブ実行依頼要求内に JSON プロパティーとして JSL を含めます。プロパティー jobXML を JSON オブジェクトに追加し、プロパティーの値に JSON ストリングとして JSL ファイルの内容全体を追加します。注: XML ストリングを適切にエスケープして JSON パーサーによって解析できるようにする必要があります。ほとんどの JSON ライブラリーは自動的にこれを行います。以下の例では、JSL が JSON によってインラインで渡されている単一パート HTTP 要求を使用するジョブを実行依頼する要求本体を示します。
{ "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>" }
注: jobXML フィールドは、JSON パーサーによって解析し、有効な JSON オブジェクトにマーシャルする必要があります。インライン JSL のジョブ ID 情報がジョブ名に使用されるため、jobXMLName フィールドはオプションです。 - HTTP マルチパート・フォームを使用します。
HTTP マルチパート・フォームを使用する場合、JSON ジョブ実行依頼データおよび XML ジョブ定義を HTTP 本体の 2 つの別個のパートとして実行依頼する必要があります。
マルチパート・フォームの JSON パートの名前は jobdata でなければならず、同フォームの XML パートの名前は jsl でなければなりません。
マルチパート・フォームを使用する場合、XML を JSON ストリングにマーシャルする必要はありません。
以下の例に示す HTTP 要求では、jsl メッセージ・パートを使用してインラインで JSL が渡されているマルチパート HTTP 要求を使用するジョブを実行依頼します。
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--
注: インライン JSL のジョブ ID 情報がジョブ名に使用されるため、jobXMLName フィールドはオプションです。
- ジョブ実行依頼要求内に JSON プロパティーとして JSL を含めます。プロパティー jobXML を JSON オブジェクトに追加し、プロパティーの値に JSON ストリングとして JSL ファイルの内容全体を追加します。
- 以下の応答例では、ジョブの実行依頼が正常に行われた場合を示します。
{ "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 は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。ジョブ・ログの削除時にエラーが発生した場合、ジョブ・ストア・データベースからのジョブ・インスタンス・データの削除は試行されません。照会パラメーターには、以下のものがあります。
- purgeJobStoreOnly=true|false: purgeJobStoreOnly=true の場合、当該ジョブ・インスタンスに関連付けられているジョブ・ログのパージ試行は行われません。デフォルト設定は purgeJobStoreOnly=false です。この API は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。注: シングル・パージ API を使用した場合、パージ応答メッセージは返されません。
- purgeJobStoreOnly=true|false: purgeJobStoreOnly=true の場合、当該ジョブ・インスタンスに関連付けられているジョブ・ログのパージ試行は行われません。デフォルト設定は purgeJobStoreOnly=false です。この API は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。
- DELETE /ibm/api/batch/v2/jobinstances/
- この URI は、以下のパージ・フィルター・パラメーターによって返されたジョブ・インスタンスに関連したすべてのデータベース項目およびジョブ・ログをパージします。注: DELETE インターフェースを実行してジョブを削除する前には、GET インターフェースを使用してジョブをリストし、パージすべき正しいジョブであることを確認することをお勧めします。
- page=[ページ番号]: 返すページ (レコードのサブセット) を指定します。デフォルトは 0 です。
- pageSize=[1 ページ当たりのレコード数]: 1 ページ当たりのレコード数を指定します。デフォルトは、50 です。
- purgeJobStoreOnly=true|false: purgeJobStoreOnly=true の場合、当該ジョブ・インスタンスに関連付けられているジョブ・ログのパージ試行は行われません。デフォルト設定は purgeJobStoreOnly=false です。この API は、ジョブ・インスタンスにアクティブなジョブ実行がある場合、エラーを返します。
- jobInstanceId=[instanceId]:[instanceId]: instanceId 範囲内 (両端含む) のジョブ・インスタンスをパージします。
- jobInstanceId=>[instanceId]: 指定した instanceId 以上のジョブ・インスタンスをパージします。
- jobInstanceId=<[instanceId]: 指定した instanceId 以下のジョブ・インスタンスをパージします。
- jobinstanceId=[instanceId],[instanceId],[instanceId]: 指定したジョブ・インスタンスをパージします。
- createTime=[yyyy-MM-dd]:[yyy-MM-dd]: 日付範囲内 (両端含む) のジョブ・インスタンスを返します。
- createTime=[yyyy-MM-dd]: 指定日のジョブ・インスタンスを返します。
- createTime=>3d: 3 日前の日以降に作成されたジョブ・インスタンスを返します。例えば、createTime は、3 日前の日の開始時以降になります。
- createTime=<3d: 3 日前の日以前に作成されたジョブ・インスタンスを返します。例えば、createTime は、3 日前の日の終了時以降になります。
- instanceState=[state],[state]: 指定した状態のジョブ・インスタンスをパージします。有効なインスタンス状態は、SUBMITTED、JMS_QUEUED、JMS_CONSUMED、DISPATCHED、FAILED、STOPPED、COMPLETED、および ABANDONED です。
- exitStatus=[string]: 終了状況ストリングに一致するジョブ・インスタンスを返します。ストリング基準では、両端にワイルドカード (*) 演算子を使用できます。
注: デフォルトでは、page および pageSize パラメーターが指定されていない限り、最大で 50 件のレコードがパージされます。注: createTime に関する照会におけるサーバー・デフォルト・タイム・ゾーンの役割ジョブを実行依頼すると、ジョブ・インスタンスの createTime がジョブ・リポジトリーに保管され、UTC に正規化されます。createTime=[yyyy-MM-dd] や createTime=[yyyy-MM-dd]:[yyy-MM-dd]: のように yyyy-MM-dd を使用して日付を指定する際には、ジョブ・インスタンス・テーブル・レコード内の createTime 値に対して突き合わせるために、yyyy-MM-dd 日付ストリングを特定の UTC 時刻範囲に変換する必要があります。これを行うために、アプリケーションは、REST 要求を処理するサーバーのデフォルト・タイム・ゾーンを使用します。突き合わせ対象とする UTC 時刻範囲に日付ストリングを変換するために使用されるのはこのサーバーのタイム・ゾーンです。
以下の表に、照会パラメーター jobInstanceId=10:13 によって返されるデータを示します。
*ジョブ・リポジトリーは createTime を UTC 形式で保管するため、この表のデータが、特定のサーバー (例えば、「server1」) のサーバー・デフォルト・タイム・ゾーンを使用してフォーマット設定された createTime を示していることを理解することが重要になります。「server1」とは異なる別のデフォルト・タイム・ゾーンを持つ別のサーバーの観点から同様の表を作成した場合、対応するタイム・ゾーン・ベースの差異を持つ異なる CREATETIME 列値セットを示すことになります。以下の例でデータベースの UTC createTime 値に yyyy-MM-dd 日付ストリング・パラメーターをマップするのに使用されるのは、REST 要求を処理するサーバーのデフォルト・タイム・ゾーンです。JOBINSTANCEID CREATETIME(* 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 以下のコマンドでは、発行対象サーバーに関係なく、同じ結果が返されます。- jobInstanceId=11:13 は JOBINSTANCEID 11、12、および 13 を返します。
- jobInstanceId=>12 は JOBINSTANCEID 12 および 13 を返します。
- jobInstanceId=<12 は JOBINSTANCEID 11 および 12 を返します。
- jobInstanceId=11,12 は JOBINSTANCEID 11 および 12 を返します。
- instanceState=FAILED は JOBINSTANCEID 12 を返します。
- exitStatus=SUCCESS は JOBINSTANCEID 10、11、および 13 を返します。
以下のコマンドでは、デフォルト・タイム・ゾーンが異なるサーバーに対して異なる結果が返される可能性があります。これらの例では、日時 11-11-2015:07:00:00 (サーバー・デフォルト・タイム・ゾーン) に「server1」(上の表にデータを取り込むために使用したのと同じサーバー) に対して発行されます。- createTime=>2d は、(2 日前の 11-09-2015 以降の) JOBINSTANCEID 12 および 13 を返します。
- createTime=<2d は、(2 日前の 11-09-2015 以前の) JOBINSTANCEID 10 および 11 を返します。
- createTime=2015-11-08:2015-11-11 は、JOBINSTANCEID が 11、12、および 13 のレコードを返します。
- createTime=2015-11-10 は、JOBINSTANCEID 12 のレコードを返します。
- 応答の例:
[{"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":""}]
- 以下の purgeStatus 値が返される可能性があります。
- COMPLETED
- ジョブのパージが正常に完了したことを示します。
- FAILED
- ジョブのパージが失敗したことを示します。
- STILL_ACTIVE
- ジョブがまだアクティブであるためジョブのパージが失敗したことを示します。
- JOBLOGS_ONLY
- データベースのパージが失敗したが、ジョブ・ログは正常にパージされたことを示します。
- NOT_LOCAL
- ジョブがローカルではないためジョブのパージが失敗したことを示します。
ジョブ実行
- GET /ibm/api/batch/jobexecutions/job execution id
- この URI は、指定したジョブ実行に関する詳細な情報を返します。関連するステップ実行およびジョブ・ログへのリンクも含まれます。
- 要求の例:
https://localhost:9443/ibm/api/batch/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/jobexecutions/job execution id/jobinstance
- この URI は、指定したジョブ実行に関連するジョブ・インスタンスに関する詳細情報を返します。
- GET /ibm/api/batch/jobinstances/job instance id/jobexecutions
- この URI は、指定したジョブ・インスタンスのジョブ実行に関する詳細情報を返します。これには、関連付けられたステップ実行およびジョブ・ログへのリンクが含まれます。
- GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number
- この URI は、指定したジョブ・インスタンス ID に関連する指定したジョブ実行に関する詳細情報を返します。これには、関連付けられたステップ実行およびジョブ・ログへのリンクが含まれます。注: job execution sequence number (ジョブ実行順序番号) とは、指定したジョブ・インスタンスに関連する 0 番目、1 番目、2 番目などのジョブ実行を意味します。
- 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/jobinstances/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 リンクのフォーマットを示します。ジョブ実行に以下のジョブ・ログ・パートが含まれている場合:
その場合、対応する 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
/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
- オプション・パラメーターには、以下のものがあります。
- type = text
- text を指定した場合、すべてのジョブ・ログをプレーン・テキストとして返します。すべてのジョブ・ログ・パートは一緒に集約されます。一緒に集約される際に異なるパーツを区切るために、パートを区切るヘッダーおよびフッター・レコードがストリームに挿入されます。
- type = zip
- zip を指定した場合、指定したジョブ・インスタンスまたはジョブ実行のすべてのジョブ・ログを圧縮ファイルとして返します。 圧縮ファイルでは、ジョブ・ログのディレクトリー構造が保持されます。
- GET /ibm/api/batch/jobinstances/job instance id/joblogs?type=text|zip
- GET /ibm/api/batch/jobexecutions/job execution id/joblogs?type=text|zip
- type パラメーターが指定されたこれら 2 つの URI の動作は、値によって異なります。
- type = text
- text を指定した場合、すべてのジョブ・ログをプレーン・テキストとして返します。すべてのジョブ・ログ・パートは一緒に集約されます。一緒に集約される際に異なるパーツを区切るために、パートを区切るヘッダーおよびフッター・レコードがストリームに挿入されます。
- type = zip
zip を指定した場合、指定したジョブ・インスタンスまたはジョブ実行のすべてのジョブ・ログを圧縮ファイルとして返します。 圧縮ファイルでは、ジョブ・ログのディレクトリー構造が保持されます。
- GET /ibm/api/batch/jobexecutions/job execution id/joblogs?part=path to part&type=text|zip
- part パラメーターが指定されたこの URI は、プレーン・テキスト (type=text) または圧縮ファイル (type=zip) としてジョブ・ログ・パートを返します。デフォルト設定は type=text です。
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 を示します。