Aggregieren-API

Die Aggregate API bietet Endpunkte, mit denen Sie aggregierte Statistiken für vorhandene Tabellen- und Spaltendaten berechnen können.

Für Aggregate API-Anforderungen benötigen Sie Lesezugriff für alle Datensätze in der abzufragenden Tabelle. Wenn eine ACL den anfragenden Benutzer daran hindert, auf einen Datensatz in der Tabelle zuzugreifen, gibt die Anforderung den Fehler „403 Unzulässig“ zurück.

Aggregat – GET /now/stats/{tableName}

Ruft Datensätze für die angegebene Tabelle ab und führt Aggregatfunktionen für die zurückgegebenen Werte aus.

Sie können angeben, welche Aggregatfunktionen ausgeführt werden sollen, indem Sie entweder den Parameter sysparm_<aggregate>_fields oder den Parameter sysparm_having=<aggregate>^field^operator^value verwenden, indem Sie eine dieser Aggregatfunktionen durch <aggregate> ersetzen:

• avg
• max.
• min
• sum

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/stats/{tableName}

Standard-URL: /api/now/stats/{tableName}

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 1. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
tableName	Name der Tabelle, für die Datensätze abgerufen werden sollen. Datentyp: Zeichenfolge

Tabelle : 2. Abfrageparameter

Name	Beschreibung
Name-Wert-Paare	Eine Alternative zur Verwendung des Parameters sysparm_query. Sie können eine Abfrage mithilfe von Schlüssel-Wert-Paaren filtern, wobei der Schlüssel der Name eines Felds ist. Beispielsweise können Sie statt des Parameters &sysparm_query=active=true &active=true verwenden. Sie können den Anzeigewert verwenden, wenn das Feld ein Auswahl- oder ein Referenztypfeld ist, z. B. &state=closed anstatt &state=7. Um mehrere Schlüssel-Wert-Paare anzugeben, trennen Sie sie jeweils mit einem kaufmännischen Und-Zeichen, z. B. &active=true&assigned_to=john.smith. Datentyp: Zeichenfolge
sysparm_<aggregate>_fields	Liste der Felder, für die jeder Zusammenfassungsvorgang ausgeführt werden soll. Sie können mehrere Felder angeben, indem Sie sie durch Kommas voneinander trennen. Um beispielsweise die Durchschnittswerte aus den Feldern „Dauer“ und „Priorität“ abzurufen, verwenden Sie sysparm_avg_fields=duration,priority. Hinweis: Geben Sie diesen Parameter und/oder den Parameter sysparm_count an, damit Ihre Abfrage aussagekräftige Ergebnisse zurückgibt. Wenn keiner der Parameter übergeben wird, wird kein Zusammenfassungsvorgang durchgeführt. Datentyp: Zeichenfolge
sysparm_count	Flag, das bestimmt, ob die Anzahl der von der Abfrage zurückgegebenen Datensätze zurückgegeben werden soll. Hinweis: Geben Sie diesen Parameter und/oder den Parameter sysparm_<aggregate>_fields an, damit Ihre Abfrage aussagekräftige Ergebnisse zurückgibt. Wenn keiner der Parameter übergeben wird, wird kein Zusammenfassungsvorgang durchgeführt. Datentyp: Zeichenfolge
sysparm_display_value	Datenabruf beim Gruppieren nach Referenz- oder Auswahlfeldern. Basierend auf diesem Wert gibt die Abfrage entweder den Anzeigewert, den tatsächlichen Wert in der Datenbank oder beides zurück. true: Gibt Anzeigewerte für alle Felder zurück. „falsch“: Gibt Ist-Werte aus der Datenbank zurück. Wenn kein Wert angegeben wird, wird für diesen Parameter standardmäßig „false“ verwendet. all: Gibt sowohl die tatsächlichen als auch die Anzeigewerte zurück. Es gibt keine bevorzugte Methode zum Festlegen dieses Parameters. Das Angeben des Anzeigewerts kann jedoch Leistungsprobleme verursachen, da er nicht aus der Datenbank gelesen wird und evtl. andere Felder und Datensätze referenziert. Weitere Informationen zu Anzeigewerten und tatsächlichen Werten finden Sie unter FAQs zur Table-API (KB0534905). Datentyp: Zeichenfolge
sysparm_group_by	Felder, nach denen die zurückgegebenen Daten gruppiert werden sollen. Sie können mehrere Felder angeben, indem Sie jedes Feld durch ein Komma trennen, z. B. sysparm_group_by=priority,state. Datentyp: Zeichenfolge
sysparm_having	Zusätzliche Abfrage, mit der Sie die Daten basierend auf einem Zusammenfassungsvorgang filtern können. Der Wert für diesen Parameter muss die Syntax aggregate^field^operator^value aufweisen, wie count^priority^>^3, um die Anzahl der Datensätze in den Abfrageergebnissen mit einer Priorität größer als 3 zu erhalten. Sie können mehrere Abfragen angeben, indem Sie jede durch ein Komma trennen, wie ascount^state^=^1,avg^priority^>^3. Datentyp: Zeichenfolge
sysparm_order_by	Liste der Werte, nach denen gruppierte Ergebnisse sortiert werden sollen. Sie können eine Sortierung über ein Feld oder eine Zusammenfassung angeben. Wenn Sie beispielsweise sysparm_order_by=AVG^stateangeben, werden Gruppen von Ergebnissen mit niedrigeren durchschnittlichen Statuswerten zuerst zurückgegeben. Sie können auch nach ANZAHL sortieren, um Gruppen von Datensätzen nach der Anzahl der Datensätze in jeder Gruppe anzuordnen. Wenn Sie eine Sortierung angeben, werden die Gruppen standardmäßig aufsteigend sortiert. Verwenden Sie ^DESC, um in absteigender Reihenfolge zu sortieren, z. B. sysparm_order_by=state^DESC. Datentyp: Zeichenfolge
sysparm_query	Codierte Abfrage. Beispiel: (sysparm_query=active=wahr)(sysparm_query=caller_id=javascript:gs.getUserID()^active=wahr) Datentyp: Zeichenfolge

Tabelle : 3. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Keine

Kopfzeilen

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 4. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 5. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 6. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
Abhängig von der angegebenen Tabelle und den angegebenen Anforderungsparametern.

Beispiel für eine cURL-Anforderung

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