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。

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

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

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

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

（在线激活）

不需要 PASSWORD 数值。

将自动使用当前用户存储在 Windows 注册表中的 Diligent One 访问令牌。
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 中运行的脚本。

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

密码定义方法

方法 描述

PASSWORD 分析标记

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

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

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

PASSWORD 命令

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

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

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

SET PASSWORD 命令

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

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

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

获取 Diligent One 访问令牌

注意

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

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

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

  1. 执行以下操作之一：

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

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

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

    通过 Analytics 访问管理 API 令牌页面是一项便利功能。您还可以登录到 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. 在启动面板中，关闭包含该令牌的对话框或侧面板。

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

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