本系列的第1部分介绍了5个一般用例，它们是使用IBM®Blueworks Live的代表性状态转移（REST）应用程序编程接口（API）的最佳方法。 您还为每种用例学习了不同的实现方法。 从本系列开始，本系列的下一部分将深入探讨这些方法并讨论实现细节。
本系列的第2-4部分使用相同的三个用例场景作为示例，在第2部分中对此进行了介绍。如果您仅对Java实现感兴趣，则可以阅读关于REST API和用例的以下两部分。场景，但是您可以直接跳至第4部分 。
Blueworks Live API提供对可用Blueworks Live功能的有限子集的访问。 所有访问都需要有效的用户名和密码，并受正常Blueworks Live角色和权限的限制。
登录到Blueworks Live之后，您可以访问以下有关REST API的在线文档：IBM知识中心上发布的Blueworks Live REST API文档。
表1显示了截至2016年的所有可用REST资源，其方法以及对该资源的说明。
考虑本教程系列中的三个典型用例。 考虑用例的优势在于，您既可以学习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测试工具可用，有些是免费提供的。 如果要使用允许您定义测试项目的桌面程序，请考虑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测试工具，但是您需要在其他工具中执行的步骤非常相似。 使用替代工具不会遇到困难。
为了熟悉Blueworks Live API并更好地理解调用和响应，本教程展示了如何使用SoapUI进行探索。 在本系列的第3部分中，您将学习使用程序逻辑来处理响应。
SoapUI是用于测试基于SOAP和REST的Web服务的工具。 基本版本可在GNU通用公共许可下作为免费软件获得。 有关更多信息和下载该工具，请参见http://www.soapui.org 。 本教程使用版本5.1.2。
在启动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所示。空请求被创建并在中心的SoapUI窗口中打开，如图2所示。
在绿色箭头旁边，您可以看到如何使用扩展名?version=20110917构建请求。 图10显示了新结果，除了名称之外，还包括每个帐户的ID。
现在，您在勘探项目中调用其他资源，并使用具有各种参数的多个请求。 右键单击并选择重命名，为请求指定一个有意义的名称。 输入与项目一样的新名称。 参见图11。
您可以通过右键单击Blueworks Live的URI并选择New Resource来创建其他资源。
然后，您可以通过右键单击资源并选择New Method来创建其他方法（除GET之外）。
您可以通过右键单击该方法并选择New Request来为该方法创建其他请求。
重要提示：不要忘记为每个请求设置授权，如图12所示。
为了简化过程，您可以克隆现有请求并更改方法或参数。
某些请求需要必填参数，例如帐户名。 如果不提供参数，则会收到401 Unauthorized响应，如图13所示。
尽管account参数在文档中被描述为可选参数，但是请理解，如果没有设置，则需要一个替代方法。 考虑在会话中使用accountId参数或cookie。 如果您只有一个Blueworks Live帐户，则在不提供该帐户的情况下，也可以进行呼叫。 但是，为了安全起见，应始终提供account参数和version属性（如果有）。
如果您尝试使用由于打字错误而不存在的资源，则会收到404 Not Found响应，如图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中的示例使用服务器作为新端点。
默认情况下，SoapUI自动转发GET请求。 请参见图17。因此，对于这些类型的请求，您还可以保留https://www.blueworkslive.com作为端点。 本系列的第2部分和第3部分将进一步讨论该主题。
现在，您确定实现上述三个用例场景所需的REST资源。 这些示例简要调查了服务调用并提供了一些示例结果。 这些示例是为第3 部分和第4 部分中的方案实现有用工具的良好起点。
要备份附加到Blueworks Live帐户的所有文档，您首先需要这些文件的列表，然后需要一种下载每个文件的方法。
使用/ scr / api / ListFiles API资源：图18中所示的示例调用从IBM70帐户请求具有创建日期为IBM70月1日的文件列表。 在此示例中，它只是一个文件。 请注意，此请求需要帐户的管理权限。使用上一个示例的返回值来获取相应的文件。 但是，SoapUI以原始格式显示内容，如图19所示。
对于用户活动报告用例，您首先需要一个用户列表，然后需要有关每个用户的登录时间或活动的一些详细信息。
使用/ scr / api / UserList API资源：接收用户列表。 有关示例，请参见图20。 屏幕截图中的以下某些内容在本教程中被故意截断，因此您可以看到返回的属性，但看不到原始客户示例中的全名和用户数据。
如果要尝试此用例，请先查找大约一周的示例登录数据。 否则，您可能会收到很多返回的数据。 图21显示了具有给定开始日期和结束日期的示例请求。
图22显示了另一个带有活动注释的示例。 请注意，服务结果包含键值对以及一些文本和message键。 文本不是注释本身（由用户输入），而是生成的消息，描述用户输入了注释并描述了包含注释的工件。
在最后一个用例中，您可以在Blueworks Live中找到用特定标签标记的模型工件。
使用/ scr / api / Search API资源： 在Blueworks Live帐户中搜索元素当然是最重要的功能之一。 为此，您必须首先定义要搜索的内容（键入和匹配），然后定义要检索的结果类型。 为与启动过程在图23的搜索的例子Garant并请求cost和work_time属性，在除了核心信息（空间，过程，活动）。要检索带有特定标签的所有工件，请使用tag作为搜索字段名称，并提供您要搜索的值。 另外，您可能希望请求返回关联的标签，如图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
相关资源：live http headers0.17.1