在本系列的第2部分中,您通过使用SoapUI测试工具探索了IBM®Blueworks Live的代表性状态转移(REST)应用程序编程接口(API)。 现在,在第3部分中,您将学习如何通过API检索数据以及如何处理它以获得三种用例场景中描述的结果。 (请参阅第2部分中的文档下载,用户分析和带标记的工件列表的用例场景。本系列的第2-4部分使用相同的三个用例场景作为示例。)
URL客户端(cURL)是允许您发送REST请求的命令行程序。 它可以在开放的MIT许可下获得,并且可以移植到多个操作系统。 使用UNIX或Linux Shell,您可以以非常灵活和交互式的方式处理REST响应。 另外,您可以在可以随时运行的脚本中收集命令。
如果使用Cygwin,则可以在Windows上采用相同的方法。Cygwin是一组开源工具,提供了与Linux发行版相似的功能。 以下示例在Windows上与Cygwin一起运行,但是它们也可以在Linux或任何其他UNIX系统上的标准Shell上运行。 有关详细信息和下载信息,请参见https://cygwin.com 。
cURL不是Cygwin默认安装集的一部分,但可以作为可安装软件包使用。 因此,必须在初始安装过程中手动选择它,如图1所示,或在以后添加它。
图1.使用Cygwin设置工具安装cURL。
将cURL与Blueworks Live一起使用
首先,启动控制台或工作站,并检查是否可以调用curl
命令。 然后,您可以尝试第一个请求,如图2所示。
图2.在Windows的Cygwin控制台或工作站中使用cURL的示例
第一部分始终相同,指定用户名,密码和基地址。 键入以下命令: curl --basic --user user_name : password https://www.blueworkslive.com
代替/api/Auth
,您可以使用其他资源和参数,如以下示例所示。 以下示例在您键入curl --basic --user user_name : password https://www.blueworkslive.com
之后,仅显示命令的右侧部分。 例如, …/api/Auth
表示您必须输入curl --basic --user user_name : password https://www.blueworkslive.com /api/Auth
。
但是,当您开始使用其他资源时,原始地址将转发到托管您帐户的本地数据中心。 例如,阿姆斯特丹的本地数据中心是https://ams001.blueworkslive.com。
因此,您需要像在第2部分中一样从REST响应数据中提取特定地址。例如,键入: curl --basic --user westphal@de.ibm.com:XXX "https://www.blueworkslive.com/api/Auth?account=IBM70&version=20110917"
示例输出参见图3。
图3.用于确定服务端点的示例输出
您还可以告诉cURL为您从REST响应数据中提取特定地址,因此对于以后的所有调用,您都可以使用以下常量: curl --location-trusted --basic --user user_name : password https://www.blueworkslive.com
。
使用前面的参数,将使用GET方法发送请求(请参见第2部分中的REST资源概述表)。 如果您需要使用POST方法发送请求,则cURL需要以下额外参数:
curl --location-trusted --basic --user user_name : password -X POST –post302 https://www.blueworkslive.com
。
第一个信息检索示例
从第1部分中与SoapUI一起使用的示例开始,然后将响应数据存储在名为users.json
的本地文件中。 使用以下命令:
…/scr/api/UserList?account=IBM70 > users.json
您可以使用cat file_name
命令查看文件内容,例如:在这种情况下为cat users.json
。
现在您可以处理内容了。 处理内容的一种简单方法是使用shell命令。 您可以使用管道符号来钩住其他命令|
直接到上一个命令(而不是> users.json
文件输出)。 管道将一个命令的输出传递给下一个命令,以便每个命令仅必须执行简单的处理。 使用以下命令,删除JavaScript对象表示法(JSON)格式以提取文本值并为每个用户获得一行。 这些命令必须附加到您到目前为止使用的命令中。 使用向上箭头键获取先前的命令输入,并附加以下代码示例:
| sed 's/},{/\n/g' | sed 's/.*{//' | sed 's/}.*//g'
结果如下例所示:
"archived":false,"email":"user1@de.ibm.com","name":"Max","role":"Author","locked":false,"licensed":true,"date":"2014\/01\/21 06:05:26 -06:00","invited":false
"archived":false,"email":"user2@fi.ibm.com","name":"Moritz","role":"Author","locked":false,"licensed":true,"date":"2015\/02\/03 11:42:17 -06:00","invited":false
"archived":false,"email":"user3@de.ibm.com","name":"Fritz","role":"Author","locked":false,"licensed":true,"date":"2014\/07\/30 03:50:14 -05:00","invited":false
最后,删除字段的名称,例如"archived"
, "email"
, "name"
。 结果是一个逗号分隔的列表( .csv
文件),您可以在Excel中阅读并使用该列表。 使用以下命令:
| sed 's/"[^"]*"://g'
结果如下例所示:
false,"user1@de.ibm.com","Max","Author",false,true,"2014\/01\/21 06:05:26 -06:00",false
false," user2@fi.ibm.com","Moritz","Author",false,true,"2015\/02\/03 11:42:17 -06:00",false
false," user3@de.ibm.com","Fritz","Author",false,true,"2014\/07\/30 03:50:14 -05:00",false
如果尚未这样做,请将所有命令放在一起(一行),然后将结果存储在文件中,如下例所示:
cat users.json | sed 's/},{/\n/g' | sed 's/.*{//' | sed 's/}.*//g' | sed 's/"[^"]*"://g' > users.csv
现在,获取具有作者角色的所有用户的列表就像键入grep Author users.csv一样简单。
用例1示例:附加文档
对于第一个用例,您想从特定的Blueworks Live帐户获取所有附件文档,并将它们下载到本地文件系统。 然后,您只想获取自上次调用以来添加到Blueworks Live存储库中的文件。
与信息检索示例类似,首先将检索到的数据添加到输出文件中。 因为您需要多个参数,所以需要分开这些参数。 但是,在shell命令中, &
字符具有特殊含义,因此请使用前导\
作为转义字符来保护它。
或者,您可以用引号将整个URL括起来。 请参见以下示例:
…/scr/api/ListFiles?account=IBM70\&from=2015-03-01 > files.json
与信息检索示例一样,您可以从JSON输出中创建一个.csv
文件。 键入以下命令:
cat files.json | sed 's/},{/\n/g' | sed 's/.*{//' | sed 's/}.*//g' | sed
's/"[^"]*"://g' > files.csv
使用head files.csv
命令获得的输出的第一行应类似于以下示例:
8714,"30000d4ea8b6c7e","westphal@de.ibm.com","process","Company Guidelines.xlsx","30000d4ea8b6c39","2015-02-10T15:39:59.363-06:00"
287009,"30000d6ea8b36f8","westphal@de.ibm.com","process","Werkstatt.png","c83e8fdd25","2015-02-10T16:53:29.995-06:00"
18113,"30000d6ea8b4125","westphal@de.ibm.com","process","Antrag.png","c83e8fdd25","2015-02-10T16:55:02.481-06:00"
要从Blueworks Live帐户下载文件,您仅需要.csv
文件每一行中的以下两个数据字段:
- 第2栏–文件ID
- 第5列-文件名
这次,您需要两次处理具有特殊含义的字符。 awk
命令删除任何单个\
字符,因此您需要另一个\
作为转义字符以保护后面的&
字符。 因此,在以下示例中使用\\&
:
awk -F"," '{printf("curl --location-trusted --basic --user westphal@de.ibm.com:XXX
https://www.blueworkslive.com/scr/api/FileDownload?account=IBM70\\&fileItemId=%s > %s\n", $2, $5);}' files.csv > download_files.sh
您创建的脚本仅包含\&
。 稍后运行此脚本时,其行为类似于本教程系列到目前为止所使用的命令。
该脚本类似于以下示例:
curl --location-trusted --basic --user westphal@de.ibm.com:XXX
https://www.blueworkslive.com/scr/api/FileDownload?account=IBM70\&fileItemId="30000d4ea8b6c7e" > "Company Guidelines.xlsx"
curl --location-trusted --basic --user westphal@de.ibm.com:XXX https://www.blueworkslive.com/scr/api/FileDownload?account=IBM70\&fileItemId="30000d6ea8b36f8" > "Werkstatt.png"
curl --location-trusted --basic --user westphal@de.ibm.com:XXX https://www.blueworkslive.com/scr/api/FileDownload?account=IBM70\&fileItemId="30000d6ea8b4125" > "Antrag.png"
最后一步是运行脚本,如以下示例所示。
chmod u+x download_files.sh
./download_files.sh
下载的文档存储在本地文件夹中。
用例2示例:用户活动
在第二个用例中,您要确定用户在特定时间段内(如果有的话)上次登录的时间。
您首先需要获得一定时期的登录活动。 请注意,支持的请求期限最长为31天。 在更长的时间内,您需要多个请求调用。
与前面的示例一样,您清理输出并为每个条目创建一行。 字段编号4和6包含endTime
和user
(比较第2部分中的SoapUI示例)。 然后,您进行切换,以相反的顺序排序(以便最后一个登录日期在前),并删除多个用户条目。 通过一个命令提示符,您可以检索信息,如以下示例所示:
curl --location-trusted --basic --user westphal@de.ibm.com:XXX 'https://www.blueworkslive.com/scr/api/activity?account=IBM70&type=LOGINS&startDate=2015-02-02T00:00:00.000-00:00&endDate=2015-02-08T23:59:59.999-00:00' | sed 's/},{/\n/g' | sed 's/.*{//' | sed 's/}.*//g' | sed 's/"[^"]*"://g' | awk -F"," '{print $6,$4}' | sort -r | awk '{if ($1 != prev) print $0; prev = $1}'
输出应类似于以下示例:
"westphal@de.ibm.com" "2015-02-03T10:16:21.992-06:00"
"sebastian.schmidt@de.ibm.com" "2015-02-06T04:25:18.065-06:00"
…
用例3示例:标记的工件列表
在第三个用例中,您要生成一个报告,列出所有用特定关键字标记的工件,并包含诸如工件类型,名称和ID之类的详细信息。
原则上,您采用与上一个示例相同的方法:
- 索取信息。
- 每个项目创建一行。
- 如果需要,请进行进一步处理。
但是,搜索响应的结构更为复杂。 在上一个示例中,您使用简单的文本过滤器处理了JSON对象。 更复杂的对象需要“真实的” JSON解析,这意味着解析器必须了解方括号表示的对象的嵌套。 另外,可能需要对返回的对象进行更深入的分析。 有关更复杂的场景,请参阅本系列的第4 部分和第5部分 。
对于本第3部分教程,您将使用一个简单的单行命令来提取所有已标记的空格。
索取资料
运行以下命令:
curl --location-trusted --basic --user westphal@de.ibm.com:XXX https://www.blueworkslive.com/scr/api/Search?account=IBM70\&version=20120130\&searchFieldName=tag\&searchValue=demo\&returnFields=tag > search.json
查看以下示例结果以了解响应的结构:
{
"spaces": [
{
"tags": [{"id": "100003bea792c7f","name": "demo"}],
"id": "3ea6e050b",
"name": "Car Part Company"
},
{
"tags": [{"id": "100003bea792c7f","name": "demo"}],
"id": "30000d5ea8b30c7",
"name": "2.3.6 Warranty Management",
"parentSpaceId": "30000d4ea8be6c7",
"processes": [
{
"tags": [{"id": "100003bea792c7f","name": "demo"}],
"id": "c83e8fdd25",
"name": "Warranty Claim",
"milestones": [
{
"id": "c83e8fe11e",
"name": "Request Creation",
"activities": [
{
"id": "cc3e8f5cc3",
"name": "Fill Form"
},
{
"id": "cc3e8f5ca2",
"name": "Review Response"
},
…
该示例显示了JSON响应的第一部分,该部分经过格式化并有时会重新排序以提高可读性。 您会看到两个都标记为"demo"
空格。 第二个空间还包含一个被称为"Warranty Claim"
的过程。 可能有一些空间未标记,但包含标记的工件。 该结构会尽可能深入,并包含子元素,例如本示例中显示的过程详细信息。 还列出了带标记的空间的子空间。
每个项目创建一行
要在每个Blueworks Live空间中获得一行,请使用以下命令除去JSON对象的外部部分:
cat search.json | sed 's/^{\"spaces\":\[{//' | sed 's/}\]}$//'
用"tag\":\"demo\"
用标签(如果包含所需的标签)替换列表,如以下示例所示:
| sed 's/\"tags\":\[[^]]*demo[^]]*\]/\"tag\":\"demo\"/g'
对于三个级别,将用[ and ]
"…"
[ and ]
框住的所有其他列表替换为"…"
,如以下示例所示:
| sed 's/\[[^][]*\]/\"...\"/g' | sed 's/\[[^][]*\]/\"...\"/g' | sed 's/\[[^][]*\]/\"...\"/g'
最后,每当找到},{
时换行},{
并过滤掉所有包含demo
,如以下示例所示:
| sed 's/},{/\n/g' | grep demo
请参见以下示例结果:
"tag":"demo","id":"3ea6e050b","name":"Car Part Company"
"processes":"...","tag":"demo","id":"30000d5ea8b30c7","name":"2.3.6 Warranty Management","parentSpaceId":"30000d4ea8be6c7"
您获得了带有标记的两个空格的列表,并且可以看到还有更多标记的工件,包括第二个空间中的一个进程。 您可能会同意,第三个用例并不真正适合于外壳管道处理,除非您可以解决响应的嵌套结构。 该示例显示了此方法的局限性。
自2015年12月以来,有一个名为…/scr/api/LibraryArtifact
的新Blueworks Live REST API资源,使实现此任务变得更加容易。 但是,先前显示的解决第三个用例的尝试对于更复杂的处理仍然是一个很好的例子。 本系列的第4部分展示了一个更合适的实现。
结论
现在,您完成了Blueworks Live REST API系列的第三部分。 您知道如何进行REST API调用以使用cURL检索结果,以及如何使用Shell命令处理结果。
如果您想学习如何编写易于使用的Java™程序来对结果进行一些更复杂的处理,请继续第4部分 。
致谢
作者要感谢Blueworks Live管理团队的Margaret Thorpe对教程概念的帮助,以及开发团队的Daniel Treiber和技术销售团队的Sean Roe的审阅和评论。
翻译自: https://www.ibm.com/developerworks/bpm/library/techarticles/1603_westphal2-trs/1603_westphal2.html