API d’agrégat

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

Cette API utilise les appels GlideAggregate et n’honore les requêtes en lecture seule que si l’accès en lecture est défini pour la table appelée en fonction de la propriété du rôle.

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 :

• moy.
• 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 scriptées, des informations supplémentaires sur la version se trouvent dans 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 autre que la plus récente. 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 dont 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égat. 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 sysparm_count paramètre ou les deux pour que votre requête renvoie des résultats significatifs. Si aucun des deux 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 sysparm_<aggregate>_fields paramètre ou les deux pour que votre requête renvoie des résultats significatifs. Si aucun des deux paramètres n’est transmis, aucune opération d’agrégat n’est effectuée. Type de données : chaîne
sysparm_display_value	Récupération de données lors du regroupement par champ 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 pour tous les champs. faux : 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 les valeurs réelles et d’affichage. Il n’existe aucune méthode privilégiée pour définir ce paramètre. Toutefois, la spécification de la valeur Display (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, consultez la FAQ sur l’API de table (KB0534905). Type de données : chaîne
sysparm_group_by	Champs selon lesquels regrouper les données renvoyées. Vous pouvez spécifier plusieurs champs en les séparant par une virgule, par exemple sysparm_group_by=priorité,état. Type de données : chaîne
sysparm_having	Requête supplémentaire vous permettant 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, 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 les séparant par une virgule, telles 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 les valeurs d’état moyennes inférieures sont renvoyés en premier. Vous pouvez également trier par NOMBRE 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 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 uniquement à cette action HTTP 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
Néant

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é traitée avec succès.
401	Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises.
403	Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié.
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 spécifiée 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"
        }
      ]
    }
  ]
}