HB_API_POST 命令

将 POST 请求发送到 HighBond API。

语法

HB_API_POST HighBond_API_请求_URL HEADERS 标头信息 DATA 负载文件 PASSWORD 数值 <TO 响应文件>

参数

名称 描述
HighBond_API_请求_URL

Diligent One 资源的请求详细信息。

在请求 URL 中添加以下详细信息：

  • 主机信息，包括 Diligent One 区域

  • API 版本号（当前的主要版本号）

  • Diligent One 实例 ID（组织 ID）

  • HighBond API 端点名称，以及任何其他端点详细信息，例如 ID 编号

例如：

"https://apis-us.highbond.com/v1/orgs/11594/robots"

有关特定 Diligent One 资源的请求语法，请参阅 HighBond API 参考。

HEADERS 标头信息

请求标头信息。

在标头中，指定 HighBond API 请求的内容类型：

'{"content-type": "application/vnd.api+json"}'
DATA 负载文件

包含请求负载的文件名称。

请求负载是指您希望发送到 Diligent One 的数据。您将数据添加到 JSON 文件，并使用 DATA 引用 HighBond API 请求中的文件。有关为特定 Diligent One 资源构建负载数据的指南，请参阅 HighBond API 参考。

将负载文件指定为具有 *.json 文件扩展名的带引号字符串。例如：

DATA "payload.json"

说明

对于您打算在机器人中运行的脚本，还必须在分析标头中指定 //FILE 标记 ，与 DATA 负载文件参数对应。例如：

COMMENT
//ANALYTIC Test HB API 命令
//FILE payload.json
END

保存负载 JSON 文件的位置

保存负载 JSON 文件的位置，取决于您打算运行脚本的位置。

在 Analytics 中运行脚本

您可以将负载 JSON 文件保存在包含 Analytics 项目的文件夹中，也可以将其保存在其他文件夹中。

如果将负载文件保存在项目文件夹以外的文件夹中，则负载文件需要添加文件路径和文件名：

DATA "C:\HighBond API payloads\payload.json"

在机器人中运行脚本

将负载 JSON 文件上传到将运行脚本的机器人中的输入/输出 选项卡。该文件必须存在于选项卡中，然后才能运行脚本。

在负载文件中，仅指定文件名称。请勿指定文件路径。

PASSWORD 数字

要使用的密码定义。

您不使用 PASSWORD 数字 提示用户提供或者指定实际密码。密码定义是指先前使用 PASSWORD 命令、SET PASSWORD 命令或 PASSWORD 分析标记提供或设置的密码。

数字是密码定义的编号。例如，如果之前已在脚本中或在调度分析脚本时提供或设置了两个密码，则 PASSWORD 2 指定使用密码 #2。

有关提供或设置密码的详细信息，请参见：

所需的密码值是 HighBond 访问令牌。有关详细信息，请参见创建密码定义并指定密码值。

可能需要也可能不需要 PASSWORD 数值，具体取决于脚本运行的环境。

脚本运行环境 PASSWORD 数值要求
Analytics

（在线激活）

不需要 PASSWORD 数值。

会自动使用当前用户存储在 Windows 注册表中的 HighBond 访问令牌。
Analytics

（离线激活）

需要 PASSWORD 数值。
机器人
TO 响应文件

可选

包含请求响应的文件名称。

将响应文件指定为具有 *.json 文件扩展名的带引号字符串。例如：

TO "response.json"

保存响应 JSON 文件的位置

保存响应 JSON 文件的位置，取决于您运行脚本的位置。

在 Analytics 中运行脚本

默认情况下，响应 JSON 文件会保存到包含该 Analytics 项目的文件夹。

添加带名称的文件路径，将文件保存到不同的现有文件夹：

TO "C:\HighBond API responses\response.json"

在机器人中运行脚本

如果在分析标头中指定 //RESULT FILE 标记，响应 JSON 文件会保存为机器人中运行的每个任务的输出。

仅指定文件名称。请勿指定文件路径。

示例

在 Diligent One 项目中创建问题

构建使用 JSON 格式的请求负载，并将该负载保存在名为 create_issue.json 的文件中。然后，使用 HB_API_POST 命令并在命令中指定负载文件，在项目 ID 19756 中创建问题。

提示

若要快速构建负载语法，请从 HighBond API 参考中复制相应的负载语法块。复制负载语法块之后，则可以移除打算留空的键值对。

HB_API_POST "https://apis-us.highbond.com/v1/orgs/11594/projects/19756/issues" HEADERS '{"content-type": "application/vnd.api+json"}' DATA "create_issue.json" PASSWORD 1 TO "hb_api_response.json"

create_issue.json 的内容：

{
"data":{ 
        "type": "issues",
        "attributes": {
            "description": "Description of issue",
            "owner": "Jane Sleaman",
            "deficiency_type": "Deficiency",
            "title": "Data retention and backup",
            "severity": "High",
            "published": true,
            "identified_at": "2021-11-01T18:15:30Z"
                }
    }
}

