API agregada

. Agregado A API fornece endpoints que permitem calcular estatísticas agregadas sobre dados de tabela e coluna existentes.

Para Agregado Solicitações de API, você deve ter acesso de leitura para todos os registros na tabela que consulta. Se uma ACL impedir que o usuário solicitante acesse qualquer registro na tabela, a solicitação retornará um erro 403 Proibido.

Agregado - OBTER /now/stats/

Recupera registros da tabela especificada e executa funções agregadas nos valores retornados.

Você pode especificar quais funções agregadas serão executadas usando sysparm_<aggregate>_fieldsparâmetro ou sysparm_having=<aggregate>^field^operator^valueparâmetro, substituindo <aggregate>para uma destas funções agregadas:

• média
• máx.
• mín
• soma

Formato de URL

URL com controle de versão: /api/now/

URL padrão: /api/now/stats/

Nota:

As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de serviço REST com script .

Parâmetros de solicitação compatíveis

Tabela 1. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessado. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: Cadeia de caracteres
tableName	Nome da tabela para a qual recuperar registros. Tipo de dados: Cadeia de caracteres

Tabela 2. Parâmetros de consulta

Nome	Descrição
pares nome-valor	Uma alternativa ao uso do sysparm_queryparâmetro. Você pode filtrar uma consulta usando pares de chave-valor em que a chave é o nome de um campo. Por exemplo, em vez de usar o parâmetro "sysparm_query , você pode usar verdadeiro . Você pode usar o valor de exibição quando o campo for um campo de escolha ou de tipo de referência, como &state: encerrado em vez de &estado: 7 . Para especificar vários pares de chave-valor, separe cada um com um e comercial, como "true&assigned_to""john.smith" . Tipo de dados: Cadeia de caracteres
sysparm_<aggregate>_fields	Lista de campos nos quais cada operação agregada será executada. Você pode especificar vários campos separando cada um com uma vírgula. Por exemplo, para obter os valores médios dos campos Duração e Prioridade, use sysparm_avg_fields: duração, prioridade . Nota: Especifique este parâmetro, o. sysparm_countou ambos para sua consulta retornar resultados significativos. Se nenhum parâmetro for aprovado, nenhuma operação agregada será realizada. Tipo de dados: Cadeia de caracteres
sysparm_count	Sinalizador que determina se o número de registros retornados pela consulta deve ser retornado. Nota: Especifique este parâmetro, o. sysparm_<aggregate>_fieldsou ambos para sua consulta retornar resultados significativos. Se nenhum parâmetro for aprovado, nenhuma operação agregada será realizada. Tipo de dados: Cadeia de caracteres
sysparm_display_value	Operação de recuperação de dados ao agrupar por campos de referência ou opção. Com base nesse valor, a consulta retorna o valor de exibição, o valor real no banco de dados ou ambos. Verdadeiro: Retorna valores de exibição para todos os campos. Falso: Retorna valores reais do banco de dados. Se um valor não for especificado, o padrão deste parâmetro será falso. Todos: Retorna valores reais e de exibição. Não há método preferencial para definir este parâmetro. No entanto, especificar o valor de exibição pode causar problemas de desempenho, pois eles não são lidos do banco de dados e podem fazer referência a outros campos e registros. Para obter mais informações sobre valores de exibição e valores reais, consulte Perguntas frequentes da API de tabela (KB0534905) . Tipo de dados: Cadeia de caracteres
sysparm_group_by	Campos pelos quais agrupar os dados retornados. Você pode especificar vários campos separando cada campo com uma vírgula, como sysparm_group_by_priority,state . Tipo de dados: Cadeia de caracteres
sysparm_having	Consulta adicional que permite filtrar os dados com base em uma operação agregada. O valor deste parâmetro deve seguir a sintaxe valor agregado do campo do operador , como contagem de prioridade> 3 para obter o número de registros nos resultados da consulta com uma prioridade maior que 3. Você pode especificar várias consultas separando cada uma com uma vírgula, como contagem de estado: 1, média de prioridade> 3 . Tipo de dados: Cadeia de caracteres
sysparm_order_by	Lista de valores pelos quais solicitar resultados agrupados. Você pode especificar um pedido usando um campo ou uma agregação. Por exemplo, se você especificar SYsparm_order_by: Estado médio grupos de resultados com valores médios de estado mais baixos são retornados primeiro. Você também pode ordenar por CONTAGEM para organizar grupos de registros pelo número de registros em cada grupo. Por padrão, quando você especifica uma ordem, os grupos são ordenados em ordem crescente. Usar DESC para classificar em ordem decrescente, como SYsparm_order_by . Tipo de dados: Cadeia de caracteres
sysparm_query	Uma consulta codificada. Por exemplo: (Sysparm_query_true)(sysparm_query_id_call_id_javascript:gs.getUserID() Tipo de dados: Cadeia de caracteres

Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)

Nome	Descrição
Nenhum(a)

Cabeçalhos

Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis .

Tabela 4. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml. Padrão: application/json

Tabela 5. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum(a)

Códigos de status

Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

Tabela 6. Códigos de status

Código do status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
401	Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
500	Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

Parâmetros do corpo da resposta (JSON ou XML)

Nome	Descrição
Depende da tabela especificada e dos parâmetros de solicitação especificados.

Solicitação de cURL de amostra

curl "https://instance.servicenow.com/api/now/stats/incident?sysparm_avg_fields=reassignment_count%2Cbusiness_stc&sysparm_group_by=assignment_group" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": [
    {
      "stats": {
        "avg": {
          "business_stc": "804162.7143",
          "reassignment_count": "1.0000"
        }
      },
      "groupby_fields": [
        {
          "value": "",
          "field": "assignment_group"
        }
      ]
    },
    {
      "stats": {
        "avg": {
          "business_stc": "2037371.0000",
          "reassignment_count": "1.5000"
        }
      },
      "groupby_fields": [
        {
          "value": "287ee6fea9fe198100ada7950d0b1b73",
          "field": "assignment_group"
        }
      ]
    },
    {
      "stats": {
        "avg": {
          "business_stc": "1821488.2857",
          "reassignment_count": "1.1111"
        }
      },
      "groupby_fields": [
        {
          "value": "8a5055c9c61122780043563ef53438e3",
          "field": "assignment_group"
        }
      ]
    },
    {
      "stats": {
        "avg": {
          "business_stc": "1730322.0000",
          "reassignment_count": "1.2500"
        }
      },
      "groupby_fields": [
        {
          "value": "287ebd7da9fe198100f92cc8d1d2154e",
          "field": "assignment_group"
        }
      ]
    },
    {
      "stats": {
        "avg": {
          "business_stc": "1564478.6250",
          "reassignment_count": "1.2500"
        }
      },
      "groupby_fields": [
        {
          "value": "d625dccec0a8016700a222a0f7900d06",
          "field": "assignment_group"
        }
      ]
    },
    {
      "stats": {
        "avg": {
          "business_stc": "1512202.2500",
          "reassignment_count": "1.1111"
        }
      },
      "groupby_fields": [
        {
          "value": "8a4dde73c6112278017a6a4baf547aa7",
          "field": "assignment_group"
        }
      ]
    }
  ]
}