API agregada

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

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

Agregado - GET /now/stats/{tableName}

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

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

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

Formato de URL

URL com controle de versões: /api/now/{api_version}/stats/{tableName}

URL padrão: /api/now/stats/{tableName}

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 acessada. 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 serão recuperados registros. Tipo de dados: cadeia de caracteres

Tabela 2. Parâmetros de consulta

Nome	Descrição
pares nome-valor	Uma alternativa ao uso do parâmetro sysparm_query. 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=active=true, você pode usar &active=true. Você pode usar o valor de exibição quando o campo for do tipo opção ou referência, como &state=closed em vez de &state=7. Para especificar vários pares de chave-valor, separe cada um com um e comercial, como &active=true&assigned_to=john.smith. Tipo de dados: cadeia de caracteres
sysparm_<aggregate> _campos	Lista de campos nos quais cada operação agregada será executada. Você pode especificar vários campos separando cada um deles com uma vírgula. Por exemplo, para obter os valores médios dos campos de duração e prioridade, use sysparm_avg_fields=duration,priority. Nota: Especifique este parâmetro, o parâmetro sysparm_count ou ambos para que sua consulta retorne 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 parâmetro sysparm_<aggregate>_fields ou ambos para que sua consulta retorne 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 referência ou campos de opção. Com base nesse valor, a consulta retorna o valor de exibição, o valor real no banco de dados ou ambos. true: retorna valores de exibição para todos os campos. false: retorna valores reais do banco de dados. Se um valor não for especificado, este parâmetro será padronizado como falso. all: retorna valores reais e de exibição. Não há nenhum 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 da tabela (KB0534905). Tipo de dados: cadeia de caracteres
sysparm_group_by	Campos pelos quais os dados retornados serão agrupados. 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 agregada^campo^operador^valor, como contagem^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 um com uma vírgula, comocount^state^=^1,avg^priority^>^3. Tipo de dados: cadeia de caracteres
sysparm_orderby	Lista de valores pelos quais ordenar resultados agrupados. Você pode especificar uma ordem usando um campo ou um agregado. Por exemplo, se você especificar sysparm_orderby=AVG^state, grupos de resultados com valores de estado médios mais baixos serão retornados primeiro. Você também pode solicitar por CONTAGEM para organizar grupos de registros pelo número de registros em cada grupo. Quando você especifica uma ordem, os grupos são ordenados em ordem crescente por padrão. Use ^DESC para classificar em ordem decrescente, como sysparm_orderby=state^DESC. Tipo de dados: cadeia de caracteres
sysparm_query	Uma consulta codificada. Por exemplo: (sysparm_query=active=true)(sysparm_query=caller_id=javascript:gs.getUserID()^active=true) Tipo de dados: cadeia de caracteres

Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)

Nome	Descrição
Nenhum

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/json ou application/xml. Padrão: application/json

Tabela 5. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

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

Tabela 6. Códigos de status

Código de 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.

Exemplo de solicitação cURL

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