Filtern, Paginieren und Sortieren

Die Control Room-API unterstützt das Filtern, Paginieren und Sortieren für Endpunkte, mit denen Arrays von Ressourcen zurückgegeben werden.

Der Filtermechanismus filtert die gewünschten Ressourcen, der Sortiermechanismus ordnet die Ressourcen, und der Paginierungsmechanismus gibt dann einen bestimmten Bereich dieser geordneten Ressourcen zurück. In diesem Thema finden Sie Einzelheiten zum Filtern und Sortieren der Ergebnisse einer API-Anforderung sowie Anleitungen zur Handhabung der Paginierung großer Ergebnismengen, die von einer API-Anforderung zurückgegeben werden.

Anmerkung:

Sortierung und Filterung werden für Teilzeichenfolgen unterstützt. Wenn Sie zum Beispiel nach Bots oder Dateien suchen möchten, die fin im Namen enthalten, geben Sie fin als Suchkriterium ein. Alle Bots und Dateien, die fin im Namen enthalten, werden angezeigt, zum Beispiel Finance, Finder, DeltaFinance und Dolfin.
Wildcards werden für die Suche und das Filtern von Bots oder Dateien nicht unterstützt.

Filtern

Durch das Filtern können Sie eine boolesche Bedingung auf eine Sammlung von zurückgegebenen Ressourcen anwenden, um die Sammlung nur auf jene Ressourcen zu beschränken, für die die Bedingung true lautet. Die grundlegendste Operation eines Control Room-API-Filters ist der Vergleich eines Feldes mit einem bestimmten Wert. Sie können einen Gleichheitsvergleich, einen Bereichsvergleich oder einen Logikvergleich verwenden. Mithilfe der folgenden Operatoren vergleichen Sie ein Feld mit einem konstanten Wert.


Operation	Beschreibung	Beispiel
Gleichheitsvergleich
eq	Ist gleich	UserEmailAddress, eq first.last@aa.com
ne	Ungleich	UserEmailAddress, ne first.last@aa.com
Bereichsvergleich
lt	Kleiner als	Menge lt 1.500
le	Kleiner gleich	Anzahl le 1.500
ge	Größer gleich	CreatedDateUtc ge 2021-03-15
gt	Größer als	CreatedDateUtc gt 2021-03-15
Logisch
und	und	Field1 gleich 'abc' und Field2 gleich 'def'
oder	Oder	Field1 gleich 'abc' oder Field2 gleich 'def'

Mit dem Abfrageparameter filter können Sie grundlegende, mehrere und konventionsorientierte Filter auf eine Anforderung anwenden. Die Filter in den Control Room-APIs werden mit einem einzelnen oder mehreren Parametern angewendet.

Filter mit einzelnem Parameter

Mit dem Filter mit einzelnem Parameter können Antworten von der API-Anforderung ausgewählt werden, indem ein oder mehrere Elemente der Antwort mit dem in der Abfrage übergebenen Wert abgeglichen werden. Der Filter mit einzelnem Parameter ist in der folgenden Abbildung dargestellt:

Das JSON-Äquivalent des obigen Bildes (Filter mit einzelnem Parameter) sieht folgendermaßen aus:

{
  "filter": {
    "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
    "field": "string",
    "value": "string"
  }
}

Wenn Sie beispielsweise alle Gerätepools auflisten möchten, die die Unterzeichenfolge finance enthalten, verwenden Sie den folgenden Filter mit einzelnem Parameter:

POST http://{{ControlRoomURL}}/v2/devices/pools/list

{
   "filter":{
      "operator":"substring",
      "field":"name",
      "value":"finance"
   }
}

Ein ausführlicheres Beispiel für einen Filter mit einzelnem Parameter finden Sie unter Gerätepool-API.

Filter mit mehreren Parametern

Mit dem Filter mit mehreren Parametern können Sie die Ergebnisse auf der Grundlage der Kombination mehrerer Bedingungen filtern, die in den logischen Operanden and und or enthalten sind.

and: Ein binärer Operator, der mit true beurteilt, wenn alle Bedingungen in den Operanden als true beurteilt werden.
or: Ein binärer Operator, der mit true beurteilt, wenn mindestens eine der Bedingungen in den Operanden mit true beurteilt wird.

Das JSON-Äquivalent des obigen Bildes (Filter mit mehreren Parametern) sieht folgendermaßen aus:

{
  "filter": {
    "operator": "<and, or>",
    "operands": [
      {
        "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
        "field": "string",
        "value": "string"
      },
      {
        "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
        "field": "string",
        "value": "string"
      }
    ]
  }
}

Wenn Sie zum Beispiel alle Rollen auflisten möchten, die die Unterzeichenfolge Device enthalten und das Datum voncreatedOn nach dem 2022-04-01 und createdOn vor dem 2022-05-31 liegt, verwenden Sie die Filterung mit mehreren Parametern mit dem logischen Operator add wie folgt:

POST http://{{ControlRoomURL}}//v1/usermanagement/roles/list

{
   "filter":{
      "operator":"and",
      "operands":[
         {
            "operator":"substring",
            "field":"name",
            "value":"Device"
         },
         {
            "operator":"gt",
            "field":"createdOn",
            "value":"2022-04-01T00:00:00.989Z"
         },
         {
            "operator":"lt",
            "field":"createdOn",
            "value":"2022-05-31T23:00:00.123Z"
         }
      ]
   }
   }

Ein ausführlicheres Beispiel für einen Filter mit einzelnem Parameter finden Sie unter API für die Nutzerverwaltung.

Paginierung

Mit der Paginierung können Sie:

eine begrenzte Sammlung von Ergebnissen abrufen
eine Sammlung von Ergebnissen aufrechnen

Alle Control Room-APIs, die eine Sammlung von Datensätzen zurückgeben, sind paginiert. API-Methoden, die die Paginierung unterstützen, benötigen zwei (optionale) Parameter:


Operation	Beschreibung
offset	Mit dem Parameter Versatz wird der Startpunkt innerhalb der Sammlung von Antwortergebnissen gesteuert. Der Standardwert lautet 0.
Länge	Der Parameter Länge ist die maximale Anzahl der Datensätze, die ab dem Versatz abgerufen werden sollen. Der Standardwert lautet 200.

Das JSON-Snippet für die Paginierung sieht wie folgt aus:

"page":{ 
    "offset":5,
    "length":10
    }

Ein ausführlicheres Beispiel für einen Filter mit einzelnem Parameter finden Sie unter API für die Nutzerverwaltung.

Sortierung

Mit der Sortierung können Sie die Ergebnisse nach einem beliebigen Feld in aufsteigender oder absteigender Reihenfolge ordnen. Wenn Sie zum Beispiel Rollen zurückgeben, können Sie diese nach dem Datum der letzten Änderung sortieren.

 "sort": [
    {
      "field": "string",
      "direction": "<asc, desc>"
    }

Richtung

Typ: Enum [ desc, asc ]

asc = aufsteigend (von klein nach groß, 0 bis 9, A bis Z)
desc = absteigend (von groß nach klein, 9 bis 0, Z bis A)

Ein ausführlicheres Beispiel für einen Filter mit einzelnem Parameter finden Sie unter API für die Nutzerverwaltung.

Automation 360

Filtern, Paginieren und Sortieren