在 IBM Business Process Manager V7.5 中使用 REST API

了解应用程序开发人员可用来在 IBM® Business Process Manager 中访问业务流程、人工任务和业务类别数据的 REST 资源。本文将介绍在 REST API 中公开的各种 Business Process Manager 组件、受支持的内容类型、方法覆盖的使用、响应数据格式,以及如何使用 REST API Tester 工具。

Nikhil Thaker, 顾问软件工程师, IBM

Nikhil Thaker 的照片Nikhil Thaker 是 IBM Software Group 的一名顾问软件工程师,还是 BPM REST APIs for IBM Business Process Manager V7.5 产品研发团队的一名成员。他从事中间件、Enterprise Application Integration 和业务流程管理解决方案的开发已有超过 10 年的时间了。作为一名顾问以及 EAI 和 BPM 的实验室倡导者,他与各种 IBM 客户合作过,曾涉足汽车、医疗保健、电信和公共事业等多个行业。



2011 年 12 月 05 日

概述

IBM Business Process Manager V7.5 提供了一组 API,可通过 Representational State Transfer (REST) 服务实现这些 API。一组业务流程定义 (BPD) 相关 REST 资源被提供用来访问业务流程、人工任务和业务类别数据。这些 REST API 允许开发人员构建用户接口或定制现有门户应用程序。这些 API 非常简单,可以从移动设备或 Rich Internet Applications (RIA) 调用它们。

本文介绍可用于访问业务流程、人工任务和业务类别数据的 IBM Business Process Manager REST API,并描述 REST API 中公开的各种 Business Process Manager 组件。您将了解以下内容:

  • REST URL 格式
  • 可用的 REST API
  • 支持的内容类型和方法覆盖的使用
  • 响应数据格式
  • REST API Tester

BPM 组件和数据模型

Business Process Manager REST API 使用各种 BPM 组件。图 1 展示了 REST API 实现的所有 Business Process Manager 组件及其关联数据模型。

图 1. REST API 实现的 BPM 组件和数据模型
REST API 实现的 BPM 组件和数据模型

应用程序开发人员可以在每种资源上使用几种 REST 方法,下一节将介绍这些方法。下面是一列 Business Process Manager 组件,在这些组件中,在 REST API 中公开了各种产品功能:

  • 业务流程定义
  • 流程实例
  • 任务
  • 外部活动和服务
  • 用户和小组
  • 已保存搜索和自定义搜索

执行 REST API

在深入了解 Business Process Manager REST API 规范支持那些 BPM REST API 之前,我们首先看看 REST API URL,然后尝试执行一个简单 REST API。

REST API URL

REST 资源 URL 拥有以下格式:br / http://{host}:{port}/{context-root}/v1/{resource}?{query}

其中:

{host}:{port} 是 REST API 端点的主机地址和端口,例如 MyProcessServer:9080。

{context-root} 是上下文根。本文中描述的所有 REST API 都拥有上下文根 /rest/bpm/wle

/v1 是 REST Resources 的当前版本。

{resource} 是一个资源标识符,比如 "process"、"task" 等。

{query} 包含可以传递到资源的查询参数。

使用 REST API Tester 执行一个 REST API

在本节中,您将使用 Business Process Manager 中提供的 REST API Tester 来执行一个简单 REST API,以便对 Business Process Manager REST API 中提供的功能有一个感性认识。您可以使用 Tester 工具调用本文中描述的所有 REST 调用。要访问这个工具,打开浏览器并转到以下 URL:

http://{host}:{port}/bpmrest-ui

其中 {host}:{port} 是 REST API 的主机地址和端口,例如 MyProcessServer:9080

现在我们执行一个简单 REST API 来获取用户详细信息。为此,执行以下步骤:

  1. 打开一个 Web 浏览器并转到以下 URL,使用正确的主机和端口信息替换:
    http://{host}:{port}/bpmrest-ui
  2. 在 REST API Tester 中,对 ResultType 字段选择 JSON (Javascript Format)
  3. Select API Call: 区域中,选择 Organization API,然后单击 User Details
  4. User Name 字段中输入 tw_admin
  5. 单击 Execute Call 按钮。您将看到,REST URL 请求被发送到服务器,一个响应显示在 Tester 的右侧面板上。
图 2. REST API Tester 执行 User Details REST API
REST API Tester 执行 User Details REST API

参见图 2 的大图

