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
  • 二进制： 使用二进制发送原始文件，如图像、视频和音频文件。 您可以使用以下一个选项上传文件：
    • 变量： 分配文件变量，以便从桌面或 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 标识的资源。
GET 方法 检索由 URI 中包含的参数标识的信息。 GET 方法没有内容类型，因为所有参数作为 URI 的一部分传递。

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

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

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

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

代理支持

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