API d'agrégat

L’API d’agrégation fournit des points de terminaison qui vous permettent de calculer des statistiques agrégées sur les données de table et de colonne existantes.

Pour les demandes d’API d’agrégat, vous devez disposer d’un accès en lecture pour tous les enregistrements de la table que vous interrogez. Si une ACL empêche l’utilisateur demandeur d’accéder à un enregistrement de la table, la demande renvoie une erreur 403 Forbidden.

Agrégat : GET /now/stats/{tableName}

Récupère les enregistrements de la table spécifiée et exécute des fonctions d’agrégation sur les valeurs renvoyées.

Vous pouvez spécifier les fonctions d’agrégation à exécuter à l’aide du paramètre ou sysparm_having=<aggregate>^field^operator^value du sysparm_<aggregate>_fields paramètre, en remplaçant <aggregate> l’une de ces fonctions d’agrégat :

• Avg
• max.
• min.
• somme

Format d'URL

URL versionnée : /api/now/{api_version}/stats/{tableName}

URL par défaut : /api/now/stats/{tableName}

Paramètres de demande pris en charge

Tableau 1. Paramètres de chemin d'accès

Nom	Description
api_version	Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne
tableName	Nom de la table pour laquelle récupérer les enregistrements. Type de données : chaîne

Tableau 2. Paramètres de requête

Nom	Description
Paires nom-valeur	Alternative à l’utilisation du sysparm_query paramètre. Vous pouvez filtrer une requête à l’aide de paires clé-valeur où la clé est le nom d’un champ. Par exemple, au lieu d’utiliser le paramètre &sysparm_query=active=true, vous pouvez utiliser &active=true. Vous pouvez utiliser la valeur d’affichage lorsque le champ est un champ de type choix ou référence, par exemple &state=closed au lieu de &state=7. Pour spécifier plusieurs paires clé-valeur, séparez-les par une esperluette, par exemple &active=true&assigned_to=john.smith. Type de données : chaîne
sysparm_<agrégat>_fields	Liste des champs sur lesquels effectuer chaque opération d’agrégat. Vous pouvez spécifier plusieurs champs en les séparant par des virgules. Par exemple, pour obtenir les valeurs moyennes des champs de durée et de priorité, utilisez sysparm_avg_fields=duration,priority. Remarque : Spécifiez ce paramètre, le sysparm_count paramètre ou les deux pour que votre requête renvoie des résultats significatifs. Si aucun paramètre n’est transmis, aucune opération d’agrégation n’est effectuée. Type de données : chaîne
sysparm_count	Marqueur qui détermine si le nombre d’enregistrements renvoyés par la requête doit être renvoyé. Remarque : Spécifiez ce paramètre, le sysparm_<aggregate>_fields paramètre ou les deux pour que votre requête renvoie des résultats significatifs. Si aucun paramètre n’est transmis, aucune opération d’agrégation n’est effectuée. Type de données : chaîne
sysparm_display_value	Opération de récupération de données lors d’un regroupement par champs de référence ou de choix. Sur la base de cette valeur, la requête renvoie soit la valeur d’affichage, soit la valeur réelle dans la base de données, soit les deux. true : renvoie les valeurs d’affichage pour tous les champs. false : renvoie les valeurs réelles de la base de données. Si aucune valeur n’est spécifiée, ce paramètre est défini par défaut sur faux. all : renvoie à la fois les valeurs réelles et les valeurs d’affichage. Il n'existe aucune méthode recommandée pour définir ce paramètre. Toutefois, spécifier la valeur d’affichage peut entraîner des problèmes de performances car elles ne sont pas lues à partir de la base de données et peuvent faire référence à d’autres champs et enregistrements. Pour plus d'informations sur les valeurs d'affichage et les valeurs réelles, voir FAQ sur l'API de table (KB0534905). Type de données : chaîne
sysparm_group_by	Champs par lesquels regrouper les données renvoyées. Vous pouvez spécifier plusieurs champs en séparant chaque champ par une virgule, par exemple sysparm_group_by=priority,state. Type de données : chaîne
sysparm_having	Requête supplémentaire qui vous permet de filtrer les données en fonction d’une opération d’agrégat. La valeur de ce paramètre doit suivre la syntaxe aggregate^field^operator^value, par exemple count^priority^>^3 pour obtenir le nombre d’enregistrements dans les résultats de la requête avec une priorité supérieure à 3. Vous pouvez spécifier plusieurs requêtes en les séparant par une virgule, par exemple :count^state^=^1,avg^priority^>^3. Type de données : chaîne
sysparm_orderby	Liste de valeurs en fonction desquelles trier les résultats groupés. Vous pouvez spécifier un ordre à l’aide d’un champ ou d’un agrégat. Par exemple, si vous spécifiez sysparm_orderby=AVG^state, les groupes de résultats avec des valeurs d’état moyennes inférieures sont renvoyés en premier. Vous pouvez également trier par COUNT pour organiser les groupes d’enregistrements en fonction du nombre d’enregistrements dans chaque groupe. Lorsque vous spécifiez un ordre, les groupes sont classés par défaut par ordre croissant. Utilisez ^DESC pour effectuer un tri par ordre décroissant, par exemple sysparm_orderby=state^DESC. Type de données : chaîne
sysparm_query	Requête codée. Par exemple : (sysparm_query=active=true)(sysparm_query=caller_id=javascript :gs.getUserID()^active=true) Type de données : chaîne

Tableau 3. Paramètres de corps de demande (XML ou JSON)

Nom	Description
Néant

En-têtes

Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

Tableau 4. En-têtes de demandes

En-tête	Description
Accepter	Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json

Tableau 5. En-têtes de réponses

En-tête	Description
Aucun

Codes d'état

Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir une liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

Tableau 6. Codes d'état

Code d'état	Description
200	Réussi. La demande a été correctement traitée.
401	Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
500	Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

Paramètres de corps de réponse (JSON ou XML)

Nom	Description
Dépend de la table et des paramètres de demande spécifiés.

Exemple de demande 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"
        }
      ]
    }
  ]
}