Filtrage, pagination et tri

L'API de la Control Room prend en charge le filtrage, la pagination et le tri pour les points de terminaison qui renvoient des tableaux de ressources.

Le mécanisme de filtrage filtre les ressources requises, le mécanisme de triage place les ressources dans l'ordre, et le mécanisme de pagination renvoie ensuite une plage spécifique de ces ressources ordonnées. Cette rubrique fournit les détails pour filtrer et trier les résultats des demande d'API et vous guide également pour gérer la pagination des grands ensembles de résultats renvoyés par une demande d'API.

Remarque :

Le tri et le filtrage sont pris en charge pour les sous-chaînes. Par exemple, si vous voulez rechercher des robots ou des fichiers qui ont fin dans leur nom, entrez fin comme critère de recherche. Tous les robots et fichiers dont le nom contient fin sont renvoyés, par exemple, Finance, Finder, DeltaFinance et Dolfin.
Les caractères génériques ne sont pas pris en charge pour la recherche et le filtrage des robots ou des fichiers.

Filtrage

Le filtrage vous permet d'appliquer une condition booléenne à une collection de ressources retournées afin de limiter la collection aux ressources pour lesquelles la condition est true. L'opération la plus élémentaire dans un filtre d'API de la Control Room consiste à comparer un champ à une valeur donnée. Il est possible d'utiliser la comparaison d'égalité, la comparaison d'intervalles et la logique . Utilisez les opérateurs suivants pour comparer un champ à une valeur constante.


Opération	Description	Exemple
Comparaison d'égalité
eq	Est égal à	UserEmailAddress, eq first.last@aa.com
ne	Pas égal à	UserEmailAddress, ne first.last@aa.com
Comparaison de plages
lt	Inférieur à (<)	Quantity lt 1500
le	Inférieur ou égal à	Quantity le 1500
ge	Supérieur ou égal à	CreatedDateUtc ge 2021-03-15
gt	Supérieur à	CreatedDateUtc gt 2021-03-15
Logique
et	Et	Field1 eq 'abc' et Field2 eq 'def'
ou	Ou	Field1 eq 'abc' ou Field2 eq 'def'

Le paramètre de requête filter permet d'appliquer à une demande des filtres basiques, multiples et orientés vers les conventions. Les filtres dans les API de la Control Room sont appliqués avec un seul paramètre ou avec plusieurs paramètres.

Filtre à paramètre unique

Le filtre à paramètre unique permet à la requête API de sélectionner les réponses en faisant correspondre un ou plusieurs membres de la réponse à la valeur transmise dans la requête. Le filtre à paramètre unique est représenté dans l'image suivante :

L'équivalent JSON de l'image ci-dessus (filtre à paramètre unique) ressemble à ceci :

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

Par exemple, pour lister tous les pools de périphériques contenant la sous-chaîne finance, utilisez le filtre à paramètre unique suivant :

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

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

Pour un échantillon plus détaillé sur un filtre à paramètre unique, voir API de pools de périphériques.

Filtre à paramètres multiples

Le filtre à paramètres multiples permet de filtrer les résultats sur la base de la combinaison de plusieurs conditions encapsulées dans les opérandes logiques and et or.

and : Opérateur binaire qui donne la valeur true si toutes les conditions dans les opérandes donnent la valeur true.
or : Opérateur binaire qui donne la valeur true si au moins une des conditions des opérandes donne la valeur true.

L'équivalent JSON de l'image ci-dessus (filtre à paramètres multiples) ressemble à ceci :

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

Par exemple, pour lister tous les rôles qui ont une sous-chaîne Device, avec createdOn postérieur à2022-04-01, et createdOn antérieur à 2022-05-31, utilisez le filtre à paramètres multiples avec l'opérateur logique add comme suit :

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

Pour un échantillon plus détaillé sur un filtre à paramètre unique, voir API de gestion des utilisateurs.

Pagination

La pagination permet de :

Récupérer une collection limitée de résultats.
Décaler une collection de résultats.

Toutes les API de la Control Room qui renvoient une collection d'enregistrements sont paginées. Les méthodes API qui prennent en charge la pagination prennent deux paramètres (facultatifs) :


Opération	Description
décalage	Le paramètre décalage contrôle le point de départ dans la collection des résultats de réponse. La valeur par défaut est 0.
longueur	Le paramètre longueur est le nombre maximum d'enregistrements à extraire à partir du décalage. La valeur par défaut est 200.

Le snippet JSON pour la pagination ressemble à ceci :

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

Pour un échantillon plus détaillé sur un filtre à paramètre unique, voir API de gestion des utilisateurs.

Tri

Le tri permet d'ordonner les résultats par n'importe quel champ, par ordre croissant ou décroissant. Par exemple, si vous retournez les rôles, vous pouvez trier les rôles par date de dernière modification.

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

Sens

Type : Enum [ desc, asc ]

asc = croissant (du plus petit au plus grand, de 0 à 9, de A à Z)
desc = décroissant (du plus grand au plus petit, de 9 à 0, de Z à A)

Pour un échantillon plus détaillé sur un filtre à paramètre unique, voir API de gestion des utilisateurs.

Automation 360