Aggregieren-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Die Aggregate -API bietet Endpunkte, mit denen Sie zusammengefasste Statistiken zu vorhandenen Tabellen- und Spaltendaten berechnen können.

    Für zusammengefasste API-Anforderungen müssen Sie Lesezugriff für alle Datensätze in der abgefragten 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.

    Aggregate – GET /now/stats/{tableName}

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

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

    • avg
    • max.
    • min
    • sum

    URL-Format

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

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

    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, den Parameter sysparm_count oder beide Parameter für Ihre Abfrage an, 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, den Parameter sysparm_<aggregate>_fields oder beide Parameter für Ihre Abfrage an, 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.
    • true: Gibt Anzeigewerte für alle Felder zurück.
    • false: Gibt tatsächliche Werte aus der Datenbank zurück. Wenn kein Wert angegeben wird, wird für diesen Parameter standardmäßig „false“ verwendet.
    • all: Gibt sowohl Ist- als auch 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_orderby Liste der Werte, nach denen gruppierte Ergebnisse sortiert werden sollen. Sie können eine Sortierung über ein Feld oder eine Zusammenfassung angeben. Wenn Sie zum Beispiel sysparm_orderby=DURCHSCHNITT^state angeben, 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 absteigend zu sortieren, wie sysparm_orderby=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 HTTP-Antwortcodesder 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.

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