
![[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。