REST Web Services 软件包

使用 REST Web Services 软件包 中的 操作 作为向 API 发送请求和从 API 接收响应的方法（例如 DELETE、GET、PATCH、POST 或 PUT）。

设置

以下设置适用于 REST Web Services 操作。 配置适当的设置以发送 REST 请求并接收响应。 每种方法都需要特定的参数。

注： 当您在 MacOS 平台上创建自动化并使用 操作（例如 DELETE、GET、PATCH、POST 或 PUT）时，不支持以下身份验证模式：
  • NTLM 身份验证（AD 用户）
  • 已登录的 AD 用户
URI
输入 API 资源的 URI。 选择以下选项之一并相应地配置设置：
  • 输入 URI： 直接输入 URI 或选择保存为字符串变量的 URI。
  • 选择凭据作为 URI： 使用此选项可选择在 Credential Vault 中作为凭据保存的 URI。 使用凭据 > 选择直接选择凭据。 还可以使用变量选项来选择映射到凭据变量的凭据。 此选项允许您隐藏包含敏感信息的 URI，例如授权代码或 API 密钥。
Proxy configuration
配置 REST Web Services 操作的代理设置。 选择以下选项之一并相应地配置设置：
  • 系统： 选择此选项可使 Bot Agent 使用系统代理。 系统代理是您在运行自动化的 机器人 运行程序计算机上配置的代理。
  • 自定义： 选择此选项以配置自动化的自定义代理设置。 配置以下设置：
    • 主机： 代理服务器的主机名或 IP 地址。
    • 端口： 代理服务器的端口号。
    • 用户名（可选）： 用于对代理服务器进行身份验证的用户名。
    • 密码（可选）： 用于对代理服务器进行身份验证的密码。
    注： 必须为任何需要身份验证的代理服务器配置用户名和密码。
    可以使用凭据、变量或不安全字符串选项之一来配置代理设置。
    • 凭据： 选择 Credential Vault 中可用的值。
    • 变量： 选择映射到值的凭据变量。
    • 不安全字符串： 手动输入值或选择映射到预定义字符串变量的值。
身份验证模式
配置 REST Web Services 操作的身份验证设置。 选择以下选项之一并相应地配置设置：
  • 无身份验证： 选择此选项以访问不需要身份验证即可访问其服务器的端点。
  • Control Room 用户令牌： 选择此选项以使用您登录 Control Room 时生成的令牌。
  • 基本： 选择此选项以输入用户名和密码，对 REST Web Services API 调用进行身份验证。 此选项会向 API 调用添加一个名称为 Authorization 的标头，其中包含用户名和密码的 base64 编码字符串表示。
  • 已登录 AD 用户： 选择此选项以选择基于 Active Directory (AD) 的身份验证。 使用 AD 对被授权访问相关 API 的 AD 用户进行身份验证。 请求中不需要凭据。
  • Windows NT LAN Manager (NTLM) 验证（AD 用户）： 选择此选项以选择质询-响应 NTLM 身份验证。 配置以下设置：
    • 域： 输入必须对 API 调用进行身份验证的域。 还可以选择一个已映射到域或主机的字符串变量。
    • 用户名（可选）： 用于对 API 调用进行身份验证的用户名。
    • 密码（可选）： 用于对 API 调用进行身份验证的密码。
    可以使用凭据、变量或不安全字符串选项之一来配置用户名和密码。 我们建议您使用凭据选项从 Credential Vault 选择一个凭据，或者使用凭据变量。
  • 托管的 OAuth2 - Control Room： 选择此选项以选择 Control Room 托管的 OAuth 连接作为身份验证选项。 有关更多详情，请参阅 Control Room 中的配置 OAuth 连接。

    以下视频展示了如何在 REST Web Services 中使用 OAuth 连接：

标题
在 API 请求中添加自定义标头以包含附加元数据。 并非所有方法都需要标题。 可以添加 Authorization、Accept-Charset、Content-Type、Cache-Control、User-Agent 等标头。

单击添加标头，并按照自定义标头模态框中的提示添加所需的标头。 您可以选择在 Credential Vault 中存储的凭据，或凭据变量，或直接以不安全字符串输入标头。

