L’API Custom Reports di CertCentral ti consente di generare serie di dati personalizzabili e complessive sfruttando il potente linguaggio di interrogazione GraphQL.
L’API Custom Reports consolida più endpoint REST in uno solo, consentendoti di definire meglio i tipi e i campi nelle tue query in modo che ti forniscano solo le informazioni necessarie. Inoltre, puoi usarlo per creare dei modelli di query riutilizzabili per generare e pianificare i report.
GraphQL è un linguaggio di interrogazione API che utilizza le serie di query per riportare solamente i dati che ti servono e nient’altro. Scopri di più su GraphQL.
Se non conosci GraphQL, ti consigliamo di leggere brevemente la documentazione GraphQL per scoprire ulteriori informazioni sul linguaggio di interrogazione.
La documentazione GraphQL spiega le funzioni e le funzionalità che potrebbero non essere supportate dall’API Custom Reports di CertCentral.
Usa questo URL base quando crei delle richieste API:
https://www.digicert.com/services/v2/reportsLe query vengono usate per generare delle serie di dati create su misura per le tue esigenze specifiche. A tutte le query si accede usando l’endpoint /query.
L’API Custom Reports attualmente offre due query: order_details e order_details_by_id.
Gli argomenti vengono usati con le query per personalizzare ulteriormente o manipolare i dati restituiti.
In questo esempio, la query order_details include tre argomenti:
status:"pending" – Restituisce solo gli ordini in attesalimit:5 – Tronca i dati a cinque risultatisort:["valid_from","DESC"] – Ordina i dati usando il valore valid_from in ordini decrescenteorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])L’inclusione o l’omissione dei campi nella tua query ti consente di manipolare e personalizzare la struttura dei dati restituiti.
In questo esempio, la query order_details_by_id viene usata per restituire i dettagli di un ordine di certificato singolo. La richiesta include quattro campi:
idcommon_namepurchase_dns_namesstatusNel corpo della risposta, vengono restituiti solo i campi specificati.
Devi includere almeno un campo nella richiesta. Se non viene incluso alcun campo, viene riportato un errore di sintassi.
{
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"
}
}
}Se non esistono dati per il campo, viene riportato un valore null.
Tutte le richieste API effettuate all’API Custom Reports sono formate da tre parti: metodo, endpoint e corpo. Il formato del corpo può essere applicazione/graphql o applicazione/json, in base alla sintassi usata per costruire il corpo.
Per usare l’API Custom Reports, devi includere una chiave API DigiCert Developer nell’intestazione della richiesta. Consulta Autenticazione per ulteriori informazioni.
Le richieste all’API Custom Reports usano metodi HTTP POST.
Gli endpoint etichettati con QUERY denotano la capacità degli endpoint di accettare la sintassi GraphQL usando un client GraphQL; tuttavia, utilizzano ancora il metodo HTTP POST.
Puoi costruire e inviare una corpo di richiesta in uno di questi due modi:
Quando si converte una sintassi di query GraphQL ad una stringa JSON valida:
\").id,common_name,dns_names).query nella corpo della richiesta JSON e imposta il suo valore nella stringa convertita.{
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}}"
}A una query può essere assegnata un nome personalizzato che viene riflesso nel corpo della risposta.
In questo esempio, un nome personalizzato di new_customer_order viene assegnato alla query order_details_by_id. Nel corpo della risposta, il nome personalizzato viene riflesso come nome dell’oggetto JSON contenente le informazioni ordine della query.
{
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"
}
}
}Invia query multiple con una sola richiesta usando nomi personalizzati per ciascuna query.
In questo esempio, due query order_details separate vengono inviate in una sola richiesta usando nomi personalizzati per ciascuno. Nel corpo della risposta, le due query vengono riportate con i nomi personalizzati assegnati.
{
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"
}
]
}
}Il modo in cui ordini i campi in una query determina come vengono ordinate le informazioni nel corpo della risposta. Ciò significa che puoi sistemare i tuoi campi di query in modo che il corpo della risposta sia nell’ordine desiderato.
In questo esempio, vengono inviate due order_details_by_id che richiedono le stesse informazioni. Tuttavia, ciascuna query utilizza un ordine di campi diverso, che viene riflesso nel corpo della risposta.
{
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"
}
}
}