批次 REST API

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

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

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

註: 會依 URL,在 URL 中將「批次」REST API 版本化。沒有版本號碼的 URL 會視為 API 第 1 版。批次 REST 介面的網址都是以根網址開頭:https://{host}:{port}/ibm/api/batch/{version}/
記住: 批次 REST 介面的網址都是以根網址開頭:https://{host}:{port}/ibm/api/batch

REST API 與只是提交者的使用者 ID

當透過 HTTPS 來呼叫 REST API 的使用者 ID 只獲授與 batchSubmitter 角色存取權時,會過濾 GET ("read") URL 傳回的結果。 提交者只會看到與提交者所提交的工作實例相關聯的實例和執行資料。 相反地,獲授與 batchAdminbatchMonitor 角色存取權的使用者 ID 可以檢視所有實例和執行資料 (由給定任何一組參數的任何給定的 URL 所傳回)。

只具備 batchSubmitter 角色存取權的使用者 ID 所看到的結果,會先按照給定 URL 的文件說明,依標準參數進行過濾。接著只傳回與提交者本身所提交之工作實例相關聯的實例和執行資料,進一步進行過濾。

如需相關資訊,請參閱維護 Liberty 批次環境安全

工作實例

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/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:傳回在三天前當天或以來所建立的工作實例。例如,createTime 大於或等於三天前算起的日期。
  • createTime=<3d:傳回在三天前當天或以前所建立的工作實例。例如,createTime 小於或等於到三天前為止的日期。
  • instanceState=[state],[state]:傳回處於所提供狀態的工作實例。有效的實例狀態是: SUBMITTED、JMS_QUEUED、JMS_CONSUMED、DISPATCHED、FAILED、STOPPED、COMPLETED 和 ABANDONED。
  • exitStatus=[string]:傳回符合結束狀態字串的工作實例。字串準則可在任一端使用萬用字元 (*) 運算子。
  • page=[頁碼]:指出要傳回的頁面(記錄子集)。預設值為 0。
  • pageSize=[每頁記錄數]:指出每頁記錄數。預設值為 50。
註: 涉及 createTime 之查詢中的伺服器預設時區角色

在您提交工作時,會將工作實例的 createTime 儲存在工作儲存庫中,並正規化為世界標準時間 (UTC)。當您利用 yyyy-MM-dd 來指定日期時 (例如 createTime=[yyyy-MM-dd]createTime=[yyyy-MM-dd]:[yyy-MM-dd]:),您必須將 yyyy-MM-dd 日期字串轉換成特定的 UTC 時間範圍,以便比對工作實例表格記錄中的 createTime 值。為了執行這項功能,應用程式會使用處理 REST 要求之伺服器的預設時區。這就是將日期字串轉換成所要比對的 UTC 時間範圍時,所使用的伺服器時區。

下表說明查詢參數 jobInstanceId=10:13 所傳回的資料。
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
*由於工作儲存庫以 UTC 格式儲存 createTime,請務必瞭解表格資料顯示的 createTime,採用特定伺服器(例如 "server1")的伺服器預設時區格式。如果從使用不同預設時區(有別於 "server1")的第二部伺服器的角度,來建構類似的表格,則表格會顯示不同的一組 CREATETIME 直欄值(對應的時區型差異)。這是處理 REST 要求之伺服器的預設時區,用來將 yyyy-MM-dd 日期字串參數,對映至下列範例中資料庫的 UTC createTime 值。
下列指令不論是針對哪一部伺服器發出,都會傳回相同的結果:
  • 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。
對於使用不同預設時區的伺服器,下列指令可能傳回不同的結果。在這些範例中,這些指令是針對 "server1"(用來移入先前表格的同一伺服器)發出,日期和時間是伺服器預設時區中的 11-11-2015:07:00:00。
  • createTime=>2d 會傳回 JOBINSTANCEID 12 和 13(2 天前當天或以來,亦即 11-09-2015)
  • createTime=<2d 會傳回 JOBINSTANCEID 10 和 11(2 天前當天或以前,亦即 11-09-2015)
  • 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
[16.0.0.4 以及更新版本]GET /ibm/api/batch/v3/jobinstances/
[16.0.0.4 以及更新版本]除了 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/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 的值是選用的。