内容类型
内容类型标头定义请求正文中的内容的媒体类型。 REST Web Services 操作 支持以下内容类型：
  • application/x-www-form-urlencoded： 将参数编码为 URL 查询字符串格式。
  • JSON（应用程序/json）： 输入 JSON 格式请求正文。
  • XML（应用程序/xml）： 输入 XML 格式请求正文。
  • 文本（文本/纯文本）： 输入纯文本格式的文本类型请求正文。
  • XML（文本/xml）： 输入 XML 格式的文本类型请求正文。
  • HTML（文本/html）： 输入 HTML 格式的文本类型请求正文。
  • multipart/form-data： 允许您在请求正文中包含文本和文件。 此内容类型支持 API 所支持的所有文件格式。 您可以使用此内容类型在单个请求中发送多个部分，通常包括文本数据（例如表单字段）以及可能的文件上传。 此内容类型还支持文件流式传输。
    将文件流分配给文件类型变量后可以读取。 例如，您可以读取分配给 OneDrive 位置中某个变量的文件流。 有关更多信息，请参阅 分配文件 操作。
    Rest Web Services FileStream

    对于不支持分块流式传输且要求预先提供内容长度的服务器，请启用在上传前缓冲文件复选框。 此选项仅适用于涉及文件流式传输的 Post 方法和 Put 方法操作。

    当您启用此复选框时，API 调用会在发送文件之前缓冲该文件，并在请求中包含 Content-Length 标头。 Content-Length 标头包含缓冲内容的总大小。 允许的最大文件大小为 150 MB。 如果文件大小超过 150 MB，系统会显示以下错误消息： 上传失败： 文件大小超过了 150 MB 的限制。 请选择较小的文件。

  • 二进制： 使用二进制发送原始文件，如图像、视频和音频文件。 您可以使用以下一个选项上传文件：
    • 变量： 分配文件变量，以便从桌面或 Control Room 中上传文件。 还可以使用此选项从存储位置流式传输文件。
    • Control Room 文件： 上传在 Control Room 存储中可用的文件。
    • 桌面文件： 直接从桌面上传文件。
  • 自定义
    自定义： 添加不属于标准内容类型的自定义内容。 例如，当您从 v.11.x 迁移到 Automation 360 时，以下值不属于任何标准内容类型：application/vnd.whispir.message-v1+json

对于 application/x-www-form-urlencoded 和 multipart/form-data，单击添加参数，并按照参数模型中的提示添加所需的标头参数。

对于其他内容类型，可以使用输入参数选项或选择凭据作为参数选项来添加参数。 选择凭据作为参数选项允许您将敏感数据添加为请求标头。

添加替换
添加替换选项允许您在 REST 请求正文中输入变量。 此选项适用于 JSON（应用程序/json）、XML（应用程序/xml）、文本（文本/纯文本）、XML（文本/xml）、HTML（文本/html）和自定义内容类型标头。
变量是数据的符号形式，您可以在必要时通过变量访问一个值，而无需手动输入。 例如，考虑以下 REST 请求体：
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
在上述请求体中，您可以通过单击添加替换并添加所需值来替换双括号内的变量。
高级选项
捕获故障响应： 选择该复选框以捕获失败响应（成功/正常响应除外）。 系统在响应正文中捕获故障响应详细信息。 此选项在删除、获取、修补、发布和放置方法操作中可用。
使用 https 时允许不安全的连接： 选中复选框以在使用 https 协议时允许建立不安全连接。 此选项在所有操作中可用。
接受 Cookie： 选中复选框以自动从服务器响应中捕获会话 cookie。 选中此复选框时，以下功能将在后台激活。
  • 捕获： 系统捕获服务器在响应中包含的会话 Cookie。
  • 安全存储： 系统在进程内存中对捕获的 Cookie 进行加密，确保其不会被永久存储，且在自动化会话之外无法访问。
  • 重用： 系统在后续 REST 调用中自动包含 Cookie，消除了手动处理 Cookie 的需要，从而提高了自动化可靠性。
  • 处理多个 Cookie： 系统允许自动化处理服务器返回的多个 Cookie，确保包含所有必要的身份验证凭据。
  • 销毁： 在自动化会话结束或机器人执行完成时，系统会自动销毁捕获的 Cookie，确保数据安全和隐私。

此选项在删除、获取、修补、发布和放置方法操作中可用。

注： 捕获的 Cookie 特定于其来源域，不会自动用于对不同域进行后续 REST 调用。 这意味着从 domainA.com 捕获的 Ccookie 将不会用于对 domainB.com 的请求。
下载文件： 选中此复选框以将 URI 中可用的二进制文件下载到特定位置。 确保您输入所需的文件路径以及名称和扩展名。 例如：<C:/Users/Downloads/image01.jpg>

