사용자 지정 보고서 API

CertCentral의 사용자 지정 보고서 API는 강력한 GraphQL 쿼리 언어를 이용하여 사용자 지정 가능하고 종합적인 데이터 집합을 생성할 수 있습니다.

왜 사용하나요?

사용자 지정 보고서 API는 여러 REST 엔드포인트를 한 개로 통합하여 쿼리의 유형 및 피드를 더 잘 정의할 수 있게 합니다. 또한 보고서 생성 및 일정 지정에 사용 가능한 쿼리 템플릿을 만드는 데 사용할 수 있습니다.

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 쿼리는 단일 인증서 주문의 상세 정보를 반환하는 데 사용합니다. 요청은 4개 필드를 포함합니다.

  • 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 문자열로 변환할 때는 다음을 따릅니다.

  • 쿼리에서 모든 줄 바꿈을 제거합니다.(문자열은 한 줄이어야 합니다.)
  • 모든 큰 따옴표(예, \")를 이스케이프합니다.
  • 여러 필드를 쉼표(예, id,common_name,dns_names)로 구분합니다.
  • JSON 요청 본문에서 query 매개 변수를 사용하고 그 값을 변환 문자열로 설정합니다.
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"
        }
    }
}

여러 쿼리 보내기

각 쿼리에 대해 사용자 지정 이름을 사용하여 한 개의 요청에서 여러 쿼리를 보냅니다.

이 예제에서 2개의 별도의 order_details 쿼리가 각 쿼리에 대해 사용자 지정 이름을 사용하여 한 개의 요청으로 보냅니다. 응답 본문에서 할당된 사용자 지정 이름을 사용하여 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"
        }
    }
}