リソースのフィルタリング


リソースのフィルタリング


HTTP GET リクエストを使用して、すべてのリソースの取得、リソースのフィルタリング、リソースのソート、およびリソースから返されるデータの制限が可能です。URL のパスは、取得するリソースのセットを指定します。例えば、すべてのCars リソースを取得するには、次のURL を使用します。

http://MyServer:MyPort/api.rsc/Cars

シングルリソース

1つのリソースを取得するには、そのリソースのURL に対してリクエストを投げます。URL を作成するには、目的のリソースの主キーを使用します。次に例を示します。

http://MyServer:MyPort/api.rsc/Cars('1000')

リソースによっては、次の例に示すような索引付きの複数の主キーがある場合があります。

http://MyServer:MyPort/api.rsc/Cars(Id='1000', Date='2016-07-01')

フィルタリング

クライアントアプリケーションは、リクエスト内で提供されるフィルタを元に、複数のリソースを取得することができます。例としては、Make が’Honda’ にマッチするすべてのリソースを取得するフィルタは、次のようになります:

http://MyServer:MyPort/api.rsc/Cars?$filter=Make eq 'Honda'

比較のために、API Server は、以下の論理演算子をサポートしています。

Eq イコール
Ne イコールではない
Gt 大なり
Ge 大なりイコール
Lt 小なり
Le 小なりイコール
Not 否定

また、’and’ および’or’ を使って、複数のフィルタを結合させることができます。

http://MyServer:MyPort/api.rsc/Cars?$filter=Make eq 'Honda' and Date lt '2016-07-01'

$filter クエリオプションでは、startswith、endswith、toupper、tolower、およびcontains 関数を使用できます。例えば、次のリクエストは、指定されたサブ文字列を含むプロパティのリソースを返します。

http://MyServer:MyPort/api.rsc/Cars?$filter=contains(Make,'Honda')

プロパティの選択

プロパティのサブセットを取得するには、次の例に示すように$select を使用します。

http://MyServer:MyPort/api.rsc/Cars?$select=Id,Model

これは、リクエスト内のフィルタにマッチするすべてのリソースのId およびModel プロパティを返します。 また、次の例に示すように1つのリソースの個別のプロパティ値を取得することも可能です。

http://MyServer:MyPort/api.rsc/Cars('1000')/Model/$value

並べ替え

次の例に示すように、$orderby を使用してリソースを並べ替えることができます。

http://MyServer:MyPort/api.rsc/Cars?$orderby=Model asc, Color desc

これは、Model(昇順)、そしてColor(降順)で並べ替えられたリソースを返します。

ページネーション

サーバーサイド

API Server はサーバーサイドページングをサポートしており、アプリケーションの[設定]->[サーバー]セクションで有効にできます。ページサイズが0より大きく、リクエストがページサイズよりも大きな結果を返す場合、結果の次のページのURL がレスポンスの@odata.nextlink 属性に含まれます。結果の最後のページにはこの属性は含まれません。このURL には、2分間有効なページングトークンが含まれています。例えば、次のレスポンスは3つのリソースを持ち、@odata.nextLink 属性はレコードの次のページのURL を含んでいます。

{
  "@odata.context": "http://MyServer:MyPort/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/api.rsc/Cars?$skiptoken=0f87696b-aa28-4a70-b13d-c86af8338c80"
}

クライアントサイド

CData API Server は、$top、$skip、および$count を使って、クライアントサイドページングもサポートしています。

$top=n を使用して、最初のn個のリソースのみを結果に含めることができます。例えば、次の要求を使用すると、上位10個のCars リソースを表示できます。

http://MyServer:MyPort/api.rsc/Cars?$top=10

$skip=n を使用して、最初のn個のリソースを結果から除外することができます。$topを$skip と組み合わせて使用すると、クライアントサイドのページングを実装できます。$skip は、クエリ内の順番にかかわらず、常に$top の前に適用されます。例えば、次の2つのクエリは、最初の20個の リソースを2ページに分けて取得します:

http://MyServer:MyPort/api.rsc/Cars?$top=10
http://MyServer:MyPort/api.rsc/Cars?$top=10&$skip=10

パラメータ$count をtrue に設定して、結果内のレコードの合計数を返すこともできます。OData バージョン2.0または3.0を使用している場合は、代わりに$inlinecount をallpages に設定できます。例えば、次のクエリを考えてみましょう:

http://MyServer:MyPort/api.rsc/Cars?$top=3&$skip=4&$count=true

このクエリは、次のようなレスポンスを返します:

{
  "@odata.context": "http://MyServer:MyPort/api.rsc/$metadata#Cars",
  "@odata.count": 402,
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/api.rsc/Account?$skip=7"
}

このように、フィルタにマッチする合計カウントが、結果のシングルページと共にレスポンスで返されます。

Count-Only

次の例に示すように、クエリの特定のフィルタにマッチするリソースのカウントのみを取得することができます。

http://MyServer:MyPort/api.rsc/Cars?$count=true&$filter=Make eq 'Honda'

レスポンスは、リクエストのフィルタにマッチするリソースの行カウントになります。