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.
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.
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.
Use esta URL base ao construir solicitações de API:
https://www.digicert.com/services/v2/reportsConsultas 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 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 pendenteslimit:5 – Trunca dados até cinco resultadossort:["valid_from","DESC"] – Classifica dados usando o valor valid_from em ordem decrescenteorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])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:
idcommon_namepurchase_dns_namesstatusNo 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.
{
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"
}
}
}Se nenhum dado existir para o campo, um valor null é retornado.
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 consultar 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.
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.
É possível construir e enviar um corpo de solicitação em uma de duas formas:
Ao converter a sinxtade de consulta GraphQL em uma string JSON válida:
\").id,common_name,dns_names).query no seu corpo da solicitação JSON e defina seu valor para a string 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}}"
}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.
{
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"
}
}
}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.
{
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"
}
]
}
}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.
{
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"
}
}
}