REST API Tester 拥有以下功能:

  • 充当定义为支持各种 Business Process Manager 功能的所有服务器端 REST 资源的客户端。
  • 拥有一个基于 Web 的用户界面,用户只需点击几次鼠标即可轻松访问 REST 资源。
  • 提供返回 JSON 和 XML 数据格式的能力。
  • 提供选择任何可用 API 和设置 API 上可用的任何选项的能力。
  • 提供执行 API 和以可读格式查看结果的能力。
  • 显示 URL(包括参数字符串)和结果。

Business Process Manager REST API 规范

本节列出了 Business Process Manager REST API 规范中定义的所有可用 REST API,如 图 1 所示。

BPD REST API

本节列出了为 BPD 公开的 REST API。

各部分的合法值如下:

"all"|"none"|"header"|"dataModel"|"data"|"diagram"

可以使用一个分隔符过滤数据模型的某个单独部分或者某个检索的部分列表。默认情况下,REST API 会检索数据模型的所有相关部分。

表 1. 所有 BPD 方法总结
协议方法REST API URL说明
GET/v1/processModel/{bpdId}[?snapshotId={string}][&processAppId={string}][&parts={string}]此方法检索一个 BPD 模型。
POST/v1/process?action={string}&bpdId={string}[&snapshotId={string}][&processAppId={string}]此方法启动一个 BPD。
POST/v1/process?action={string}&message={string}此方法向 Event Manager 发送一条消息以进行异步处理。
GET/v1/processApps此方法检索系统中安装的流程应用程序。

业务流程实例 REST API

本节列处了为业务流程实例公开的所有 REST API。

BPD 实例数据的操作查询参数的合法值如下:

"suspend", "terminate", "comment", "adhoc", "addDocument", "updateDocument", 
"sendMessage", "fireTimer", "delete", "deleteDocument", "trigger"

使用操作查询参数时,REST 资源会调用适当的操作处理程序。

表 2. 所有业务流程实例 REST API 总结
协议方法REST API URL说明
GET/v1/process/{instanceId} 此方法检索一个指定流程实例的细节。
PUT/v1/process/{instanceId}?action={string}此方法在流程实例上执行以下操作:挂起、恢复、终止。
PUT/v1/process/{instanceId}?action={string}&dueDate={string}此方法更新流程实例的到期时间。
PUT/v1/process/{instanceId}?action={string}&docId={string}[&data={string}][&docUrl={string}]此方法更新与流程实例关联的现有文档。
PUT/v1/process/{instanceId}?action={string}&step={string}此方法运行与流程实例关联的特殊事件。
PUT/v1/process/{instanceId}?action={string}&script={string}此方法执行一个 JavaScript 表达式并返回生成的流程实例细节。
DELETE/v1/process/{instanceId}?action={string}&docId={string}此方法删除与流程实例有关联的文档。
POST/v1/process/{instanceId}?action={string}&comment={string}此方法向流程实例添加注释。
POST/v1/process/{instanceId}?action={string}&timerId={string}此方法手动触发在线或附加定时器。
POST/v1/process/{instanceId}?action={string}&docType={string}&name={string}[&data={string}][&docUrl={string}]此方法向流程实例添加新文档。
POST/v1/process/{instanceId}?action={string}&docId={string}[&data={string}][&docUrl={string}]此方法更新与流程实例有关联的现有文档。
POST/v1/process/{instanceId}?action={string}&docId={string}此方法删除与流程实例有关联的文档。
GET/v1/processes/queries[?kind={string}][&content={string}]此方法检索某个流程实例数据列的查询。
GET/v1/processes/query/{queryName}/attributes此方法检索流程实例数据查询的一列属性。
GET/v1/processes/query/{queryName}[?selectedAttributes={string}][&queryFilter={string}][&sortAttributes={string}][&offset={integer}][&size={integer}]此方法通过查询检索某个流程实例实体列。
GET/v1/processes/query/{queryName}/count[?queryFilter={string}][&offset={integer}][&size={integer}]此方法检索查询中匹配指定标准的流程实例实体的数量。

任务 REST API

本节列出了为流程服务器上的任务公开的所有 REST API。

任务 REST API 的操作查询参数的合法值如下:

"start", "assign", "update", "finish", "claim", "claimnext",  "cancel" and "getnext"

使用操作查询参数时,REST 资源会调用适当的操作处理程序。

