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:
Filtro de parâmetro único

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.
    Filtro de múltiplos parâmetros - AND
  • or: Um operador binário que avalia como true se pelo menos uma das condições nos operandos é considerada true.
    Filtro de múltiplos parâmetros - OR
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.