カスタムレポート API

CertCentral のカスタムレポート API により、強力な GraphQL クエリー言語を利用して、カスタマイズ可能な総合データセットを生成することができます。

その使用理由な何ですか?

カスタムレポート API では、複数の REST エンドポイントを1に統合することで、お客様が必要な情報のみを戻すように、クエリーでタイプとフィールドをより適切に定義することが可能になります。また、この利用により、再利用可能なクエリーテンプレートを作成し、レポートを生成および予約することができます。

GraphQL とは、何ですか?

GraphQL は、クエリーセットを利用して、必要とするデータのみを返す API クエリー言語で、それ以外は何もありません。GraphQL についてもっとみる.

GraphQL について全く新規ユーザーの場合は、クエリー言語について知るため、少し時間を取ってGraphQL ドキュメントを読むことをお勧めします。

GraphQL ドキュメントでは、CertCentral のカスタムレポート API エンドポイントがサポートしない可能性がある特長や機能について説明しています。

ベース URL

API 申請を行うときは、このベース URL を使用します。

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

クエリー

クエリーは、個別ニーズにあわせたデータセットを生成するのに使用します。すべてのクエリーは、/query エンドポイントを使用してアクセスします。

カスタムレポート API には、現在、以下の2つのクエリーがあります。order_detailsorder_details_by_id.

引数

拡張は、返されたデータをさらにカスタマイズまたは操作するクエリーとあわせて使用します。

この例では、order_details クエリーには以下の3つの拡張が含まれます。

  • status:"pending" – 保留中のオーダーのみを返す
  • limit:5 – データを5つの結果に区切る
  • sort:["valid_from","DESC"]valid_from 値を降順で使用してデータを分類する
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

フィールド

クエリーのフィールを入れる、または省略すると、返されるデータ構造を操作およびカスタマイズする権限が付与されます。

この例では、order_details_by_id クエリーは、1つの証明書オーダーの詳細を返すのに使用します。申請には、以下のフィールドが含まれます。

  • id
  • common_name
  • purchase_dns_names
  • status

応答団体では、指定フィールドのみが返されます。

申請には少なくとも1つのフィールドを含める必要があります。フィールドを何も入れない場合、シンタックスエラーが返されます。

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

当該のフィールドについてデータが存在しない場合は、null エラーが返されます。

証明書申請の一覧

カスタムレポート API へのすべての API 申請は、方法、エンドポイントおよび本体の3部で構成されています。本体の形式は、本体を構成するのに使用するシンタックスによって、application/graphql または application/json,のいずれかにすることができます。

カスタムㇾポート API を使用するには、申請ヘッダに DigiCert 開発者 API キーを含めなければなりません。詳細は、「認証」を参照してください。

方法

カスタムレポート API への申請は標準 HTTP POST 方法を使用しています。

QUERY ラベルの付いたエンドポイントは、GraphQL クライアントを使用して GraphQL シンタックスを承認するエンドポイントの機能を示していますが、そこでも HTTP POST 方法を使用しています。

本体

申請本文は以下の2つの方法うち1ずれかで構成および送信できます。

  • GraphQL クエリーシンタックスの利用および GraphQL クライアントを経由した申請の送信。
  • GraphQL クエリーの有効な JSON 文字列への変換、および JSON ペイロードを経由した申請の送信。

GraphQL クエリーシンタックスを有効な JSON 文字列に変換する場合:

  • クエリーのすべての新しいラインを削除します(文字列は1つのラインでなければなりません)。
  • すべての二重見積もりを回避します (例. \")。
  • 複数のフィールドをコンマで区切ります (例. id,common_name,dns_names).
  • query パラメーターを JSON 申請本体に使用し、その値を変換した文字列に設定します。
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}}"
}

ヒントと注意点

カスタムクエリー名

クエリーには、応答本体に反映されるカスタム名を割り当てることができます。

この例では、new_customer_order のカスタム名が order_details_by_id クエリーに割り当てられています。応答本体では、カスタム名は照会されたオーダー情報を含む JSON オブジェクトとして反映されます。

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

複数のクエリーを送信する

各クエリーについてカスタム名を使用して、1つの申請で複数のクエリーを送信します。

この例では、order_details クエリーを、それぞれにカスタム名を使用した1つの申請で送信します。応答本体では、割り当てられたカスタム名を使用して、2つのクエリーが返されます。

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

応答データを再オーダーする

クエリーでのフィールドのオーダーの仕方により、応答本体で情報がどのようにオーダーされるかが決まります。すなわち、応答本体が希望のオーダーとなるように、クエリーフィールドを調整することができます。

この例では、2つの order_details_by_id クエリーを送信し、同じ情報を申請します。ただし、各クエリーは、応答本体に反映される別のフィールドオーダーを使用しています。

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