API Custom Reports

L’API Custom Reports di CertCentral ti consente di generare serie di dati personalizzabili e complessive sfruttando il potente linguaggio di interrogazione GraphQL.

Perché usarla?

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.

Cos’è GraphQL?

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.

URL base

Usa questo URL base quando crei delle richieste API:

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

Query

Le 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.

Argomenti

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 attesa
  • limit:5 – Tronca i dati a cinque risultati
  • sort:["valid_from","DESC"] – Ordina i dati usando il valore valid_from in ordini decrescente
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Campi

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:

  • id
  • common_name
  • purchase_dns_names
  • status

Nel 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.

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"
        }
    }
}

Se non esistono dati per il campo, viene riportato un valore null.

Richieste

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.

Metodo

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.

Corpo

Puoi costruire e inviare una corpo di richiesta in uno di questi due modi:

  • Usando la sintassi della query GraphQL e inviando la richiesta tramite un client GraphQL.
  • Convertendo una sintassi di query GraphQL ad una stringa JSON valida e inviando la richiesta tramite un carico utile JSON.

Quando si converte una sintassi di query GraphQL ad una stringa JSON valida:

  • Rimuovi tutte le righe nuove nella query (la stringa deve essere una sola riga).
  • Esci da tutte le virgolette doppie (ad es. \").
  • Separa più campi con le virgole (ad es. id,common_name,dns_names).
  • Usa il parametro query nella corpo della richiesta JSON e imposta il suo valore nella stringa convertita.
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}}"
}

Consigli pratici

Nomi query personalizzati

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.

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"
        }
    }
}

Invia query multiple

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.

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"
            }
        ]
    }
}

Riordina i dati risposta

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.

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"
        }
    }
}