Liberty 儲存庫[8.5.5.6 或更新版本]

批次 REST API 管理

WebSphere Application Server Liberty 設定檔含有 RESTful 管理介面,用來管理您的批次工作。

與批次工作相關聯的基本作業包括:提交(啟動)、停止、重新啟動,以及檢視狀態。您可以使用任何 HTTP REST 用戶端,來執行這些作業。隨要求提交的資料或隨回應傳回的資料,都是 JSON 格式。

下列範例顯示您可以使用 REST API 執行的功能。

記住: 批次 REST 介面的網址都是以根網址開頭:https://{host}:{port}/ibm/api/batch

工作實例

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 鏈結的格式。
如果您的工作執行含有下列工作日誌組件:
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 正常
  • HTTP 201 已順利建立新資源。
  • HTTP 202 已接受要求,但處理程序未完成。
  • HTTP 400 具有無效參數的不正確要求。如需詳細資料,請參閱傳回的訊息。
  • HTTP 401 未獲授權存取此資源。
  • HTTP 403 鑑別失敗。
  • HTTP 404 所要求的資源找不到或者不存在。
  • HTTP 409 該要求與該資源的現行狀態衝突。如需詳細資料,請參閱傳回的訊息。
  • HTTP 500 內部伺服器錯誤。

分散式伺服器批次環境中的 STOP 要求

傳送至批次 REST API 的停止要求,必須直接傳送至正在執行該工作的執行程式。如果停止要求是傳送至不在執行工作的分派器或執行程式,則會透過 HTTP 302 重新導向回應訊息,將該要求重新導向至正確的執行程式。HTTP 302 重新導向回應中的位置欄位會指出用於該停止要求的正確 URL。

分散式伺服器批次環境中的 JOBLOGS 要求

傳送至批次 REST API 的工作日誌要求,必須直接傳送至正在執行該工作的執行程式。如果工作日誌要求是傳送至不在執行工作的分派器或執行程式,則會透過 HTTP 302 重新導向回應訊息,將該要求重新導向至正確的執行程式。HTTP 302 重新導向回應中的位置欄位會指出用於該工作日誌要求的正確 URL。
註: 該工作實例的所有工作執行必須都在相同執行程式上執行,針對整個工作實例傳送給批次 REST API 的工作日誌要求才會生效。如果工作執行是在不同執行程式上執行,針對該實例的工作日誌要求將會失敗。在此情況下,必須個別提取每一項執行的工作日誌。

分散式伺服器批次環境中的清除要求

傳送至批次 REST API 的清除要求,必須直接傳送至正在執行該工作的執行程式。如果清除要求是傳送至不在執行工作的分派器或執行程式,則會透過 HTTP 302 重新導向回應訊息,將該要求重新導向至正確的執行程式。HTTP 302 重新導向回應中的位置欄位會指出用於該清除要求的正確 URL。
註: 該工作實例的所有工作執行必須都在相同執行程式上執行,針對整個工作實例傳送給批次 REST API 的清除要求才會生效。如果工作執行是在不同執行程式上執行,針對該實例的清除要求將會失敗。

指示主題類型的圖示 參照主題

資訊中心條款 | 意見


「時間戳記」圖示 前次更新: 2015 年 6 月 22 日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_batch_rest_api
檔名:rwlp_batch_rest_api.html