API Custom Reports

L’API Custom Reports de CertCentral vous permet de générer des ensembles de données complets et personnalisables en tirant parti du puissant langage de requête GraphQL.

Pourquoi l’utiliser ?

L’API Custom Reports regroupe plusieurs points de terminaison REST en un seul, ce qui vous permet de mieux définir les types et les champs de vos requêtes pour qu'elles ne renvoient que les informations nécessaires. Vous pouvez également l'utiliser pour créer des modèles de demandes réutilisables pour générer et planifier des rapports.

Qu’est-ce que GraphQL ?

GraphQL est un langage de demandes d’API qui utilise des ensembles de demandes pour ne renvoyer que les données dont vous avez besoin et rien d’autre. En savoir plus sur GraphQL.

Si vous débutez avec GraphQL, nous vous recommandons de consacrer quelques minutes à la lecture de la documentation GraphQL afin de vous familiariser avec ce langage de requête.

La documentation GraphQL couvre des fonctions et fonctionnalités susceptibles de ne pas être compatibles avec l’API Custom Reports de CertCentral.

URL de base

Utilisez cette URL de base lors de l’établissement des demandes d’API :

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

Requêtes

Les requêtes sont utilisées pour générer des ensembles de données qui sont adaptés à vos besoins spécifiques. Toutes les requêtes sont accessibles via le point de terminaison /query.

L’API Custom Reports propose actuellement deux requêtes : order_details et order_details_by_id.

Arguments

Les arguments sont utilisés avec les requêtes pour personnaliser ou manipuler davantage les données renvoyées.

Dans cet exemple, la requête order_details inclut trois arguments :

  • status:"pending" – Retourne uniquement les commandes en attente
  • limit:5 – Tronque les données à cinq résultats
  • sort:["valid_from","DESC"] – Trie les données en utilisant la valeur valid_from par ordre décroissant
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Champs

L'inclusion ou l'omission de champs dans votre requête vous donne le pouvoir de manipuler et de personnaliser la structure des données renvoyées.

Dans cet exemple, la requête order_details_by_id est utilisée pour renvoyer les détails d'une commande de certificat unique. La demande contient quatre champs :

  • id
  • common_name
  • purchase_dns_names
  • status

Dans le corps de la réponse, seuls les champs spécifiés sont renvoyés.

Vous devez inclure au moins un champ dans la demande. Si aucun champ n'est inclus, une erreur de syntaxe est renvoyée.

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

S’il n’existe pas de données pour le champ, une valeur de null est renvoyée.

Demandes

Toutes les demandes d’API envoyées à l’API Custom Reports sont composées de trois éléments : la méthode, le point de terminaison et le corps. Le format du corps peut être soit application/graphql ou application/json, en fonction de la syntaxe utilisée pour le construire.

Pour utiliser l’API Custom Reports, vous devez inclure une clé d’API Developper DigiCert dans l’en-tête de la demande. Pour en savoir plus, consultez la page Authentification.

Méthode

Les demandes à l'API Custom Reports utilisent les méthodes HTTP POST standard.

Les points de terminaison portant la mention REQUÊTE indiquent la capacité du point de terminaison à accepter la syntaxe GraphQL en utilisant un client GraphQL ; cependant, ils utilisent toujours la méthode HTTP POST.

Corps

Vous pouvez construire et envoyer un corps de demande de deux manières :

  • En utilisant la syntaxe de requête GraphQL et en envoyant la requête via un client GraphQL.
  • En convertissant la syntaxe de la requête GraphQL en une chaîne JSON valide et en envoyant la requête via une charge utile JSON.

Lors de la conversion de la syntaxe de la requête GraphQL en une chaîne JSON valide :

  • Supprimez toutes les nouvelles lignes de la requête (la chaîne doit être constituée d'une seule ligne).
  • Évitez les guillemets (par ex, \").
  • Séparez les champs multiples par des virgules (par ex, id,common_name,dns_names).
  • Utilisez le paramètre query dans votre corps de requête JSON et fixez sa valeur à la chaîne convertie.
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}}"
}

Conseils et astuces

Noms de requête personnalisés

Une requête peut se voir attribuer un nom personnalisé qui sera reproduit dans le corps de la réponse.

Dans cet exemple, le nom personnalisé new_customer_order est attribué à la requête order_details_by_id. Dans le corps de la réponse, le nom personnalisé est reproduit sous la forme du nom de l'objet JSON contenant les informations sur la commande interrogée.

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

Envoyer plusieurs requêtes

Envoyez plusieurs requêtes sous la forme d'une seule requête en utilisant des noms personnalisés pour chacune.

Dans cet exemple, deux requêtes order_details distinctes sont envoyées sous la forme d'une seule requête utilisant des noms personnalisés pour chacune. Dans le corps de la réponse, les deux requêtes sont renvoyées en utilisant les noms personnalisés attribués.

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

Réorganiser les données de réponse

Votre façon d'organiser les champs d'une requête détermine la façon dont les informations sont présentées dans le corps de la réponse. Ce qui signifie que vous pouvez organiser vos champs de requête de manière à ce que le corps de la réponse soit dans l'ordre souhaité.

Dans cet exemple, deux requêtes order_details_by_id sont envoyées pour demander la même information. Cependant, chaque requête utilise un ordre de champ différent, qui se reflète dans le corps de la réponse.

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