自訂報告 API

CertCentral 的 Custom Reports API 可讓您運用強大的 GraphQL 查詢語言產生可自訂和全面性的資料集。

為什麼要使用?

Custom Reports API (自訂報告 API) 將多個 REST 端點結合成一個,讓您可以更好的定義您的查詢中的類型和欄位,因此它們只會傳回需要的資訊。此外,您可以用其建立使用於產生和排程報告的可重複使用查詢範本。

什麼是 GraphQL?

GraphQL 是一種 API 查詢語言,使用僅傳回您需要的資料的查詢集。深入瞭解 GraphQL

如果您對 GraphQL 陌生,建議您花一點時間閱讀 GraphQL 文件以瞭解與查詢語言有關的資訊。

GraphQL 文件涵蓋 CertCentral 的 Custom Reports 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 的值。

要求

對 Custom Reports API 的所有 API 要求由三個部份所組成:方法、端點和內文。本文的格式可以是 application/graphqlapplication/json,,視用於建構本文的語法而定。

若要使用「自訂報告 API」,您必須在要求標題中包含 DigiCert 開發人員 API 金鑰。如需更多資訊,請參閱驗證

方法

對「自訂報告 API」的要求使用標準 HTTP POST 方法。

標示為 QUERY (查詢) 的端點表示端點使用 GraphQL 用戶端接受 GraphQL 語法的能力,但其仍使用 HTTP POS廿方法。

內文

您可以兩個方式的其中之一建構和傳送要求本文:

  • 使用 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"
        }
    }
}