API de informes personalizados

La API de informes personalizados de CertCentral le permite generar conjuntos de datos personalizables e integrales al aprovechar el poderoso lenguaje de consulta GraphQL.

¿Por qué utilizarla?

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.

¿Qué es GraphQL?

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.

URL base

Utilice esta URL base al crear solicitudes API:

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

Consultas

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.

Argumentos

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 pendientes
  • limit:5: clasifica la información en cinco resultados
  • sort:["valid_from","DESC"]: clasifica la información mediante el valor valid_from en orden descendente
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Campos

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.

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

Si no existe información para el campo, se devuelve un valor de null.

Solicitudes

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 utilizar 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.

Método

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.

Cuerpo

Puede construir y enviar un cuerpo de pedido por medio de una de estas dos formas:

  • Usar una sintaxis de consulta GraphQL y enviar el pedido por medio de un cliente GraphQL.
  • Convertir la sintaxis de consulta GraphQL en una cadena JSON válida y enviar el pedido por medio de una carga JSON.

Cuando convierta la sintaxis de consulta GraphQL en una cadena JSON válida, haga lo siguiente:

  • Elimine todas las líneas nuevas de la consulta (la cadena debe tener una sola línea).
  • Evite todas las comillas inglesas (por ejemplo, \").
  • Separe los diferentes campos con comas (por ejemplo, id,common_name,dns_names).
  • Use el parámetro query en su cuerpo de pedido JSON y establezca su valor de acuerdo con la cadena convertida.
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}}"
}

Consejos y trucos

Nombres de campos personalizados

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.

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

Enviar varias consultas

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.

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

Reordenar la información de la respuesta

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.

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