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 agregada, 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édio
• máx.
• mín.
• soma

Formato da URL

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

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

Nota:

As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres
tableName	Nome da tabela para a qual os registros serão recuperados. Tipo de dados: cadeia de caracteres

Tabela 2. Parâmetros de consulta

Nome	Descrição
pares de 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 passado, nenhuma operação agregada será executada. 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 passado, nenhuma operação agregada será executada. 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. 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. 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 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_tendo	Consulta adicional que permite filtrar os dados com base em uma operação agregada. O valor deste parâmetro deve seguir a sintaxe agregate^field^operator^value, como count^priority^>^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_order_by	Lista de valores pelos quais os resultados agrupados são ordenados. Você pode especificar uma ordem usando um campo ou um agregado. Por exemplo, se você especificar sysparm_order_by=AVG^state, grupos de resultados com valores de estado médios mais baixos serão retornados primeiro. Você também pode solicitar por COUNT 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_order_by=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(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/json ou 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 códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de 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.

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