本系列的第1部分介绍了5个一般用例,它们是使用IBM®Blueworks Live的代表性状态转移(REST)应用程序编程接口(API)的最佳方法。 您还为每种用例学习了不同的实现方法。 从本系列开始,本系列的下一部分将深入探讨这些方法并讨论实现细节。
本系列的第2-4部分使用相同的三个用例场景作为示例,在第2部分中对此进行了介绍。如果您仅对Java实现感兴趣,则可以阅读关于REST API和用例的以下两部分。场景,但是您可以直接跳至第4部分 。
Blueworks Live REST API
Blueworks Live API提供对可用Blueworks Live功能的有限子集的访问。 所有访问都需要有效的用户名和密码,并受正常Blueworks Live角色和权限的限制。
登录到Blueworks Live之后,您可以访问以下有关REST API的在线文档:IBM知识中心上发布的Blueworks Live REST API文档。
表1显示了截至2016年的所有可用REST资源,其方法以及对该资源的说明。
表1. REST资源概述
资源资源 | 方法 | 描述 |
---|---|---|
/ scr / api / activity | 得到 | 检索帐户活动详细信息。 |
/ scr / api / ActivityDocumentation | 得到 | 检索活动的文档。 |
/ scr / api / AppDetail | 得到 | 检索ID的应用定义的详细信息。 |
/ scr / api / AppList | 得到 | 获取用户有权启动的应用程序列表。 |
/ api / Auth | 得到 | 检查用户身份验证并返回帐户信息 |
/ scr / api /头像 | 得到 | 下载用户头像。 |
/ scr / api / BpmnExport | 得到 | 将流程图导出为BPMN 2.0格式。 |
/ scr / api / ExcelExport | 得到 | 将空间,过程或决策导出到excel文件。 |
/ scr / api / export / process | 得到 | 以BPMN 2.0格式导出流程的特定修订版。 |
/ scr / api / FileDownload | 得到 | 下载附件文件。 |
/ scr / api / FileUpload | 开机自检 | 添加文件附件以处理活动或工作项。 |
/ scr / api / FollowedProcesses | 得到 | 获取有关用户标记为遵循的过程的信息 |
/ scr / api / LaunchInstance | 开机自检 | 从应用程序定义启动新实例。 |
/ scr / api / LibraryArtifact | 得到 | 自2015年12月以来的新功能: 检索库工件详细信息。 |
/ scr / api / ListFiles | 得到 | 检索附件文件列表。 |
/ scr / api / ManageGroup | 得到, 放入,删除 | 管理群组。 |
/ scr / api / NewsFeed | 得到 | 按日期时间顺序从最新到最旧检索消息。 |
/ scr / api / PostComment | 开机自检 | 向活动添加评论或作为对现有评论的回复。 |
/ scr / api / PrintDiagram | 得到 | 下载该图的PDF视图。 |
/ scr / api / ProcessData | 得到 | 获取过程数据作为项目图。 |
/ scr / api / provision / user | 得到, 放入,删除 | 将用户设置为一个帐户。 |
/ scr / api / revision | 得到, 开机自检 | 查询或创建流程/政策/决策修订 |
/ scr / api /搜索 | 开机自检 | 在帐户中搜索指定的属性。 |
/ scr / api / TaskList | 得到 | 检索分配给当前用户或由当前用户完成的任务的列表。 |
/ scr / api / TaskListCount | 得到 | 获取分配给当前用户或由当前用户完成的任务总数。 |
/ scr / api / UpdateFavorites | 开机自检 | 更新用户的收藏夹应用列表。 |
/ scr / api / UserList | 得到 | 检索经过身份验证的用户帐户中的用户列表。 |
/ scr / api / UserListForWork | 得到 | 检索可以分配任务的用户列表。 |
/ scr / api / WorkAction | 开机自检 | 为一项工作执行一些动作,例如完成一项任务。 |
/ scr / api / WorkComment | 开机自检 | 向工作项添加评论。 |
/ scr / api / WorkDetail | 得到 | 返回工作实例的详细信息以获取ID。 |
/ scr / api / WorkList | 得到 | 检索当前用户启动的打开或完成的工作实例的列表。 |
用例场景
考虑本教程系列中的三个典型用例。 考虑用例的优势在于,您既可以学习Blueworks Live REST API的理论,又可以学习如何使用该技术,检索信息或数据以及以适当的方式存储和呈现信息或数据。
前两个用例是Blueworks Live客户的真实要求:
- 用例1:从特定的Blueworks Live帐户获取所有附件文档,并将它们下载到本地文件系统。 接下来,您只想获取自上次调用以来添加到Blueworks Live存储库中的文件。
- 用例2:要了解用户更新流程模型,编写注释,附加文档和其他活动的强度,您需要一个报告,其中列出了所有用户以及对存储库的最后提交日期。 例如,您需要一份有关哪些用户仍处于活动状态并且正在进行流程优化的报告。 Blueworks Live中有许多内置的报告,它们按日期,用户,空间和每个空间内的统计信息显示最近的更改,但是尚没有活动的用户并正在进行流程优化的报告。
尽管这些用例是特殊情况,但它们是显示REST接口功能的很好的例子。 第一个用例具有技术目的,即备份文档(这就是为什么它与本系列第1部分中介绍的一般用例无关)的原因。 第二个用例属于用户管理和仪表板类别。 在本教程中考虑的简单形式中,用例仅具有报告方面,但是您也可以将其扩展为管理用户。 仪表板类别中更典型的示例是有关流程模型内容和文档的特殊报告,例如以下用例:
- 用例3:生成一个报告,列出所有用特定关键字标记的工件(例如
core
,并包含诸如工件类型,名称和ID之类的详细信息。
快速浏览可用的REST资源会告诉您,需要以下API来实现用例:
- 对于用例1:
/scr/api/ListFiles
和/scr/api/FileDownload
- 对于用例2:
/scr/api/UserList
和/scr/api/activity
- 对于用例3:
/scr/api/Search
通用REST测试工具
有各种各样的REST测试工具可用,有些是免费提供的。 如果要使用允许您定义测试项目的桌面程序,请考虑SoapUI。 现在可以使用可在浏览器中运行的工具:Postman可用于Google Chrome,而RESTClient是类似的工具,可作为Firefox的附件使用。
从以下网站获取REST测试工具:
- SoapUI: http : //www.soapui.org 。 详细信息和下载。
- 邮递员: https : //www.getpostman.com 。 请参阅网站上的说明,以将Postman安装为Google Chrome应用。
- RESTClient: https ://addons.mozilla.org/zh-CN/firefox/addon/restclient。 通过单击添加到Firefox安装此Firefox附加组件。 重新启动后,从“工具”菜单调用RESTClient。
本教程使用SoapUI作为REST测试工具,但是您需要在其他工具中执行的步骤非常相似。 使用替代工具不会遇到困难。
SoapUI
为了熟悉Blueworks Live API并更好地理解调用和响应,本教程展示了如何使用SoapUI进行探索。 在本系列的第3部分中,您将学习使用程序逻辑来处理响应。
SoapUI是用于测试基于SOAP和REST的Web服务的工具。 基本版本可在GNU通用公共许可下作为免费软件获得。 有关更多信息和下载该工具,请参见http://www.soapui.org 。 本教程使用版本5.1.2。
创建SoapUI项目
在启动SoapUI之前,必须更改默认的安全协议。 从2017年7月开始,Blueworks Live仅支持TLS版本1.2和更高版本,以提高安全性。 .vmoptions
添加到SoapUI的bin
目录中具有扩展名.vmoptions
的文件中:
-Dsoapui.https.protocols=SSLv3,TLSv1.2
- 启动SoapUI后,您将看到一个空的工作区。 通过右键单击Projects并选择New REST Project来创建一个REST项目。
- 对于URI,输入
https://www.blueworkslive.com
,如图1所示。
图1. New REST Project窗口
第一个SoapUI请求
空请求被创建并在中心的SoapUI窗口中打开,如图2所示。
图2.第一个请求示例
- 右键单击项目名称,然后选择Renam e 。 给您的项目起一个适当的名称,例如
Blueworks Live
。 - 输入请求的资源。 首先从
/api/Auth
,然后单击绿色箭头发送请求,如图3所示。图3.输入资源并发送请求
- 您收到来自服务器的响应。 选择格式选项卡之一,例如HTML选项卡,以查看内容。 如图5所示,您看到一条消息,要求授权。
图4. Response HTML选项卡
- 在窗口底部选择Auth的设置,然后添加一个授权,如图5所示。
图5.添加授权
- 选择“ 基本”作为授权类型,然后输入用户名和密码。 另外,选择抢先验证 ,如图6所示。
图6.配置授权
- 单击绿色箭头并选择JSON作为输出格式,再次发送请求。 使用正确的用户凭证,您会收到包含所有Blueworks Live帐户的列表。 有关示例,请参见图7。
图7.重新提交的请求结果
- 向请求添加参数。 您可以使用+图标,如图8所示,也可以单击Parameters 。
图8.添加一个参数
- 快速浏览API文档显示
20091212
被用作API版本的默认值。 添加一个名为version
的参数,其值为20110917
,然后再次发送该请求,如图9所示。图9.设置参数值
在绿色箭头旁边,您可以看到如何使用扩展名
?version=20110917
构建请求。 图10显示了新结果,除了名称之外,还包括每个帐户的ID。图10.使用不同版本的请求结果。
创建更多请求的提示
现在,您在勘探项目中调用其他资源,并使用具有各种参数的多个请求。 右键单击并选择重命名,为请求指定一个有意义的名称。 输入与项目一样的新名称。 参见图11。
图11.请求的有意义名称的示例
您可以通过右键单击Blueworks Live的URI并选择New Resource来创建其他资源。
然后,您可以通过右键单击资源并选择New Method来创建其他方法(除GET之外)。
您可以通过右键单击该方法并选择New Request来为该方法创建其他请求。
重要提示:不要忘记为每个请求设置授权,如图12所示。
图12.为每个请求配置授权
为了简化过程,您可以克隆现有请求并更改方法或参数。
某些请求需要必填参数,例如帐户名。 如果不提供参数,则会收到401 Unauthorized
响应,如图13所示。
图13.未经授权的请求的结果
尽管account
参数在文档中被描述为可选参数,但是请理解,如果没有设置,则需要一个替代方法。 考虑在会话中使用accountId
参数或cookie。 如果您只有一个Blueworks Live帐户,则在不提供该帐户的情况下,也可以进行呼叫。 但是,为了安全起见,应始终提供account
参数和version
属性(如果有)。
如果您尝试使用由于打字错误而不存在的资源,则会收到404 Not Found
响应,如图14所示。
图14.未知示例资源的结果
请注意,除/api/Auth
以外的所有请求都必须转发到托管您特定帐户数据的最终服务提供商。 例如,您可能要访问在阿姆斯特丹托管的一个Blueworks Live帐户,并且可能要访问在奥斯丁托管的另一个Blueworks Live帐户。 到目前为止,您只提供了一个全局Blueworks Live URL。 出于安全原因,大多数REST客户端不会自动转发通过POST方法发送的数据。 而是使用该帐户的正确服务提供商地址。 当您为https://www.blueworkslive.com
端点提供/api/Auth
帐户并提供您要使用的帐户时,可以在Auth
调用的响应中找到此数据。 您会收到服务提供商的地址。 对于连续的呼叫,请使用服务提供商作为端点。
图15显示了一个名为ibm.blueworkslive.com
的专用IBM服务器的ibm.blueworkslive.com
。 图16中的示例使用服务器作为新端点。
图15.确定服务端点。
图16.使用实际的服务端点作为请求
默认情况下,SoapUI自动转发GET请求。 请参见图17。因此,对于这些类型的请求,您还可以保留https://www.blueworkslive.com
作为端点。 本系列的第2部分和第3部分将进一步讨论该主题。
图17. SoapUI自动进行GET请求转发
用例示例
现在,您确定实现上述三个用例场景所需的REST资源。 这些示例简要调查了服务调用并提供了一些示例结果。 这些示例是为第3 部分和第4 部分中的方案实现有用工具的良好起点。
用例1:附加文档
要备份附加到Blueworks Live帐户的所有文档,您首先需要这些文件的列表,然后需要一种下载每个文件的方法。
- 使用/ scr / api / ListFiles API资源:图18中所示的示例调用从
IBM70
帐户请求具有创建日期为IBM70
月1日的文件列表。 在此示例中,它只是一个文件。 请注意,此请求需要帐户的管理权限。图18.请求文件列表
- 使用/ scr / api / FileDownload API资源:
使用上一个示例的返回值来获取相应的文件。 但是,SoapUI以原始格式显示内容,如图19所示。
图19.使用SoapUI请求pdf文件的示例
用例2:用户活动
对于用户活动报告用例,您首先需要一个用户列表,然后需要有关每个用户的登录时间或活动的一些详细信息。
- 使用/ scr / api / UserList API资源:
接收用户列表。 有关示例,请参见图20。 屏幕截图中的以下某些内容在本教程中被故意截断,因此您可以看到返回的属性,但看不到原始客户示例中的全名和用户数据。
图20.用户列表请求的结果
- 使用/ scr / api / activity API资源:
该API资源提供了多种可能性。 某些类型是分层结构的,您可以在下面的列表中看到:LOGINS ITEMS_VIEWED PROCESSES_VIEWED POLICIES_VIEWED DECISIONS_VIEWED SPACES_VIEWED COMMENTS PROCESS_COMMENTS DECISION_COMMENTS USERS_JOINED ITEMS_CHANGED PROCESSES_CHANGED POLICIES_CHANGED DECISIONS_CHANGED SPACES_CHANGED ACCOUNT_CHANGED SNAPSHOTS PROCESS_SNAPSHOTS POLICY_SNAPSHOTS DECISION_SNAPSHOTS
如果要尝试此用例,请先查找大约一周的示例登录数据。 否则,您可能会收到很多返回的数据。 图21显示了具有给定开始日期和结束日期的示例请求。
图21.请求登录信息的示例
图22显示了另一个带有活动注释的示例。 请注意,服务结果包含键值对以及一些文本和message
键。 文本不是注释本身(由用户输入),而是生成的消息,描述用户输入了注释并描述了包含注释的工件。
图22.注释请求示例
用例3:使用特定标签搜索工件
在最后一个用例中,您可以在Blueworks Live中找到用特定标签标记的模型工件。
- 使用/ scr / api / Search API资源:
在Blueworks Live帐户中搜索元素当然是最重要的功能之一。 为此,您必须首先定义要搜索的内容(键入和匹配),然后定义要检索的结果类型。 为与启动过程在图23的搜索的例子Garant
并请求cost
和work_time
属性,在除了核心信息(空间,过程,活动)。图23.搜索请求的示例。
要检索带有特定标签的所有工件,请使用tag
作为搜索字段名称,并提供您要搜索的值。 另外,您可能希望请求返回关联的标签,如图24所示。
图24.对特定标签的搜索请求示例
结论
您已经完成了Blueworks Live REST API系列的第2部分。 您了解了在哪里可以找到有关Blueworks Live REST API的服务资源的信息,以及如何使用SoapUI等测试工具对服务请求进行身份验证和发送信息。 第1部分还确定了实现三个建议的示例用例所需的所有特定REST API资源。
在第3部分和第4部分中 ,您将学习如何处理REST API调用的结果。 您将学习如何调用REST API并将结果与shell命令和脚本(在第3部分中)以及在Java应用程序(在第4部分中)一起使用,以扩展Blueworks Live的内置功能。
致谢
作者要感谢Blueworks Live管理团队的Margaret Thorpe对教程概念的帮助,以及开发团队的Daniel Treiber和技术销售团队的Sean Roe的审阅和评论。
翻译自: https://www.ibm.com/developerworks/bpm/library/techarticles/1602_westphal1-trs/1602_westphal1.html