此选项仅在获取方法操作中可用。 出现下列情况之一时，系统会显示错误消息：

  • 无效的 URI： 如果提供的 URI 不正确。
  • 未找到文件： 如果因指定位置不存在文件而出现 API 响应为空的情况。
  • 权限不足： 如果您没有下载位置的写入权限。
  • 文件扩展名不匹配： 如果文件扩展名与预期类型不匹配。

启用如果已存在则覆盖文件复选框，以使用新版本覆盖现有文件。

等待操作完成
您可以在发送 REST 请求并接收响应时设置超时值。 当您执行 操作（例如 POST、PUT、DELETE、PATCH 和 GET）时，请在等待操作完成字段中指定等待时间（以毫秒为单位）。 默认情况下，等待时间为 60000 毫秒。
SSL/TLS 配置
使用此选项上传带或不带密码的证书文件，以在 REST API 调用期间提供额外的身份验证。

SSL/TLS 配置使用双向 TLS (mTLS) 协议对 API URI 和客户端之间的通信进行加密、认证和保护。mTLS 要求双方实体通过交换证书相互认证。 只有在双方实体成功验证交换的证书后，才会进行数据传输。

REST Web Services 支持 Windows 机器的 .p12 类证书和非 Windows 机器的 .pfx 格式。

  • 密钥库文件路径（可选）： 使用变量、Control Room 文件或桌面文件选项上传证书。
  • 密钥库密码（可选）： 如果证书受密码保护，您可以使用凭据、变量或不安全字符串选项验证证书密码。 有关在凭据存储柜中安全存储密码的更多信息，请参阅 Credential Vault 中的凭据和 存储柜。
将输出分配到变量
响应输出在字典变量中捕获。 字典变量是密钥值对。 使用响应标题名称作为密钥返回标题值，或将“Body”作为密钥返回响应正文。

此选项在删除、获取、修补、发布和放置方法操作中可用。

注： 响应密钥及其值在字典变量中可用，以显示 REST API 的响应状态。
要获取 API 资源的标题名称列表，请执行以下步骤：
  1. 在 REST Web Services 操作 之后插入 循环 操作。
  2. 选择对于字典中的每个密钥迭代器。
  3. 在字典变量字段中，选择包含 REST Web Services 操作 输出的变量。
  4. 将每个密钥的值分配给 $prompt-assignment$。
  5. 插入将文本记录到文件 操作。
  6. 提供文本文件的文件路径以保存标题名称列表。
  7. 在将文本输入日志字段中插入 $prompt-assignment$。
  8. 选择覆盖现有文件选项。
  9. 单击保存。

    运行 机器人 时，会将标题名称从 API 资源打印到选定的文件。

将文件分配到变量
此选项仅在获取文件流操作中可用。 获取文件流操作允许您将文件变量分配给 URI 中的可用文件。 然后，您可以在会话的任何后续操作中使用此文件变量。 有关分配文件变量的更多信息，请参阅 使用获取文件流操作。

安全地传递值

您可以通过在以下支持的 操作 字段中指定 存储柜、凭据和属性，将值从 Credential Vault 安全地传递到 Web 服务：
  • URI
  • 自定义标头
  • 正文： 对于 application/x-www-form-urlencoded 内容类型，单击添加参数以从 Credential Vault 中选择值。

    对于所有其他内容类型，请选择选择凭据作为参数选项，然后单击选择。

操作 REST Web Services 中的 软件包

操作 描述
DELETE 方法 移除由 URI 标识的资源。
获取文件流方法 使用 URI 参数检索文件流资源，并将文件变量分配给该资源。
GET 方法 检索由 URI 中包含的参数标识的信息。 GET 方法没有内容类型，因为所有参数作为 URI 的一部分传递。

GET 方法的局限性和特征包括以下内容：

  • URI 长度限制为 2048 个字符。
  • 所有参数均在 URI 中传递。
  • GET 方法暴露 URI 中的数据，使其相对于 POST 方法不太安全。
  • GET 不会更改任何数据，使其对所有用户（无论授权如何）都很安全。

请参阅 使用 Get 方法。
补丁方法 修改由 URI 标识的资源。
POST 方法 在 URI 中创建新资源。
  • 参数在请求正文中传递。
  • 请求正文没有长度限制。

请参阅 使用 Post 方法。
PUT 方法 根据 URI 或正文中传递的参数更新或替换资源。 请参阅 使用 Put 方法。

代理支持

如果您的设备配置了代理，则来自此 软件包 的所有出站请求将通过代理服务器路由。 请参阅 使用代理将 Bot Agent 连接到设备。