API d'agrégat

L’API d’agrégat 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 avoir 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 Interditden.

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

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

Vous pouvez spécifier les fonctions d’agrégat à 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}

Remarque :

Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST basées sur un script, des informations de version supplémentaires sont disponibles sur le formulaire Service REST scripté.

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. Par 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	Une 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, tel que &state=closed au lieu de &state=7. Pour spécifier plusieurs paires clé-valeur, séparez-les chacune par une esperluette, telle que &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égation. Vous pouvez spécifier plusieurs champs en les séparant par une virgule. 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 paramètre ou les sysparm_count deux pour que votre requête renvoie des résultats significatifs. Si aucun des paramètres n’est transmis, aucune opération d’agrégat n’est effectuée. Type de données : chaîne
sysparm_count	Marqueur qui détermine s’il faut renvoyer le nombre d’enregistrements renvoyés par la requête. Remarque : Spécifiez ce paramètre, le paramètre ou les sysparm_<aggregate>_fields deux pour que votre requête renvoie des résultats significatifs. Si aucun des paramètres n’est transmis, aucune opération d’agrégat n’est effectuée. Type de données : chaîne
sysparm_display_value	Opération de récupération de données lors du 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. vrai : renvoie les valeurs d’affichage de 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, la spécification de 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 renvoyer vers 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 sur lesquels regrouper les données renvoyées. Vous pouvez spécifier plusieurs champs en les séparant par une virgule, telle que 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égation. La valeur de ce paramètre doit suivre la syntaxe aggregate^field^operator^value, telle que 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 séparant chacune par une virgule, telle que count^state^=^1,avg^priority^>^3. Type de données : chaîne
sysparm_order_by	Liste de valeurs selon lesquelles 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_order_by=AVG^state, les groupes de résultats avec des valeurs d’état moyennes inférieures sont renvoyés en premier. Vous pouvez également organiser les groupes d’enregistrements par NOMBRE en fonction du nombre d’enregistrements de chaque groupe. Lorsque vous spécifiez un ordre, les groupes sont classés par ordre croissant par défaut. Utilisez ^DESC pour effectuer un tri par ordre décroissant, par exemple sysparm_order_by=state^DESC. Type de données : chaîne
sysparm_query	Une 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 la 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 la 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 du corps de la 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"
        }
      ]
    }
  ]
}