La API de informes personalizados de CertCentral le permite generar conjuntos de datos personalizables e integrales al aprovechar el poderoso lenguaje de consulta GraphQL.
La API de informes personalizados fusiona varios terminales REST en uno solo para que pueda definir mejor los tipos y campos en sus consultas a fin de que solo le devuelvan la información necesaria. Además, puede usarla para crear plantillas de consultas reutilizables para generar y programar informes.
GraphQL es un lenguaje de consulta API que usa grupos de consultas para devolver únicamente los datos exactos que necesita. Obtenga más información sobre GraphQL.
Si es nuevo en GraphQL, le recomendamos que se tome un minuto para leer la documentación de GraphQL a fin de aprender sobre el lenguaje de consulta.
La documentación de GraphQL abarca características y funciones que podrían no ser compatibles con la API de informes personalizados de CertCentral.
Utilice esta URL base al crear solicitudes API:
https://www.digicert.com/services/v2/reports
Las consultas se usan para generar grupos de datos a medida para sus necesidades concretas. Se accede a todas las consultas a través del terminal /query
.
La API de informes personalizados actualmente ofrece dos consultas: order_details y order_details_by_id.
Los argumentos se usan con las consultas para personalizar o manipular aún más la información que se devuelve.
En este ejemplo, la consulta order_details
incluye tres argumentos:
status:"pending"
: devuelve solo las solicitudes pendienteslimit:5
: clasifica la información en cinco resultadossort:["valid_from","DESC"]
: clasifica la información mediante el valor valid_from en orden descendenteorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])
Incluir u omitir campos en su consulta le dará la facultad para manipular y personalizar la estructura de la información que se devuelve.
En este ejemplo, se usa la consulta order_details_by_id
para que se devuelvan los detalles de una sola solicitud certificada. La solicitud incluye cuatro campos:
id
common_name
purchase_dns_names
status
En el cuerpo de la respuesta, solo se devuelven los campos determinados.
Debe incluir al menos un campo en la solicitud. Si no se incluyen campos, se devolverá un error de sintaxis.
{
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"
}
}
}
Si no existe información para el campo, se devuelve un valor de null
.
Todas las solicitudes API para la API de informes personalizados tienen tres partes: el método, el terminal y el cuerpo. El formato del cuerpo puede ser aplicación/graphql o aplicación/json,, lo que depende de la sintaxis que utilizó para construir el cuerpo.
Para consultar la API de informes personalizados, debe incluir la clave API del desarrollador de DigiCert en el encabezado de la solicitud. Vea Autenticación para obtener más información.
Las solicitudes a la API de informes personalizados utilizan los métodos de HTTP POST estándar.
Los terminales denominados CONSULTA denotan la capacidad de los terminales de aceptar la sintaxis GraphQL usando un cliente GraphQL; sin embargo, siguen usando el método HTTP POST.
Puede construir y enviar un cuerpo de pedido por medio de una de estas dos formas:
Cuando convierta la sintaxis de consulta GraphQL en una cadena JSON válida, haga lo siguiente:
\"
).id,common_name,dns_names
).query
en su cuerpo de pedido JSON y establezca su valor de acuerdo con la cadena convertida.{
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}}"
}
Se le puede asignar un nombre personalizado a una consulta; este se verá plasmado en el cuerpo de la respuesta.
En este ejemplo, se le asignó el nombre personalizado new_customer_order
a la consulta order_details_by_id
. En el cuerpo de la respuesta, el nombre personalizado se ve plasmado como el nombre del objeto JSON en que está la información del pedido consultado.
{
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"
}
}
}
Envíe varias consultas con un solo pedido usando nombres personalizados para cada consulta.
En este ejemplo, dos consultas order_details
separadas se envían en un solo pedido usando nombres personalizados para cada una. En el cuerpo de la respuesta, se devuelven las dos consultas usando los nombres personalizados asignados.
{
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"
}
]
}
}
La forma en la que ordena los campos en un cuestionario determina la forma en la que se ordena la información en el cuerpo de la respuesta. Esto significa que puede disponer los campos de su cuestionario para que el cuerpo de la respuesta quede en el orden que desee.
En este ejemplo, se envían dos cuestionarios order_details_by_id
por los que se pide la misma información. Sin embargo, cada cuestionario usa un orden de campos diferente, lo que se ve plasmado en el cuerpo de la respuesta.
{
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"
}
}
}