CertCentral 的 Custom Reports API 可讓您運用強大的 GraphQL 查詢語言產生可自訂和全面性的資料集。
Custom Reports API (自訂報告 API) 將多個 REST 端點結合成一個,讓您可以更好的定義您的查詢中的類型和欄位,因此它們只會傳回需要的資訊。此外,您可以用其建立使用於產生和排程報告的可重複使用查詢範本。
GraphQL 是一種 API 查詢語言,使用僅傳回您需要的資料的查詢集。深入瞭解 GraphQL。
如果您對 GraphQL 陌生,建議您花一點時間閱讀 GraphQL 文件以瞭解與查詢語言有關的資訊。
GraphQL 文件涵蓋 CertCentral 的 Custom Reports API 可能不支援的特點和功能。
建構 API 要求時,請使用此基礎 URL:
https://www.digicert.com/services/v2/reports
查詢用於產生針對您的特定需求量身訂做的資料集。使用 /query
端點存取所有查詢。
自訂報告 API 目前提供兩種查詢:order_details 和 order_details_by_id。
引數與查詢配合使用,以進一步自訂或控制傳回的資料。
在此範例中,order_details
查詢包括三種引數:
status:"pending"
– 僅傳回擱置中訂單limit:5
– 將資料截斷成五個結果sort:["valid_from","DESC"]
– 使用 valid_from 值依降冪順序將資料排序order_details(status:"pending",limit:5,sort:["valid_from","DESC"])
在您的查詢中,納入或省略欄位讓您有權操作和自訂傳回資料的結構。
在此範例中,order_details_by_id
查詢用於傳回單一憑證順序的詳細資料。要求包括四個欄位:
id
common_name
purchase_dns_names
status
在回應本文中,僅傳回指定欄位。
您必須在要求中納入至少一個欄位。如果未納入任何欄位,傳回語法錯誤。
{
order_details_by_id(id:123456) {
id
common_name
purchased_dns_names
status
}
}
{
"data": {
"order_details_by_id": {
"id": "123456",
"common_name": "example.com",
"purchased_dns_names": "4",
"status": "issued"
}
}
}
如果不存在欄位的資料,則會傳回 null
的值。
對 Custom Reports API 的所有 API 要求由三個部份所組成:方法、端點和內文。本文的格式可以是 application/graphql 或 application/json,,視用於建構本文的語法而定。
若要查詢 Custom Reports API,您必須在要求標題中納入 DigiCert Developer API 密鑰。如需更多資訊,請參閱身份驗證。
對「自訂報告 API」的要求使用標準 HTTP POST 方法。
標示為 QUERY (查詢) 的端點表示端點使用 GraphQL 用戶端接受 GraphQL 語法的能力,但其仍使用 HTTP POS廿方法。
您可以兩個方式的其中之一建構和傳送要求本文:
將 GraphQL 查詢語法轉換成有效的 JSON 字串時:
\"
)。id,common_name,dns_names
)。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
}
}
{
"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 物件的名稱。
{
new_customer_order: order_details_by_id(id:123456) {
id
common_name
purchased_dns_names
status
}
}
{
"data": {
"new_customer_order": {
"id": "123456",
"common_name": "example.com",
"purchased_dns_names": "4",
"status": "issued"
}
}
}
使用每個查詢的自訂名稱傳送有單一要求的多個查詢。
在此範例中,使用每個查詢的自訂名稱在單一要求中傳送兩個個別的 order_details
查詢。在回應本文中,使用指派的自訂名稱傳回兩個查詢。
{
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
}
}
{
"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
查詢。但每個查詢都使用不同的欄位順序,在回應本文中反映出來。
{
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
}
}
{
"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"
}
}
}