自定义报告 API

CertCentral 的自定义报告 API 可用于通过强大的 GraphQL 查询语言生成可自定义的全面数据集。

为什么使用它?

自定义报告 API 将多个 REST 端点整合到一个端点中,使您能更好地定义查询中的类型和字段,从而仅返回需要的信息。而且,您可以用它来创建用于生成和调度报告的可重用查询模板。

为什么是 GraphQL?

GraphQL 是一种 API 查询语言,可通过使用查询组来仅返回您需要的准确数据,而不提供更多其他数据。进一步了解 GraphQL

如果您刚接触 GraphQL,我们建议您花时间阅读 GraphQL 文件,了解有关查询语言的信息。

GraphQL 文件包含 CertCentral 自定义报告 API 可能不支持的特性和功能。

基本 URL

创建 API 请求时使用此基本 URL:

markup
https://www.digicert.com/services/v2/reports

查询

查询用于生成专为您的特定需求而定制的数据集。所有查询经使用 /query 端点进行访问。

自定义报告 API 目前提供两种查询:order_detailsorder_details_by_id

参数

参数与查询一起使用,以进一步自定义或操纵返回的数据。

在该示例中,order_details 查询包括三个参数:

  • status:"pending" - 仅返回待处理的订单
  • limit:5 - 将数据截断至五个结果
  • sort:["valid_from","DESC"] - 使用 valid_from 值整理数据并按降序排列
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

字段

通过在查询中包含或省略字段,可以操纵和自定义所返回数据的结构。

在该示例中,order_details_by_id 查询用于返回单个证书订单的详细信息。请求包括四个字段:

  • id
  • common_name
  • purchase_dns_names
  • status

在响应主体中,仅返回指定的字段。

在请求中必须包含至少一个字段。如果不包含任何字段,则返回句法错误。

GraphQL
{
    order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
    }
}
200 OK
{
    "data": {
        "order_details_by_id": {
            "id": "123456",
            "common_name": "example.com",
            "purchased_dns_names": "4",
            "status": "issued"
        }
    }
}

如果字段不存在数据,则返回 null 值。

请求

对自定义报告 API 的所有 API 请求包括三个部分:方法、端点和主体。主体格式可以是 application/graphqlapplication/json,,这取决于用于构建主体的句法。

要使用自定义报告 API,必须在请求标头中包括一个 DigiCert Developer API 密钥。请参阅身份验证了解更多信息。

方法

自定义报告 API 请求使用标准 HTTP POST 方法。

标记为 QUERY 的端点表示该端点能使用 GraphQL 客户端访问 GraphQL 句法。但是,它们仍然使用 HTTP POST 方法。

主体

可以通过以下两种方式之一构建和发送请求主体:

  • 使用 GraphQL 查询句法并通过 GraphQL 客户端发送请求。
  • 将 GraphQL 查询句法转换为有效的 JSON 字符串并通过 JSON 工作负载发送请求。

将 GraphQL 查询句法转换为有效的 JSON 字符串的方法:

  • 删除查询中的所有新行(字符串必须为单一行)。
  • 转义所有双引号(例如,\")。
  • 用逗号分隔多个字段(例如,id,common_name,dns_names)。
  • 在 JSON 请求主体中使用 query 参数并将其值设置为转换后的字符串。
GraphQL
{
    order_details(valid_till:"2020-10-26",status:"issued",limit:5,sort:["valid_from","DESC"]) {
        id
        common_name
        dns_names
        organization_id
        status
        valid_from
        valid_till
    }
}
JSON
{
    "query": "{order_details(valid_till:\"2020-10-26\",status:\"issued\",limit:5,sort:[\"valid_from\",\"DESC\"]){id,common_name,dns_names,organization_id,status,valid_from,valid_till}}"
}

提示和技巧

自定义查询名称

可以为查询分配一个自定义名称并反映在响应主体中。

在该示例中,自定义名称 new_customer_order 分配给了 order_details_by_id 查询。在响应主体中,自定义名称反映为含有所查询订单信息的 JSON 对象的名称。

GraphQL
{
    new_customer_order: order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
    }
}
200 OK
{
    "data": {
        "new_customer_order": {
            "id": "123456",
            "common_name": "example.com",
            "purchased_dns_names": "4",
            "status": "issued"
        }
    }
}

