CertCentral のカスタムレポート API により、強力な GraphQL クエリー言語を利用して、カスタマイズ可能な総合データセットを生成することができます。
カスタムレポート API では、複数の REST エンドポイントを1に統合することで、お客様が必要な情報のみを戻すように、クエリーでタイプとフィールドをより適切に定義することが可能になります。また、この利用により、再利用可能なクエリーテンプレートを作成し、レポートを生成および予約することができます。
GraphQL は、クエリーセットを利用して、必要とするデータのみを返す API クエリー言語で、それ以外は何もありません。GraphQL についてもっとみる.
GraphQL について全く新規ユーザーの場合は、クエリー言語について知るため、少し時間を取ってGraphQL ドキュメントを読むことをお勧めします。
GraphQL ドキュメントでは、CertCentral のカスタムレポート API エンドポイントがサポートしない可能性がある特長や機能について説明しています。
API 要求を行うときは、このベース URL を使用します。
https://www.digicert.com/services/v2/reportsクエリーは、個別ニーズにあわせたデータセットを生成するのに使用します。すべてのクエリーは、/query エンドポイントを使用してアクセスします。
カスタムレポート API には、現在、以下の2つのクエリーがあります。order_details と order_details_by_id.
拡張は、返されたデータをさらにカスタマイズまたは操作するクエリーとあわせて使用します。
この例では、order_details クエリーには以下の3つの拡張が含まれます。
status:"pending" – 保留中のオーダーのみを返すlimit:5 – データを5つの結果に区切るsort:["valid_from","DESC"] – valid_from 値を降順で使用してデータを分類するorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])クエリーのフィールを入れる、または省略すると、返されるデータ構造を操作およびカスタマイズする権限が付与されます。
この例では、order_details_by_id クエリーは、1つの証明書オーダーの詳細を返すのに使用します。要求には、以下のフィールドが含まれます。
idcommon_namepurchase_dns_namesstatus応答本文では、指定フィールドのみが返されます。
要求には少なくとも1つのフィールドを含める必要があります。フィールドを何も入れない場合、シンタックスエラーが返されます。
{
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"
}
}
}当該のフィールドについてデータが存在しない場合は、null エラーが返されます。
カスタムレポート API へのすべての API 要求は、方法、エンドポイントおよび本体の3部で構成されています。本体の形式は、本体を構成するのに使用するシンタックスによって、application/graphql または application/json,のいずれかにすることができます。
カスタムㇾポート API を使用するには、要求ヘッダに DigiCert 開発者 API キーを含めなければなりません。詳細は、「認証」を参照してください。
カスタムレポート API への要求は標準 HTTP POST 方法を使用しています。
QUERY ラベルの付いたエンドポイントは、GraphQL クライアントを使用して GraphQL シンタックスを承認するエンドポイントの機能を示していますが、そこでも HTTP POST 方法を使用しています。
要求本文は以下の2つの方法うち１ずれかで構成および送信できます。
GraphQL クエリーシンタックスを有効な JSON 文字列に変換する場合:
\")。id,common_name,dns_names).query パラメーターを JSON 要求本体に使用し、その値を変換した文字列に設定します。{
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}}"
}クエリーには、応答本体に反映されるカスタム名を割り当てることができます。
この例では、new_customer_order のカスタム名が order_details_by_id クエリーに割り当てられています。応答本体では、カスタム名は照会されたオーダー情報を含む JSON オブジェクトとして反映されます。
{
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"
}
}
}各クエリーについてカスタム名を使用して、1つの要求で複数のクエリーを送信します。
この例では、order_details クエリーを、それぞれにカスタム名を使用した1つの要求で送信します。応答本体では、割り当てられたカスタム名を使用して、2つのクエリーが返されます。
{
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"
}
]
}
}クエリーでのフィールドのオーダーの仕方により、応答本体で情報がどのようにオーダーされるかが決まります。すなわち、応答本体が希望のオーダーとなるように、クエリーフィールドを調整することができます。
この例では、2つの order_details_by_id クエリーを送信し、同じ情報を要求します。ただし、各クエリーは、応答本体に反映される別のフィールドオーダーを使用しています。
{
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"
}
}
}