表 3. 所有 REST API 总结
协议方法REST API URL说明
GET/v1/taskTemplate/{templateId}此方法检索特定的人工任务模板。
GET/v1/taskTemplate/{templateId}/clientSettings/{type}此方法检索人工任务模板的客户端设置。
GET/v1/taskTemplates/queries[?kind={string}][&content={string}]此方法检索某个人工模板数据列的查询。
GET/v1/taskTemplates/query/{queryName}/attributes此方法检索任务模板数据查询的一列属性。
GET/v1/taskTemplates/query/{queryName}[?interactionFilter={string}][&selectedAttributes={string}][&sortAttributes={string}][&offset={integer}][&size={integer}]此方法通过查询检索某个任务模板实体列。
GET/v1/taskTemplates/query/{queryName}/count[?interactionFilter={string}][&offset={integer}][&size={integer}]此方法检索查询中匹配指定标准的人工模板实体的数量。
GET/v1/externalactivity/{externalActivityId}/model[?parts={string}]此方法检索外部活动的模型信息。
PUT/v1/task?action={string}此方法声明对多个任务实例的责任。
PUT/v1/task?action={string}此方法释放多个已声明的任务实例。
PUT/v1/task?action={string}&query={string}[&queryFilter={string}][&sortAttributes={string}]此方法声明基于过滤标准选择的下一个任务。如果存在已经声明的任务,则返回该任务。
GET/v1/task/actions?taskIDs={string}[&actions={string}]此方法检索人工任务的可用操作。
GET/v1/task/{taskId}[?parts={string}]此方法检索指定人工任务的细节。
PUT/v1/task/{taskId}?action={string}此方法启动任务。
PUT/v1/task/{taskId}?action={string}[&toMe={boolean}][&back={boolean}][&toUser={string}][&toGroup={string}][&parts={string}]此方法向用户和小组分配任务。
PUT/v1/task/{taskId}?action={string}[&dueDate={string}][&priority={string}][&parts={string}]此方法更新任务的到期日或优先权。
PUT/v1/task/{taskId}?action={string}[&parts={string}][params={string}]此方法结束或关闭任务。
PUT /v1/task/{taskId}?action={string}此方法声明、取消或执行任务上的另一个操作。
GET/v1/task/{taskId}/clientSettings/{type}此方法检索人工任务实例的客户端设置。这主要包含将用于调用与任务有关联的指导的 URL。
GET/v1/tasks/queries[?kind={string}][&content={string}]此方法检索某个任务实例数据列的查询。
GET/v1/tasks/query/{queryName}/attributes此方法检索指定查询的一列包含任务实例数据的属性。
GET/v1/tasks/query/{queryName}[?selectedAttributes={string}][&interactionFilter={string}][&queryFilter={string}][&sortAttributes={string}][&offset={integer}][&size={integer}]此方法通过查询检索一列任务实例实体。
GET/v1/tasks/query/{queryName}/count[?interactionFilter={string}][&queryFilter={string}][&offset={integer}][&size={integer}]此方法检索查询中匹配指定标准的任务实例实体的数量。

服务 REST API

本节列出了为流程服务器上的服务公开的所有 REST API。

服务 REST API 的操作查询参数的合法值如下:

"resume", "stop", "currentlyRunning", "getData", "setData", "js"

使用操作查询参数时,REST 资源将调用适当的操作处理程序。

表 4. 所有服务 REST API 的总结
协议方法REST API URL说明
GET/v1/serviceModel/{serviceId}[?parts={string}]此方法检索服务模型。
POST/v1/service/{instanceId}?action={string}[&createTask={boolean}][&parts={string}]此方法启动服务。instanceId 应该为服务模型 ID,或者为以下形式的字符串:<project-shortname>@<service-name>
GET /v1/service/{instanceId}此方法检索当前正在运行的服务列表。应该将该参数指定为字符串 currentlyRunning
GET/v1/service/{instanceId}?action={string}[&parts={string}]此方法检索与服务有关联的数据。参数应该指定为服务实例 ID。该值作为启动服务时的 ServiceRunModel 响应中的 key 元素返回。
PUT/v1/service/{instanceId}?action={string}此方法中止正在运行的服务。应该将这个参数指定为服务实例 ID。该值作为启动服务时的 ServiceRunModel 响应中的 key 元素返回。
PUT/v1/service/{instanceId}?action={string}[&parts={string}]此方法恢复停止的服务。应该将这个参数指定为启动服务时的 ServiceRunModel 响应中的 key 元素。
PUT/v1/service/{instanceId}?action={string}&script={string}此方法在正在运行的服务实例上下文中评估 javascript 代码段。应该将这个参数指定为服务实例 ID。该值作为启动服务时的 ServiceRunModel 响应中的 key 元素返回。
PUT/v1/service/{instanceId}?action={string}&field={string}&value={string}此方法设置正在运行的服务中的字段。应该将这个参数指定为服务实例 ID。该值作为启动服务时的 ServiceRunModel 响应中的 key 元素返回。

