Aggregieren-API

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 4 Minuten Lesedauer

    • Die Aggregieren Die API stellt Endpunkte bereit, mit denen Sie Aggregatstatistiken zu vorhandenen Tabellen- und Spaltendaten berechnen können.

    Für Aggregieren API-Anforderungen müssen Sie Lesezugriff für alle Datensätze in der abfragenden Tabelle haben. 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 verwenden sysparm_<aggregate>_fieldsParameter oder sysparm_having=<aggregate>^field^operator^valueParameter, wird ersetzt <aggregate>Für eine dieser Aggregatfunktionen:

    • avg
    • max.
    • min
    • sum

    URL-Format

    Versionierte URL: /api/now/{api_Version}/stats/{tableName}

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

    Hinweis:
    Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. 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 von sysparm_queryParameter. 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 an, die sysparm_countParameter oder beides für Ihre Abfrage, um aussagekräftige Ergebnisse zurückzugeben. 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 an, die sysparm_<aggregate>_fieldsParameter oder beides für Ihre Abfrage, um aussagekräftige Ergebnisse zurückzugeben. 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.
    • Wahr: 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. Beispiel: Wenn Sie angeben Sysparm_order_by=AVG^State , Gruppen von Ergebnissen mit niedrigeren durchschnittlichen Statuswerten werden 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 ^DESC Zum Sortieren in absteigender Reihenfolge, z. B. Sysparm_order_by=State^DESC .

    Datentyp: Zeichenfolge
    sysparm_query Codierte Abfrage.

    Beispiel: (Sysparm_query=Active=true)(sysparm_query=caller_ID=javascript:gs.getUserID()^Active=true)

    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 REST API-HTTP-Antwortcodes .

    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.

    Antworttext-Parameter (JSON oder XML)

    Name Beschreibung
    Hängt von der angegebenen Tabelle und den angegebenen Anforderungsparametern ab.

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