API de relatórios personalizados

A API de relatórios personalizados da CertCentral permite que você gere conjuntos de dados personalizáveis e compreensivos ao alavancar a poderosa linguagem de consulta GraphQL.

Por que usá-la?

A API de Relatórios Personalizados consolida diversos pontos de extremidade REST em um único, habilitando a melhor definição dos tipos e campos nas suas consultas para que possam retornar apenas as informações necessárias. Além disso, é possível usá-la para criar modelos de consultas reutilizáveis para gerar e agendar relatórios.

O que é GraphQL?

GraphQL é uma linguagem de consulta de API que usa conjuntos de consultas para retornar apenas os dados necessários e nada mais. Saiba mais sobre GraphQL.

Se você for novo ao GraphQL, recomendamos que você reserve um minuto para ler a documentação do GraphQL para aprender sobre a linguagem de consulta.

A documentação do GraphQL abrange recursos e funcionalidade que poderiam não ser suportados pela API de relatórios personalizados da CertCentral.

URL Base

Use esta URL base ao construir solicitações de API:

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

Consultas

Consultas são usadas para gerar conjuntos de dados que são personalizados de acordo com as suas necessidades específicas. Todas as consultas são acessadas usando o ponto de extremidade /query.

A API de relatórios personalizados atualmente oferece duas consultas: order_details e order_details_by_id.

Argumentos

Argumentos são usados com consultas para personalizar ou manipular ainda mais os dados retornados.

Neste exemplo, a consulta order_details inclui três argumentos:

  • status:"pending" – Retorna apenas pedidos pendentes
  • limit:5 – Trunca dados até cinco resultados
  • sort:["valid_from","DESC"] – Classifica dados usando o valor valid_from em ordem decrescente
graphql
order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Campos

Incluir ou omitir campos na sua consulta fornece o poder de manipular e personalizar a estrutura dos dados retornados.

Neste exemplo, a consulta order_details_by_id é usada para retornar os detalhes de um único pedido de certificado. A solicitação inclui quatro campos:

  • id
  • common_name
  • purchase_dns_names
  • status

No corpo da resposta, apenas os campos especificados são retornados.

É necessário incluir pelo menos um campo na solicitação. Se nenhum campo for incluído, um erro de sintaxe é retornado.

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

Se nenhum dado existir para o campo, um valor null é retornado.

Solicitações

Todas as solicitações de API para a API Relatórios personalizados possuem três partes: método, ponto de extremidade e corpo. O formato do corpo pode ser application/graphql ou application/json, dependendo da sintaxe usada para construir o corpo.

Para usar a API de relatórios personalizados, é necessário incluir uma chave de API do desenvolvedor da DigiCert no cabeçalho da solicitação. Veja Autenticação para mais informações.

Método

Solicitações para a API de Relatórios personalizados usam os métodos padrão HTTP POST.

Pontos de extremidade habilitados com QUERY denotam a capacidade do ponto de extremidade em aceitar a sintaxe GraphQL usando um cliente GraphQL; contudo, eles ainda usam o método HTTP POST.

Corpo

É possível construir e enviar um corpo de solicitação em uma de duas formas:

  • Usando a sintaxe de consulta GraphQL e enviando a solicitação através de um cliente GraphQL.
  • Convertendo a sintaxe de consulta GraphQL em uma string JSON válida e enviando a solicitação através de uma carga JSON.

Ao converter a sinxtade de consulta GraphQL em uma string JSON válida:

  • Remova todas as novas linhas na consulta (a string deve ser uma única linha).
  • Escape todas as aspas duplas (por ex., \").
  • Separe múltiplos campos com vírgulas (por ex., id,common_name,dns_names).
  • Use o parâmetro query no seu corpo da solicitação JSON e defina seu valor para a string 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}}"
}

Dicas e truques

Nomes personalizados da consulta

Uma consulta pode receber um nome personalizado que é refletido no corpo de resposta.

Neste exemplo, um nome personalizado de new_customer_order está atribuído à consulta order_details_by_id. No corpo da resposta, o nome personalizado é refletido como o nome do objeto JSON contendo informações do pedido em consulta.

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 múltiplas consultas

Envie múltiplas consultas com uma única solicitação usando nomes personalizados para cada consulta.

Neste exemplo, duas consultas separadas order_details são enviadas em uma única solicitação usando nomes personalizados para cada uma. No corpo da resposta, duas consultas são retornadas usando os nomes personalizados atribuídos.

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 dados da resposta

Como você ordena os campos em um campo determina como as informações são ordenadas no corpo da resposta. Isso significa que você pode organizar os seus campos de consulta para que o corpo de resposta esteja na ordem desejada.

Neste exemplo, duas consultas order_details_by_id são enviadas solicitando as mesmas informações. Contudo, cada consulta usa uma ordem de campo diferente, o que está refletido no corpo da resposta.

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