API настраиваемых отчетов CertCentral позволяют вам генерировать настраиваемые и универсальные комплекты данных, используя в максимальной степени мощный язык запросов GraphQL.
API пользовательских отчетов объединяет многочисленные конечные точки REST в единую конечную точку, что позволяет вам лучше определять типы и поля в своих запросах, чтобы получать в ответ на них только нужную информацию. Кроме того, вы можете использовать его для создания многоразовых шаблонов запросов для генерирования и планирования отчетов.
GraphQL — это язык запросов API, использующий наборы запросов, которые позволяет получать только те данные, которые вам необходимы, и больше ничего. Узнать больше о GraphQL.
Если вы ничего не знаете о GraphQL, мы рекомендуем потратить немного времени на чтение документации по GraphQL, чтобы ознакомиться с данным языком запросов.
Документация по GraphQL содержит описание функций и функциональных возможностей, которые могут не поддерживаться API настраиваемых отчетов в CertCentral.
Используйте данный базовый URL-адрес при создании запросов API:
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 в порядке убыванияorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])
Включая пропускаемые поля в вашем запросе, дает вам возможность управления структурой полученных данных и их индивидуализации.
В этом примере запрос order_details_by_id
используется для получения подробной информации о запросе одиночного сертификата. Запрос включает четыре поля:
id
common_name
purchase_dns_names
status
В теле запроса используются только заданные поля.
Вам необходимо включить как минимум одно поле в этот запрос. Если включенных полей нет, отображается синтаксическая ошибка.
{
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 пользовательских отчетов состоят из трех частей: метод, конечная точка и тело. Форматом тела может быть application/graphql или application/json, в зависимости от синтаксиса, используемого для конструирования тела.
Для использования API настраиваемого отчета вы должны включить ключ API из Cert Developer API в заголовок запроса. См. раздел Аутентификация, в котором содержатся дополнительные сведения.
Запросы к API пользовательских отчетов используют стандартные методы HTTP POST.
Конечные точки, промаркированные QUERY (ЗАПРОСЫ), обозначают способность принимать синтаксис GraphQL с помощью клиента GraphQL; в любом случае, они все равно используют метод HTTP POST.
Вы можете конструировать и отправлять тело запроса одни из двух способов:
При преобразовании синтаксиса запросов 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"
}
}
}
Отправить несколько запросов с использованием имени для каждого запроса.
В этом примере два отдельных запроса order_details
отправлены в одиночном запросе с пользовательским именем для каждого. В теле ответа приведены два запроса с использованием двух присвоенных пользовательских имен.
{
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"
}
]
}
}
Группировка полей в запросе определяет группировку информации в теле ответа. Это означает, что вы можете компоновать поля своих запросов таким образом, чтобы тело ответа было организовано в нужном порядке.
В этом примере два отправленных запроса 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"
}
}
}