发送多个查询

通过一个请求发送多个查询,其中为每个请求使用自定义名称。

在该示例中,通过一个请求发送了两个单独的 order_details 请求,其中为每个请求使用了自定义名称。在响应主体中,使用分配的自定义名称返回两个查询。

GraphQL
{
    pending_orders: order_details(status:"pending",limit:5,sort:["date_created","DESC"]) {
        id
        status
        common_name
        purchased_dns_names
        date_created
    }
    issued_orders: order_details(status:"issued",limit:5,sort:["date_created","DESC"]) {
        id
        status
        common_name
        purchased_dns_names
        date_created
    }
}
200 OK
{
    "data": {
        "pending_orders": [
            {
                "id": "100010",
                "status": "pending",
                "common_name": "test.example.com",
                "purchased_dns_names": "1",
                "date_created": "2019-10-09 12:55:29"
            },
            {
                "id": "100011",
                "status": "pending",
                "common_name": "monitor.example.com",
                "purchased_dns_names": "1",
                "date_created": "2019-10-08 16:54:55"
            },
            {
                "id": "100012",
                "status": "pending",
                "common_name": "logs.example.com",
                "purchased_dns_names": "1",
                "date_created": "2019-10-08 14:03:22"
            },
            {
                "id": "100013",
                "status": "pending",
                "common_name": "docs.example.com",
                "purchased_dns_names": "1",
                "date_created": "2019-10-08 12:50:42"
            },
            {
                "id": "100014",
                "status": "pending",
                "common_name": "staging.example.com",
                "purchased_dns_names": "1",
                "date_created": "2019-10-08 10:08:03"
            }
        ],
        "issued_orders": [
            {
                "id": "100005",
                "status": "issued",
                "common_name": "example.com",
                "purchased_dns_names": "0",
                "date_created": "2019-10-04 17:56:36"
            },
            {
                "id": "100006",
                "status": "issued",
                "common_name": "example.org",
                "purchased_dns_names": "2",
                "date_created": "2019-10-04 11:36:10"
            },
            {
                "id": "100007",
                "status": "issued",
                "common_name": "example.net",
                "purchased_dns_names": "1",
                "date_created": "2019-10-04 04:05:41"
            },
            {
                "id": "100008",
                "status": "issued",
                "common_name": "example.biz",
                "purchased_dns_names": "4",
                "date_created": "2019-10-02 06:32:54"
            },
            {
                "id": "100009",
                "status": "issued",
                "common_name": "example.ca",
                "purchased_dns_names": "0",
                "date_created": "2019-09-30 08:04:18"
            }
        ]
    }
}

给响应数据重新排序

查询中各字段的排序方式决定了响应主体中的信息的排序方式。这意味着您可以整理查询字段,使响应主体按需要的方式排序。

在该示例中,发送了两个 order_details_by_id 查询,它们请求的信息相同。但是,每个查询各自使用不同的字段顺序,这反映在了响应主体中。

GraphQL
{
    cert_order_1: order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
        organization_id
    }
    cert_order_2: order_details_by_id(id:123457) {
        status
        common_name
        purchased_dns_names
        id
        organization_id
    }
}
200 OK
{
    "data": {
        "cert_order_1": {
            "id": "123456",
            "common_name": "example.com",
            "purchased_dns_names": "4",
            "status": "issued",
            "organization_id": "334455"
        },
        "cert_order_2": {
            "status": "pending",
            "common_name": "example.net",
            "purchased_dns_names": "1",
            "id": "123457",
            "organization_id": "334455"
        }
    }
}