备注

创建密码定义并指定密码值

当您在机器人中运行向 HighBond API 发送请求的脚本时，需要在发送请求的命令中添加密码定义。如果您使用离线激活，则同样的要求适用于在 Analytics 中运行的脚本。

无论您使用哪种方法创建密码定义，必填的密码值都是 HighBond 访问令牌，您可以在启动面板中生成该令牌。有关详细信息，请参阅获取 HighBond 访问令牌。

密码定义方法

方法 描述

PASSWORD 分析标记

（适用于在机器人中运行的脚本）

如果使用 PASSWORD 分析标记创建用于连接到 Diligent One 的编号密码定义，且脚本中未指定密码值。当您创建一个要在机器人中运行脚本的任务时，任务设计器中的输入字段允许您或其他用户指定机器人实际密码。

有关更多信息，请参阅 PASSWORD 分析标记。

PASSWORD 命令

（适用于在 Analytics 中运行的脚本，离线激活）

如果使用 PASSWORD 命令创建用于连接到 Diligent One 的编号密码定义，且脚本中未指定密码值。当脚本试图连接时，会显示密码提示。

有关详细信息，请参见PASSWORD 命令。

SET PASSWORD 命令

（适用于在 Analytics 中运行的脚本，离线激活）

如果使用 SET PASSWORD 命令创建用于连接到 Diligent One 的编号密码定义，且在脚本中指定了密码值，则不会显示密码提示。这种方法适用于设计为以无人看管方式运行的脚本，但它会在脚本中以明文形式显示实际密码，这可能不适合您的情况。

有关详细信息，请参见 SET PASSWORD 命令。

获取 HighBond 访问令牌

注意

生成的访问令牌与用于登录 Diligent One 的账户匹配。 作为脚本编写者，如果该脚本将供他人使用，则在脚本中指定您自己的访问令牌可能不适当。

像保护任何账户密码一样保护访问令牌。

除非有充分的理由创建新令牌，否则请使用现有令牌。如果现有令牌不工作，请创建一个新的令牌。使用现有令牌可削减您需要管理的令牌数。

  1. 执行以下操作之一：

    • 从 Analytics 主菜单中，选择工具 > HighBond 访问令牌。

    • 在脚本编辑器中，右键单击并选择插入 > HighBond 令牌。

    管理 API 令牌页面将在您的浏览器中打开。您可能需要先登录到 Diligent One。

    通过 Analytics 访问管理 API 令牌页面是一项便利功能。Analytics您还可以登录到 Diligent One，然后通过用户个人资料访问该页面，而无需使用 Analytics。

  2. 执行以下操作之一：

    • 使用现有令牌

      1. 在令牌列中，单击要使用的已部分屏蔽的令牌。

      2. 输入您的 Diligent One 账户密码，然后单击确认。

        未屏蔽的令牌被显示。

      3. 单击复制以复制该令牌。

        提示

        在成功粘贴该令牌之前，请勿关闭包含该令牌的对话框。

    • 创建新令牌

      1. 单击添加令牌 > Analytics。

      2. 在新建 Analytics 令牌侧面板中，指定以下信息：

        域或选项 描述
        描述

        输入提供有用信息的描述，例如：

        • 令牌的用途
        • 令牌的使用场景 – 例如，分析脚本的名称和位置，或者机器人任务的名称和位置
        令牌有效期
        • 已启用令牌将在您指定的天数之后到期
        • 已禁用令牌永不过期

        说明

        贵组织可能制定了一项安全政策，要求令牌在一定时间之后到期。创建包含有效期的令牌是一种好做法。Diligent One 会在到期日之前，向您发送一封自动电子邮件通知。
        即将在…到期 指定距离令牌到期日之前的天数（1 到 365 天）。
        密码 输入您的 Diligent One 账户密码。

      3. 单击生成令牌。

      4. 单击复制以复制该令牌。

        提示

        在成功粘贴该令牌之前，请勿关闭包含该令牌的侧面板。

  3. 根据您使用的密码定义方法，执行以下操作之一：

    • PASSWORD 分析标记在 ACL 机器人的任务设计器中，将复制的令牌粘贴到密码参数字段中。

    • PASSWORD 命令在 Analytics 中，将复制的令牌粘贴到执行脚本过程中出现的密码提示中。

    • SET PASSWORD 命令在 Analytics 中，将复制的令牌粘贴到脚本中 SET PASSWORD 命令语法的适当位置。

  4. 在启动面板中，关闭包含该令牌的对话框或侧面板。

    如果您创建了新令牌，则该令牌的部分屏蔽版本被添加到您的令牌列表的顶部。

    有关更多信息，请参阅创建和管理 HighBond 访问令牌。