필터링, 페이지 매김 및 정렬

Control Room API는 리소스 배열을 반환하는 엔드포인트에 대한 필터링, 페이지 매김 및 정렬을 지원합니다.

필터링 메커니즘은 필요한 리소스를 필터링하고, 정렬 메커니즘은 리소스를 순서대로 배치하고, 페이지 매김 메커니즘은 정렬된 리소스의 특정 범위를 반환합니다. 이 항목에서는 API 요청의 결과를 필터링 및 정렬하기 위한 세부 정보를 제공하고 API 요청에서 반환된 큰 결과 집합의 페이지 매김을 처리하기 위한 지침도 제공합니다.
주:
  • 하위 문자열에 대한 정렬 및 필터링이 지원됩니다. 예를 들어 이름에 fin이 있는 Bot 또는 파일을 검색하려는 경우 검색 기준으로 fin을 입력합니다. 이름에 fin이 포함된 모든 Bot 및 파일이 표시됩니다(예: Finance, Finder, DeltaFinance 및 Dolpin).
  • Bot 또는 파일 검색 및 필터링에는 와일드카드가 지원되지 않습니다.

필터링

필터링을 사용하면 조건이 true인 리소스에만 모음의 하위 집합을 지정하기 위해 반환된 리소스 모음에 대해 부울 조건을 적용할 수 있습니다. Control Room API 필터에서 가장 기본적인 작업은 필드를 지정된 값과 비교하는 것입니다. 같음 비교, 범위 비교 또는 로직을 사용할 수 있습니다. 다음 연산자를 사용하여 필드를 상수 값과 비교합니다.
작업 설명
같음 비교
eq Equals UserEmailAddress, eq first.last@aa.com
ne Not Equals UserEmailAddress, ne first.last@aa.com
범위 비교
lt Less Than(<) Quantity lt 1500
le 보다 작거나 같음 Quantity le 1500
ge 보다 크거나 같음 CreatedDateUtc ge 2021-03-15
gt Greater Than CreatedDateUtc gt 2021-03-15
로직
Field1 eq 'abc' and Field2 eq 'def'
또는 또는 Field1 eq 'abc' or Field2 eq 'def'
filter 쿼리 매개변수를 사용하면 기본, 다중 및 규칙 지향 필터를 요청에 적용할 수 있습니다. Control Room API의 필터는 단일 매개변수 또는 여러 매개변수를 사용하여 적용됩니다.

단일 매개변수 필터

단일 매개변수 필터를 사용하면 API 요청이 하나 이상의 응답 멤버를 쿼리에 전달된 값과 일치시켜 응답을 선택할 수 있습니다. 단일 매개변수 필터는 다음 이미지에 나와 있습니다.
단일 매개변수 필터

위 이미지(단일 매개변수 필터)에 해당하는 JSON은 다음과 같습니다.
{
  "filter": {
    "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
    "field": "string",
    "value": "string"
  }
}

예를 들어 하위 문자열 finance가 있는 모든 기기 풀을 나열하려면 다음 단일 매개변수 필터를 사용합니다.

POST http://{{ControlRoomURL}}/v2/devices/pools/list
{
   "filter":{
      "operator":"substring",
      "field":"name",
      "value":"finance"
   }
}

단일 매개변수 필터에 대한 자세한 샘플은 기기 풀 API.항목을 참조하십시오.

다중 매개변수 필터

다중 매개변수 필터를 사용하면 로직 피연산자 andor에 래핑된 여러 조건을 결합하여 결과를 필터링할 수 있습니다.
  • and: 피연산자의 모든 조건이 true로 평가되면 true로 평가되는 이진 연산자입니다.
    다중 매개변수 필터 - AND
  • or: 피연산자의 조건 중 하나 이상이 true로 평가되면 true로 평가되는 이진 연산자입니다.
    다중 매개변수 필터 - OR
위 이미지(다중 매개변수 필터)에 해당하는 JSON은 다음과 같습니다.
{
  "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"
      }
    ]
  }
}

예를 들어, 하위 문자열 Device를 포함하고, createdOn2022-04-01 이후이고, createdOn2022-05-31 이전인 역할을 모두 나열하려면 다음과 같이 로직 add가 포함된 다중 매개변수 필터를 사용합니다.

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

단일 매개변수 필터에 대한 자세한 샘플은 사용자 관리 API.항목을 참조하십시오.

페이지 매김

페이지 매김을 통해 다음을 수행할 수 있습니다.
  • 제한된 결과 모음을 검색합니다.
  • 결과 모음을 오프셋합니다.
기록 모음을 반환하는 모든 Control Room API는 페이지가 매겨집니다. 페이지 매김을 지원하는 API 메소드는 두 가지(선택 사항) 매개변수를 사용합니다.
작업 설명
오프셋 오프셋 매개변수는 응답 결과 모음 내에서 시작점을 제어합니다. 기본값은 0입니다.
길이 길이 매개변수는 오프셋에서 시작하여 검색할 최대 기록 수입니다. 기본값은 200입니다.
페이지 매김을 위한 JSON 코드 조각은 다음과 같습니다.
"page":{ 
    "offset":5,
    "length":10
    }

단일 매개변수 필터에 대한 자세한 샘플은 사용자 관리 API.항목을 참조하십시오.

정렬

정렬을 사용하면 임의의 필드를 기준으로 결과를 오름차순 또는 내림차순으로 정렬할 수 있습니다. 예를 들어 역할을 반환하는 경우 마지막 수정 날짜를 기준으로 역할을 정렬할 수 있습니다.

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

방향

유형: 열거 [ desc, asc ]

  • asc = 오름차순(최솟값에서 최댓값으로, 0에서 9, A에서 Z)
  • desc = 내림차순(최댓값에서 최솟값으로, 9에서 0까지, Z에서 A로)

단일 매개변수 필터에 대한 자세한 샘플은 사용자 관리 API.항목을 참조하십시오.