除了使用 META-INF/batch-jobs 下批次應用程式內所包裝的 JSL 工作定義,您也可以將 JSL 放在 REST 提交工作要求的行內中一起傳遞。行內提交的 JSL 一律會置換批次應用程式所包裝的任何 JSL。您可以採用兩種方法,將 JSL 放在行內隨 HTTP 要求一起提交。
  1. 將 JSL 當成 JSON 有效負載包含在您的工作提交要求中。將 jobXML 內容新增至 JSON 物件,並將 JSL 檔的整個內容以 JSON 字串形式新增成內容值。
    註: 您必須適當跳出 XML 字串,JSON 剖析器才能剖析它。大部分 JSON 程式庫會為您執行這項功能。
    下列範例說明用來提交工作的要求內文,其中使用了單一組件 HTTP 要求,並透過 JSON 將 JSL 放在行內傳遞。
    {
      "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 物件。jobXMLName 為選用欄位,因為會將行內 JSL 中的工作 ID 資訊用於工作名稱。
  2. 使用 HTTP 多組件表單。當您使用 HTTP 多組件表單時,需要以 HTTP 內文的兩個個別組件形式,來提交 JSON 工作提交資料和 XML 工作定義。多組件表單中的 JSON 組件必須命名為 jobdata,表單中的 XML 組件必須命名為 jsl。使用多組件表單時,不需將 XML 配置成 JSON 字串。
    下列範例說明用來提交工作的 HTTP 要求,其中使用多組件 HTTP 要求,並藉由 jsl 訊息組件將 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--
        
    註: jobXMLName 為選用欄位,因為會將行內 JSL 中的工作 ID 資訊用於工作名稱。
下列範例回應說明順利提交工作:
{
    "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 會傳回錯誤。如果在刪除工作日誌時發生錯誤,不會嘗試將工作實例資料從工作儲存資料庫刪除。查詢參數包括:
  • purgeJobStoreOnly=true|false:當 purgeJobStoreOnly=true 時,不會嘗試清除此工作實例相關聯的工作日誌。預設值為 purgeJobStoreOnly=false。如果工作實例還有作用中的工作執行,此 API 會傳回錯誤。
    註: 當您使用單一清除 API 時,不會傳回任何清除回應訊息。
DELETE /ibm/api/batch/v2/jobinstances/
這個 URI 會清除下列清除過濾器參數所傳回之工作實例相關聯的所有資料庫項目和工作日誌。
註: 在執行 DELETE 介面來清除工作之前,建議您使用 GET 介面列出工作,並驗證這些是確實要清除的工作。
  • page=[頁碼]:指出要傳回的頁面(記錄子集)。預設值為 0
  • pageSize=[每頁記錄數]:指出每頁記錄數。預設值為 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:傳回在三天前當天或以來所建立的工作實例。例如,createTime 大於或等於三天前算起的日期。
  • createTime=<3d:傳回在三天前當天或以前所建立的工作實例。例如,createTime 小於或等於到三天前為止的日期。
  • instanceState=[state],[state]:清除處於所提供狀態的工作實例。有效的實例狀態是: SUBMITTED、JMS_QUEUED、JMS_CONSUMED、DISPATCHED、FAILED、STOPPED、COMPLETED 和 ABANDONED。
  • exitStatus=[string]:傳回符合結束狀態字串的工作實例。字串準則可在任一端使用萬用字元 (*) 運算子。
註: 依預設,除非指定 page 和 pageSize 參數,否則最多清除 50 筆記錄。
註: 涉及 createTime 之查詢中的伺服器預設時區角色

在您提交工作時,會將工作實例的 createTime 儲存在工作儲存庫中,並正規化為世界標準時間 (UTC)。當您透過 yyyy-MM-dd 來指定日期時 (例如 createTime=[yyyy-MM-dd]createTime=[yyyy-MM-dd]:[yyy-MM-dd]:),您必須將 yyyy-MM-dd 日期字串轉換成特定的 UTC 時間範圍,以便比對工作實例表格記錄中的 createTime 值。為了這樣做,應用程式會使用處理 REST 要求之伺服器的預設時區。這就是將日期字串轉換成所要比對的 UTC 時間範圍時,所使用的伺服器時區。

下表說明查詢參數 jobInstanceId=10:13 所傳回的資料。
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
*由於工作儲存庫以 UTC 格式儲存 createTime,請務必瞭解表格資料顯示的 createTime,採用特定伺服器(例如 "server1")的伺服器預設時區格式。如果從使用不同預設時區(有別於 "server1")的第二部伺服器的角度,來建構類似的表格,則表格會顯示不同的一組 CREATETIME 直欄值(對應的時區型差異)。這是處理 REST 要求之伺服器的預設時區,用來將 yyyy-MM-dd 日期字串參數,對映至下列範例中資料庫的 UTC createTime 值。
下列指令不論是針對哪一部伺服器發出,都會傳回相同的結果:
  • 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。
對於使用不同預設時區的伺服器,下列指令可能傳回不同的結果。在這些範例中,這些指令是針對 "server1"(用來移入先前表格的同一伺服器)發出,日期和時間是伺服器預設時區中的 11-11-2015:07:00:00。
  • createTime=>2d 會傳回 JOBINSTANCEID 12 和 13(2 天前當天或以來,亦即 11-09-2015)
  • createTime=<2d 會傳回 JOBINSTANCEID 10 和 11(2 天前當天或以前,亦即 11-09-2015)
  • 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 相關之指定工作執行相關的詳細資訊。 其中包括指向相關聯的步驟執行和工作日誌的鏈結。
註: 工作執行序號表示與指定的工作實例相關的第 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 會傳回 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
選用參數包括:
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 參數的 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 回覆碼

以下是 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 的清除要求才會生效。如果工作執行是在不同執行程式上執行,針對該實例的清除要求將會失敗。

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



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