Filtragem, paginação e classificação

A API do Control Room é compatível com filtragem, paginação e classificação para endpoints que retornam conjuntos de recursos.

O mecanismo de filtragem filtra os recursos necessários, o mecanismo de classificação coloca os recursos em ordem; e o mecanismo de paginação devolve então uma gama específica daqueles recursos encomendados. Este tópico fornece os detalhes para filtrar e classificar os resultados de uma solicitação de API e também um guia para lidar com a paginação de grandes conjuntos de resultados retornados de uma solicitação de API.

Nota:

A classificação e a filtragem são compatíveis com substrings. Por exemplo, se você quiser procurar por bots ou arquivos que tenham fin em seus nomes, digite fin como critério de pesquisa. Todos os bots e os arquivos que contenham fin nos nomes serão exibidos, por exemplo, Finance, Finder, DeltaFinance e Dolfin.
Não são aceitos caracteres curinga para a pesquisa e filtragem de bots ou arquivos.

Filtragem

A filtragem permite que você aplique condições booleanas em um conjunto de recursos retornados para subconjunto da coleção apenas para os recursos para os quais a condição é true. A operação mais básica nos filtros de uma API Control Room é para comparar um campo com um determinado valor. É possível utilizar comparação de igualdade, comparação de intervalo ou lógica . Use os seguintes operadores para comparar um campo a um valor constante.


Operação	Descrição	Exemplo
Comparação de igualdade
eq	Igual a (=)	UserEmailAddress, eq first.last@aa.com
ne	Não igual	UserEmailAddress, ne first.last@aa.com
Comparação de intervalo
lt	Menor que (<)	Quantidade lt 1500
le	Menor que ou igual a	Quantidade le 1500
ge	Maior que ou igual a	CreatedDateUtc ge 2021-03-15
gt	Maior que	CreatedDateUtc gt 2021-03-15
Lógica
e	E	Campo1 eq “abc” e Campo2 eq “def”
ou	Ou	Campo1 eq “abc” ou Campo2 eq “def”

O parâmetro de consulta filter permite aplicar filtros básicos, múltiplos e orientados a convenções a uma solicitação. Os filtros nas APIs Control Room são aplicados com um único parâmetro ou com vários parâmetros.

Filtro de parâmetro único

O filtro de parâmetro único permite que a solicitação de API selecione as respostas combinando um ou mais membros da resposta com o valor passado na consulta. O filtro de parâmetro único é representado na imagem a seguir:

O equivalente JSON da imagem acima (filtro de parâmetro único) é assim:

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

Por exemplo, para listar todos os pools de dispositivos que possuem uma substring finance, use o seguinte filtro de parâmetro único:

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

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

Para uma amostra mais detalhada em um filtro de parâmetro único, consulte API de pools de dispositivos.

Filtro de vários parâmetros - AND

O filtro de vários parâmetros permite filtrar os resultados com base na combinação de várias condições incluídas em operandos lógicos and e or.

and: Um operador binário que avalia para true se todas as condições nos operandos avaliarem para true.
or: Um operador binário que avalia como true se pelo menos uma das condições nos operandos é considerada true.

O equivalente JSON da imagem acima (filtro de parâmetro único) é assim:

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

Por exemplo, para listar todas as funções que têm uma substring Device, createdOn é anterior a 2022-04-01 e createdOn é posterior a 2022-05-31, use a filtragem de vários parâmetros com operador lógico add da seguinte forma:

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

Para uma amostra mais detalhada em um filtro de parâmetro único, consulte APIs de gerenciamento de usuários.

Paginação

A paginação permite que você:

Recupere uma coleção limitada de resultados.
Desloque uma coleção de resultados.

Todas as APIs de Control Room que retornam uma coleção de registros são paginados. Os métodos de API compatíveis com paginação usam dois parâmetros (opcionais):


Operação	Descrição
offset	O parâmetro de deslocamento controla o ponto de partida dentro da coleta dos resultados da resposta. O valor padrão é 0.
length	O parâmetro de comprimento é o número máximo de registros a serem recuperados a partir do deslocamento. O valor padrão é 200.

O snippet do JSON para paginação é assim:

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

Para uma amostra mais detalhada em um filtro de parâmetro único, consulte APIs de gerenciamento de usuários.

Classificar

A classificação permite ordenar os resultados por qualquer campo, em ordem ascendente ou descendente. Por exemplo, se você estiver devolvendo as funções, pode classificar os funções até a data da última modificação.

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

Direção

Tipo: Enum [ desc, asc ]

asc = ascendente (menor para maior, 0 a 9, A a Z)
desc = descendente (maior para menor, 9 a 0, Z a A)

Para uma amostra mais detalhada em um filtro de parâmetro único, consulte APIs de gerenciamento de usuários.

Automation 360

Filtragem, paginação e classificação