‎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 项目中创建问题

构建采用 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。

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

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

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

系统用户令牌

购买了特定 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")