API пользовательских отчетов

API настраиваемых отчетов CertCentral позволяют вам генерировать настраиваемые и универсальные комплекты данных, используя в максимальной степени мощный язык запросов GraphQL.

Почему необходимо использовать данное дополнение?

API пользовательских отчетов объединяет многочисленные конечные точки REST в единую конечную точку, что позволяет вам лучше определять типы и поля в своих запросах, чтобы получать в ответ на них только нужную информацию. Кроме того, вы можете использовать его для создания многоразовых шаблонов запросов для генерирования и планирования отчетов.

Что такое GraphQL?

GraphQL — это язык запросов API, использующий наборы запросов, которые позволяет получать только те данные, которые вам необходимы, и больше ничего. Узнать больше о GraphQL.

Если вы ничего не знаете о GraphQL, мы рекомендуем потратить немного времени на чтение документации по GraphQL, чтобы ознакомиться с данным языком запросов.

Документация по GraphQL содержит описание функций и функциональных возможностей, которые могут не поддерживаться API настраиваемых отчетов в CertCentral.

Базовый URL-адрес

Используйте данный базовый URL-адрес при создании запросов API:

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

Запросы

Запросы используются для генерирования наборов данных, скомпонованных в соответствии с вашими конкретными потребностями. Доступ ко всем запросам осуществляется с помощью конечной точки /query.

API пользовательских отчетов предлагает два запроса: order_details и order_details_by_id.

Аргументы

Аргументы используются с запросами для дальнейшей индивидуализации удаленно расположенных данных или для обращения с ними.

В этом примере запрос order_details включает три аргумента:

  • status:"pending" — показывает только находящиеся на рассмотрении заказы
  • limit:5 — сокращает количество результатов до пяти
  • sort:["valid_from","DESC"] — сортирует данные с помощью значения valid_from в порядке убывания
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Поля

Включая пропускаемые поля в вашем запросе, дает вам возможность управления структурой полученных данных и их индивидуализации.

В этом примере запрос order_details_by_id используется для получения подробной информации о запросе одиночного сертификата. Запрос включает четыре поля:

  • id
  • common_name
  • purchase_dns_names
  • status

В теле запроса используются только заданные поля.

Вам необходимо включить как минимум одно поле в этот запрос. Если включенных полей нет, отображается синтаксическая ошибка.

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 пользовательских отчетов состоят из трех частей: метод, конечная точка и тело. Форматом тела может быть application/graphql или application/json, в зависимости от синтаксиса, используемого для конструирования тела.

Для использования API настраиваемого отчета вы должны включить ключ API из Cert Developer API в заголовок запроса. См. раздел Аутентификация, в котором содержатся дополнительные сведения.

Метод

Запросы к API пользовательских отчетов используют стандартные методы HTTP POST.

Конечные точки, промаркированные QUERY (ЗАПРОСЫ), обозначают способность принимать синтаксис GraphQL с помощью клиента GraphQL; в любом случае, они все равно используют метод HTTP POST.

Тело

Вы можете конструировать и отправлять тело запроса одни из двух способов:

  • С помощью синтаксиса запросов GraphQL и отправка запроса через клиент GraphQL.
  • Преобразование синтаксиса запроса GraphQL в действительную строку JSON и отправка запроса через полезные данные JSON.

При преобразовании синтаксиса запросов GraphQL в действительную строку JSON:

  • Удалите все новые строки в запросе (строка должны быть одиночной линией).
  • Исключение всех двойных кавычек (например, \").
  • Разделяйте несколько полей с помощью запятых (например, 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"
        }
    }
}

Отправить несколько запросов

Отправить несколько запросов с использованием имени для каждого запроса.

В этом примере два отдельных запроса order_details отправлены в одиночном запросе с пользовательским именем для каждого. В теле ответа приведены два запроса с использованием двух присвоенных пользовательских имен.

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

Перегруппировать данные ответа

Группировка полей в запросе определяет группировку информации в теле ответа. Это означает, что вы можете компоновать поля своих запросов таким образом, чтобы тело ответа было организовано в нужном порядке.

В этом примере два отправленных запроса 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"
        }
    }
}