用户和小组 REST API

本节列出了为流程服务器上定义的用户和小组公开的所有 REST API。

表 5. 所有用户和小组 REST API 的总结
协议方法REST API URL说明
GET/v1/exposed此方法检索向终端用户公开的项目。将返回所有类型为 "process" (BPD)、"service""report""scoreboard" 的公开项目。
GET/v1/exposed/{type}此方法检索向终端用户公开的特定类型的项目。
GET/v1/users[?filter={string}][&parts={string}]此方法检索为了完成 Business Process Manager 安装而定义的用户的相关信息。
GET/v1/user/{userNameOrID}[?parts={string}]此方法检索为了完成 Business Process Manager 安装而定义的用户的相关信息。
PUT/v1/user/{userNameOrID}?action={string}&key={string}&value={string}此方法通过操作 ="setPreference" 更新与用户关联的用户偏好。
GET/v1/groups[?filter={string}][&parts={string}]此方法检索为了完成 Business Process Manager 安装而定义的小组的相关信息。
GET/v1/group/{groupNameOrID}[?parts={string}]此方法检索为了完成 Business Process Manager 安装而定义的小组的相关信息。
GET/v1/systems此方法检索关于一个或多个 Business Process Manager 安装(单个服务器或集群)的元数据。

已保存和自定义搜索 REST API

本节列出了为流程服务器中定义的已保存和自定义搜索公开的所有 REST API。

表 6. 所有搜索 REST API 的总结
协议方法REST API URL说明
GET/v1/search/meta/{type}此方法通过 type 路径参数检索请求类型的元数据。
PUT/v1/search/query[?columns={string}][&condition={string}][&sort={string}][&secondSort={string}][&organization={string}][&saveAsName={string}]此方法指定自定义搜索。
GET/v1/performance/query?filter={string}[&columns={string}][&condition={string}][&sort={string}][&secondSort={string}][&onlyRollup={string}][&rollupRule={string}]此方法针对性能服务器执行自定义搜索。注意,针对性能服务器执行的搜索只返回最近可用的业务数据值。要检索之前的业务数据值,请参见性能实例搜索资源。有关详细信息,请访问 Business Process Manager Information Center
GET/v1/performance/instance/{piid}此方法检索流程实例的历史信息。

移动支持的方法不可知论

所有以上下文根 /rest/bpm/wle 开始的 Business Process Manager REST API 都是 HTTP 方法不可知的,它们支持 HTTP GET 或 HTTP POST 方法。例如,支持 PUT 或 DELETE 的已记录 REST API 还拥有一个对等的 POST 方法支持。这样做是为了确保不支持 PUT HTTP 方法的移动设备或其他设备能够使用 HTTP POST 调用 REST 资源。

使用 HTTP 方法覆盖

出于安全考虑,有些防火墙不允许穿过防火墙使用 HTTP PUT 和 DELETE。要解决这个问题,可以使用 X-Method-OverrideX-HTTP-Method-Override HTTP 标头在 POST 请求中创建一条 PUT 或 DELETE 请求 “通道”。通常,X-Method-OverrideX-HTTP-Method-Override HTTP 标头会重写请求中使用的 HTTP 方法。

设置 X-Method-OverrideX-HTTP-Method-Override HTTP 标头的另一种方法是使用 x-method-overridex-http-method-override URL 查询参数,例如 "POST /rest/bpm/htm/v1/task?...&x-method-override=PUT"


Business Process Manager REST API 支持的数据格式

Business Process Manager REST API 支持三种数据格式:

  • JSON (JavaScript Object Notation)

    这是默认响应内容类型。要了解每种返回对象的详细格式,请参阅每种操作的 JSON 架构规范。有关详细信息,请访问 Business Process Manager Information Center

  • XML (eXtensible Markup Language)

    基于 XML 的数据的格式由产品的 <install-root>/properties/schemas/bpmrest/v1 目录中提供的 XML 架构来指定。每种操作的文档中都提供了这些架构的摘要。

    响应验证技巧

    Business Process Manager REST 资源使用 JAXB 数据绑定技术对 XML 进行编组和解组。因此,您可以选择针对提供的架构定义验证 REST XML 响应。

  • JSONP (JSON with Padding)

    这种格式可以用作 JSON 的替补。在这种情况下,每个返回的 JSON 响应都被包装到一个 JavaScript 回调函数调用中。要使用这个特性,则必须指定回调 URI 查询参数。

