フィルタリング、改ページ、ソート

Control Room API は、リソースの配列を返すエンドポイントに対して、フィルタリング、改ページ、ソートをサポートします。

フィルタリング機構は必要なリソースをフィルタリングし、ソート機構はリソースを順序付けし、改ページ機構はその順序付けられたリソースの特定の範囲を返します。このトピックでは、API リクエストの結果をフィルタリングおよびソートする方法と、API リクエストから返された大量の結果セットの改ページを行う方法について説明します。

注:

従属文字列のソートとフィルタリングはサポートされています。たとえば、名前に fin を含む Bot またはファイルを検索したい場合は、検索条件として「fin」と入力します。名前に fin を含むすべての Bot とファイルが表示されます。たとえば、Finance、Finder、DeltaFinance、Dolfin などです。
Bot やファイルの検索とフィルタリングにワイルドカードはサポートされていません。

フィルタリング

フィルタリングを使用すると、返されたリソースのコレクションに対して Boolean 条件を適用して、条件が true であるリソースのコレクションのみのサブセットを抽出できます。Control Room API フィルタにおける最も基本的な操作は、あるフィールドと与えられた値とを比較することです。等価性比較、範囲比較、またはロジックを使用することが可能です。以下の演算子を使用して、フィールドと一定値を比較することができます。


操作	説明	例
等価性比較
eq	等しい	UserEmailAddress、eq first.last@aa.com
ne	等しくない	UserEmailAddress、ne first.last@aa.com
範囲比較
lt	より小さい	数量 lt 1500
le	以下	数量 le 1500
ge	以上	CreatedDateUtc ge 2021-03-15
gt	より大きい	CreatedDateUtc gt 2021-03-15
ロジック
and	および	Field1 eq 'abc' および Field2 eq 'def'。
または	または	Field1 eq 'abc' または Field2 eq 'def'。

filter クエリパラメーターにより、リクエストに基本的な、複数の、規則指向のフィルタを適用することができます。Control Room API のフィルタは、単一のパラメーターまたは複数のパラメーターで適用されます。

単一パラメーターフィルタ

単一パラメーターフィルタを使用すると、API リクエストで、1 人以上のメンバーの応答をクエリで渡された値と一致させることにより、応答を選択することができます。単一パラメーターフィルタは、次の図のように表されます。

上の画像に相当する 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」を参照してください。

複数パラメーターフィルタ

複数パラメーターフィルタを使用すると、論理演算子 and と or でくくられた複数の条件を組み合わせて結果をフィルタリングすることができます。

and: オペランドの中のすべての条件が true であると評価する場合に、true と評価するバイナリ演算子。
or: オペランドの中の少なくとも 1 つの条件が true であると評価する場合に、true と評価するバイナリ演算子。

上の画像に相当する 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、createdOn が 2022-04-01 より後の日時で、createdOn が 2022-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 メソッドは、2 つの (オプションの) パラメーターを取ります。


操作	説明
offset	offset パラメーターは、応答結果のコレクション内の開始点を制御。デフォルト値は 0。
長さ	length パラメーターは，オフセットから開始するレコードの最大取得数。デフォルト値は 200。

改ページの JSON スニペットは以下のようになります。

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

単一パラメーターフィルタに関するより詳細なサンプルは、「ユーザー管理 API」を参照してください。

ソート

ソートでは、任意のフィールドで結果を昇順または降順に並べることができます。たとえば、ロールを返す場合、最終変更日でロールをソートすることができます。

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

方向

タイプ: Enum [ desc, asc ]

asc = 昇順 (小から大、0 から 9、A から Z)
asc = 降順 (大から小、9 から 0、Z から A)

単一パラメーターフィルタに関するより詳細なサンプルは、「ユーザー管理 API」を参照してください。