Custom Reports API

Mit der Custom Reports API von CertCentral können Sie anpassbare und umfassende Datensets generieren, indem Sie die leistungsstarke GraphQL-Abfragesprache benutzen.

Warum sie verwenden?

Die Custom Reports-API konsolidiert mehrere REST-Endpunkte in einen einzigen, sodass Sie die Typen und Felder in Ihren Abfragen besser definieren können und nur die benötigten Informationen angezeigt werden. Zusätzlich können Sie sie nutzen, um wiederverwendbare Abfragevorlagen zur Erstellung und Planung von Berichten zu erstellen.

Was ist GraphQL?

GraphQL ist eine API-Abfragesprache, die Abfragesets verwendet, sodass Sie nur die Daten erhalten, die Sie benötigen, und sonst nichts. Weitere Informationen zu GraphQL.

Falls Sie GraphQL noch nicht kennen, empfehlen wir, sich einen Moment Zeit zu nehmen und die GraphQL-Dokumentation zu lesen, um die Abfragesprache zu lernen.

Die GraphQL-Dokumentation enthält Features und Funktionen, die möglicherweise vom Custom Reports API von CertCentral nicht unterstützt werden.

Basis-URL

Verwenden Sie diese Basis-URL zum Erstellen von API-Anfragen:

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

Abfragen

Abfragen werden verwendet, um Datensets zu generieren, die exakt auf Ihren spezifischen Bedarf zugeschnitten sind. Auf alle Anfragen wird über den /query-Endpunkt zugegriffen.

Custom Reports API bietet derzeit zwei Abfragen: order_details und order_details_by_id.

Argumente

Argumente werden bei Anfragen verwendet, um die zurückgegebenen Daten weiter anzupassen oder zu manipulieren.

In diesem Beispiel enthält die order_details-Abfrage drei Argumente:

  • status:"pending" – gibt nur offene Bestellungen zurück
  • limit:5 – beschneidet die Daten in fünf Ergebnisse
  • sort:["valid_from","DESC"] – sortiert die Daten absteigend nach dem valid_from-Wert
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Felder

Indem Sie Felder in Ihrer Abfrage einbeziehen oder weglassen, haben Sie die Möglichkeit, die Struktur der zurückgegebenen Daten zu manipulieren und anzupassen.

In diesem Beispiel dient die order_details_by_id Abfrage wird der Wiedergabe der Details eines einzelnen Zertifikatsauftrags. Die Abfrage enthält vier Felder:

  • id
  • common_name
  • purchase_dns_names
  • status

In der Antwort werden nur die angegebene Felder zurückgegeben.

Sie müssen mindestens ein Feld in der Abfrage angeben. Sind keine Felder enthalten, wird ein Syntaxfehler zurückgegeben.

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

Falls für das Feld keine Daten vorhanden sind, wird null zurückgegeben.

Anforderungen

Alle API-Anfragen an die Custom Reports-API bestehen aus drei Teilen: Methode, Endpunkt und Text. Das Format des Texts kann entweder application/graphql oder application/json sein,, je nachdem, welche Syntax für den Text verwendet wird.

Bei der Verwendung von Custom Reports API benötigen Sie einen DigiCert-Entwickler-API-Schlüssel im Header der Anfrage. Weitere Informationen finden Sie in Authentifizierung.

Methode

Anfragen bei der Custom Reports-API verwenden Standard-HTTP-POST-Methoden.

Endpunkte mit dem Label QUERY bezeichnen die Fähigkeit des Endpunkts, GraphQL-Syntax mithilfe eines GraphQL-Clients zu akzeptieren, auch wenn sie die HTTP-POST-Methode verwenden.

Text

Es gibt zwei Arten, einen Anfragetext zu konstruieren und zu senden:

  • Sie können GraphQL-Abfragesyntax verwenden und die Anfrage per GraphQL-Client senden.
  • Oder Sie konvertieren die GraphQL-Abfragesyntax in eine gültige JSON-Zeichenfolge und senden die Anfrage als JSON-Nutzlast.

Bei der Konvertierung der GraphQL-Abfragesyntax in eine gültige JSON-Zeichenfolge:

  • Entfernen Sie alle Zeilenwechsel in der Abfrage (Die Zeichenfolge muss eine einzelne Zeile sein).
  • Versehen Sie alle doppelten Anführungszeichen mit einem Escape-Zeichen (z. B. \").
  • Trennen Sie mehrere Felder durch Kommas (z. B. id,common_name,dns_names).
  • Verwenden Sie den query-Parameter in Ihrem JSON-Anfragetext und setzen Sie seinen Wert in die konvertierte Zeichenfolge.
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}}"
}

Tipps und Tricks

Benutzerdefinierte Abfragenamen

Einer Abfrage kann ein benutzerdefinierter Name zugewiesen werden, der im Antworttext gespiegelt wird.

In diesem Beispiel wird der order_details_by_id-Abfrage ein benutzerdefinierter Name new_customer_order zugewiesen. In der Antwort wird der benutzerdefinierte Name als der Name des JSON-Objekts gespiegelt, das die abgefragten Auftragsinformationen enthält.

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

Senden mehrerer Abfragen

Senden Sie mehrere Abfragen mit einer einzigen Anfrage unter Verwendung eines benutzerdefinierten Namens für jede Abfrage.

In diesem Beispiel werden zwei separate order_details Abfragen unter Verwendung benutzerdefinierter Namen mit einer einzigen Anfrage gesendet. In der Antwort werden die beiden Abfragen unter Verwendung der zugewiesenen benutzerdefinierten Namen zurückgegeben.

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

Antwortdaten umordnen

Die Reihenfolge in der Sie die Felder in einer Abfrage anordnen, bestimmt die Reihenfolge der Informationen in der Antwort. Das heißt, Sie können Sie die Felder in Ihrer Abfrage so arrangieren, dass die Antwort in der gewünschten Reihenfolge erfolgt.

In diesem Beispiel werden zwei order_details_by_id-Abfragen zur Anforderung derselben Informationen gesendet. Jede Abfrage verwendet jedoch eine andere Feldreihenfolge, was sich in der Antwort niederschlägt.

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