切换数据格式

可以使用两种方法来切换默认数据格式:

  • 客户端可以通过使用 Accept HTTP 标头指定响应的请求介质类型。例如:"Accept: application/json"

  • 或者,客户端可以使用 accept URI 查询参数。例如: "GET /rest/bpm/htm/v1/task/...?accept=application/json"

如果同时指定 HTTP 标头和 URI 查询参数,则优先处理查询参数。如果服务器不能使用请求的介质类型进行响应,则返回 HTTP 状态码 "406 Not Acceptable" 。

JSONP 响应:

启用 JSONP 技巧

由于安全原因,JSONP 支持使用默认禁用。要启用 JSONP 支持,则必须在服务器的 100Custom.xml 文件中设置以下属性:
<jsonp-enabled>true</jsonp-enabled>

要请求以 JSONP 格式返回相应的数据,则必须使用 Accept HTTP 标头或 Accept URI 查询参数指定响应介质类型 application/x-javascript,还必须使用回调 URI 查询参数指定 JavaScript 函数名。例如,GET /rest/bpm/wle/v1/task/...?accept=application/x-javascript&callback=mycallback

响应数据模型

Business Process Manager REST API 拥有一个良好定义的响应数据模型。响应数据总是有一个状态和数据字段。该状态是一个 HTTP 状态码,数据字段包含响应数据或错误信息。下面的清单展示了一个样例 JSON 响应。

清单 1. 响应数据模型样例
{ status:, data:}
清单 2. currentUser REST API 的 JSON 格式的响应
{
   "status":"200",
   "data":{
	 "userID":1,
	 "userName":"tw_admin
   }
}
清单 3. currentUser REST API 的 XML 格式的响应
<bpm:ResponseData xmlns:bpm="http://rest.bpm.ibm.com/v1/data">
   <status>200</status>
   <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xmlns:ug="http://rest.bpm.ibm.com/v1/data/usergroup" 
            xsi:type="ug:User">
      <userID>1</userID>
   </data>
</bpm:ResponseData>

错误响应

Business Process Manager REST API 有一个良好定义的错误响应数据模型。错误响应数据将总是包含一个状态和额外数据。状态指出错误,数据包含关于异常类型、错误编号、错误消息和程序员细节的信息。下面的清单展示了 JSON 和 XML 错误响应示例。

清单 4. JSON 格式的错误响应
{
   "status":"error",
   "Data":{
    "status":"error",
	"exceptionType":"com.ibm.bpm.wle.api.NoSuchUserException",
	"errorNumber":"CWTBG0007E",
	"errorMessage":"CWTBG0007E: User 'currentUser' not found.",
	"errorMessageParameters":["currentUser"]
	}
}

由于安全原因,错误响应默认情况下会省略服务器端异常细节。要包含服务器端异常细节,则必须在服务器的 100Custom.xml 文件中设置以下属性:
<server-stacktrace-enabled>true</server-stacktrace-enabled>

清单 5. XML 格式的错误响应
<ex:RestRuntimeException 
       xmlns:ex="http://rest.bpm.ibm.com/v1/data/exception">
   <status>error</status>
   <Data>
      <status>error</status>
	  <exceptionType>com.ibm.bpm.wle.api.NoSuchUserException</exceptionType>
	  <errorNumber>CWTBG0007E</errorNumber>
	  <errorMessage>CWTBG0007E: User 'currentUser' not found.</errorMessage>
	  <errorMessageParameters>currentUser</errorMessageParameters>
   </Data>
</ex:RestRuntimeException>

结束语

IBM Business Process Manager REST API 支持用户构建自定义用户接口,或者为现有公司门户添加 BPM 功能,无需采用黑客技术或不受支持的调用。这些 API 非常简单,适用于 Rich Internet Applications (RIA) 或移动设备。REST API 提供了一个 REST API Tester,可以使用它在应用程序开发过程中验证结果。


致谢

本文作者衷心感谢 Steven Gonchar 对 REST API Tester 的代码贡献,Gregory Harley 对 IBM Business Process Manager REST 规范的汇总和对本文的贡献,以及 Phil Adams 和 Richard Scheuerle 对本文的审阅!

参考资料

学习

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=WebSphere
ArticleID=778853
ArticleTitle=在 IBM Business Process Manager V7.5 中使用 REST API
publish-date=12052011