
![[8.5.5.6 或更新版本]](../ng_v8556.gif)
批次 REST API 管理
WebSphere Application Server Liberty 設定檔含有 RESTful 管理介面,用來管理您的批次工作。
與批次工作相關聯的基本作業包括:提交(啟動)、停止、重新啟動,以及檢視狀態。您可以使用任何 HTTP REST 用戶端,來執行這些作業。隨要求提交的資料或隨回應傳回的資料,都是 JSON 格式。
下列範例顯示您可以使用 REST API 執行的功能。
工作實例
- GET /ibm/api/batch/jobinstances/
- 此 URI 會傳回工作實例清單。查詢參數包括:
- page=[頁碼]:指出要傳回的頁面(記錄子集)。預設值為 0。
- pageSize=[每頁記錄數]:指出每頁記錄數。預設值為 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 用來提交(啟動)新工作。下列範例說明要求內文,該要求內文以 JSON 格式來提交包裝在 WAR 模組中的工作:
{ "applicationName" : "SimpleBatchJob", "moduleName" : "SimpleBatchJob.war", "jobXMLName" : "test_batchlet_jsl", "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"} }
下列範例說明要求內文,該要求內文以 JSON 格式來提交包裝在 EJB 模組中的工作:{ "applicationName" : "SimpleBatchJob", "moduleName" : "SimpleBatchJobEJB.jar", "componentName" : "MyEJB", "jobXMLName" : "test_batchlet_jsl", "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"} }
applicationName 用來識別批次應用程式。這是必要的,除非指定了 moduleName,在此情況下,applicationName 會衍生自 moduleName,並修整 moduleName 的 .war 或 .jar 字尾。舉例來說,如果未提供 applicationName,且 moduleName=SimpleBatchJob.war,則 applicationName 會預設為 SimpleBatchJob。
moduleName 用來識別批次應用程式內包含工作構件(例如 JSL)的模組。工作會放在模組的元件環境定義之下提交。moduleName 是必要的,除非指定了 applicationName,在此情況下,moduleName 會衍生自 applicationName,並在 applicationName 之後附加 .war。舉例來說,如果提供 applicationName=SimpleBatchJob,但未提供 moduleName,則 moduleName 會預設為 SimpleBatchJob.war。
componentName 用來識別批次應用程式 EJB 模組內的 EJB 元件。若有指定,則會在 EJB 的元件環境定義之下提交工作。註: 只有在模組是 EJB 模組時,才需要 componentName。如果模組是 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 來重新啟動它。如果這個實例沒有相關聯的工作執行,或者最新的工作執行是「已完成」狀態,API 會傳回錯誤。
- PUT /ibm/api/batch/jobinstances/job instance id?action=restart&reusePreviousParams=true
- 這個 URI 用來重新啟動最近一次的工作執行,並重複使用此工作實例相關聯之先前執行中的工作參數。先前的執行必須是「停止」或「失敗」狀態。如果這個實例沒有相關聯的工作執行,或者最新的工作執行是「已完成」狀態,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 會傳回 JSON 陣列,內含指向指定工作實例之所有工作日誌組件的 REST 鏈結。
- GET /ibm/api/batch/jobexecutions/job execution id/joblogs
- 這個 URI 會傳回 JSON 陣列,內含指向指定工作執行之所有工作日誌組件的 REST 鏈結。重要: 下列範例顯示 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
- 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 回覆碼
- HTTP 200 正常
- HTTP 201 已順利建立新資源。
- HTTP 202 已接受要求,但處理程序未完成。
- HTTP 400 具有無效參數的不正確要求。如需詳細資料,請參閱傳回的訊息。
- HTTP 401 未獲授權存取此資源。
- HTTP 403 鑑別失敗。
- HTTP 404 所要求的資源找不到或者不存在。
- HTTP 409 該要求與該資源的現行狀態衝突。如需詳細資料,請參閱傳回的訊息。
- HTTP 500 內部伺服器錯誤。
分散式伺服器批次環境中的 STOP 要求
傳送至批次 REST API 的停止要求,必須直接傳送至正在執行該工作的執行程式。如果停止要求是傳送至不在執行工作的分派器或執行程式,則會透過 HTTP 302 重新導向回應訊息,將該要求重新導向至正確的執行程式。HTTP 302 重新導向回應中的位置欄位會指出用於該停止要求的正確 URL。