api_post() 方法

将 POST 请求发送到 HighBond API。

语法

hcl.api_post("HighBond API 请求详情",data = 请求负载)

参数

名称	描述
HighBond API 请求详细信息	Diligent One 资源的请求详细信息。 hcl.api_post 会在后台自动提供请求详细信息的标准部分。除非要覆盖默认值，否则不需要显式指定这些请求元素：主机信息 Diligent One 区域 Diligent One 实例 ID（组织 ID）标头信息有关特定 Diligent One 资源的请求语法，请参阅 HighBond API 参考。说明如果您明确地指定主机信息，则必须使用 HTTPS 协议来连接 HighBond API。例如：https://apis-us.highbond.com
data = 请求负载	要发送到 Diligent One API 服务器的数据。负载数据必须采用 JSON 格式。

名称

描述

HighBond API 请求详细信息

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

hcl.api_post 会在后台自动提供请求详细信息的标准部分。除非要覆盖默认值，否则不需要显式指定这些请求元素：

主机信息
Diligent One 区域
Diligent One 实例 ID（组织 ID）
标头信息

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

说明

如果您明确地指定主机信息，则必须使用 HTTPS 协议来连接 HighBond API。例如：https://apis-us.highbond.com

data = 请求负载

要发送到 Diligent One API 服务器的数据。

负载数据必须采用 JSON 格式。

来自 HighBond API 服务器的响应对象。

示例

在 Diligent One 项目中创建问题

构建采用 JSON 格式的请求负载，并将负载分配给 payload 变量。然后使用 hcl.api_post 方法并引用方法中的payload变量，在 ID 为 19756 的项目中创建问题。

提示

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

payload = {"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"
                    }
                }
            }

hcl.api_post("projects/19756/issues", data = payload)

备注

身份验证

所有 HighBond API 请求需要进行身份验证。您必须是至少一个 Diligent One 实例中的系统管理员才能访问该 API。

要进行身份验证，请使用启动面板为您的账户创建一个 HighBond API 令牌。该令牌是验证您身份的一个字符串，它允许您安全地访问 HighBond API。有关创建令牌的帮助，请参阅创建和管理 HighBond 访问令牌。

将 HighBond API 令牌与 HighBond API 方法结合使用

要将 HighBond API 令牌与 HighBond API 方法结合使用，必须将该令牌分配给一个名为 v_hb_token 的 HCL 变量。分配该令牌之后，它将会在后台自动用于身份验证，无需在 Diligent One 脚本中显式指定。有关将令牌分配给变量的信息，请参阅使用变量窗口定义 HCL 变量。

系统用户令牌

购买了特定 Diligent One 工具包的客户，还可以选择使用通用系统用户令牌，而不是与特定用户帐户关联的令牌进行身份验证。

仅指定资源 URL 的唯一部分

使用 HighBond API 方法时，只需指定 Diligent One 资源 URL 的唯一部分或端点。无需指定您正在处理的 Diligent One 实例的公共部分（基础 URL）或 ID。此信息在后台自动提供。

例如，如果您在 ID 为 1000236 的 Diligent One 实例中工作，那么这两个 API 请求会返回相同的响应。二者均列出项目 19756 中的所有问题。

hcl.api_get("projects/19756/issues")

hcl.api_get("https://apis.highbond.com/v1/orgs/1000236/projects/19756/issues")

请参阅《HighBond API 参考》

HighBond API 参考中提供了每个 Diligent One 资源的请求语法。例如，下面是获取项目中问题列表的请求语法。

如果使用 HCL 方法发出请求，则可以从 projects/... 开始指定语法：

如果从 Diligent One 外部发出请求，则需要从协议 ( https://... ) 开始指定整个资源 URL。

在资源 URL 中使用变量

与在资源 URL 中指定文本 ID 不同，您可能具有需要在该 URL 中使用变量的代码。资源 URL 被格式化为字符串，因此要在字符串中包含变量，您需要使用下面所示的 Python 技术之一。

您可以使用 Python f 字符串：

v_project_id = "19756"
hcl.api_get(f"projects/{v_project_id}/issues")

您可以使用 Python 字符串连接：

v_project_id = "19756"
hcl.api_get("projects/" + v_project_id + "/issues")