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

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 と評価するバイナリ演算子。
    複数パラメーター フィルタ - AND
  • or: オペランドの中の少なくとも 1 つの条件が 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、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」を参照してください。