メインコンテンツまでスキップ

クエリパラメータ

Nodeblocksにおいて、リソースリスト取得エンドポイントのインタフェースは、Microsoft RESTful API ガイドラインに従っています。クエリの中にFilter, OrderBy, Pagination, Expand, Applyなどを使うことができます。

それらの使用方法について、説明します。

フィルタリング​

$filter クエリパラメータを使用して、取得するリソースをフィルタリングできます。

GET /resources?$filter={フィルタ条件}

フィルタ条件には、リソースのプロパティと比較演算子（eq, ne, gt, ge, lt, le）を組み合わせた式を指定します。複数の条件を組み合わせる場合、and や or を使用して条件を連結できます。

例

GET /orders?$filter=status eq 'completed' and totalPrice gt 100

並び替え​

$orderby クエリパラメータを使用して、取得するリソースの順序を指定できます。

特定のプロパティでリソースを昇順または降順に並べ替える場合、次のようにリクエストを行います。

GET /resources?$orderby={プロパティ} {昇順または降順}

昇順の場合は asc、降順の場合は desc を指定します。

例：

GET /orders?$orderby=createdAt desc

ページネーション​

エンドポイントが二種類のページネーションをサポートしています：

スキップベースのページネーション​

$skip と $top クエリパラメータを使用して、ページネーションを実現できます。

$skip は、最初にスキップするリソース数を指定します。$top は、取得するリソース数を指定します。

例：

GET /orders?$skip=10&$top=20

カーソルベースのページネーション​

カーソルベースのページネーションは、特定のリソースのポイント（カーソル）から始めて、前後のリソースを取得する方法です。オフセットベースのページネーションと比較して、大規模なデータセットの場合でも高速で安定したパフォーマンスを提供します。

例：

GET /resources?$nextToken={カーソル}&$top=10

比較

特徴スキップベースのページネーションカーソルベースのページネーション
利点・簡単に実装できる・大規模なデータセットでも高速なパフォーマンス
・任意のページに直接ジャンプできる・ページ間で重複や欠落が少ない
・データの追加や削除が頻繁に行われても安定した結果
欠点・大規模なデータセットではパフォーマンスが低下・任意のページに直接ジャンプすることが困難
・ページ間で重複や欠落数が発生する可能性・実装がやや複雑

どちらの方式を選択するかは、プロジェクトの要件やデータセットの規模によって決定されます。大規模なデータセットやデータの追加・削除が頻繁に行われる場合は、カーソルベースのページネーションが適しています。一方、実装の簡易さや任意のページへのジャンプが重要な要件であれば、スキップベースのページネーションが適切です。

拡張​

$expand クエリパラメータは、ODataの一部であり、関連するリソースを同時に取得するために使用されます。通常、APIは、要求されたリソースのプロパティと、それに関連するリソースへのリンクのみを返しますが、$expandを使用すると、関連するリソースも一度に取得できます。

例えば、プロダクトサービスがあり、各プロダクトには関連する組織情報があるとします。通常、プロダクトリソースを要求すると、組織情報へのリンクが含まれますが、組織情報データ自体は含まれません。$expandクエリパラメータを使用して組織情報データを含めるように要求できます。

GET /products?$expand=organizations

$expandを使用することで、クライアントが必要なすべてのデータを単一のリクエストで取得できるため、APIの効率が向上します。ただし、大量のデータを要求する場合は、パフォーマンスに影響が出ることがあります。そのため、適切なページネーションと組み合わせて使用することが重要です。

Expandのサポート状況は、各エンドポイントに確認してください。

適用 (変換)​

$apply クエリパラメータは、ODataの一部であり、リソースの集計やグループ化、および一部のフィルタリングや制限などの変換を行うために使用されます。変換は、APIから取得されたデータの構造を変更し、出力行数を大幅に変更する操作です。

例えば、カタログサービスをご利用の場合、$applyを利用することですべてのプロダクトの合計価格と平均価格を計算できます。

GET /products/:productId/variants?$apply=aggregate(price.amount with sum as totalPrice, price.amount with average as avgPrice)

// レスポンス

{
    "total": 1,
    "count": 1,
    "value": [
        {
            "totalPrice": 1000,
            "avgPrice": 100
        }
    ]
}

thenを区切り文字として使用することで、複数の変換を組み合わせることができます。

GET /products/:productId/variants?$apply=aggregate(price.amount with sum as totalPrice, price.amount with average as avgPrice) then filter(totalPrice gt 500)

変換: 集計 (aggregate)​

aggregate 変換は、すべてのリソースを対象に、プロパティの合計、平均、最小値、最大値、または重複してない数を計算するために使用されます。次のようの形式をしています。

aggregate({Property} with {Function} as {Alias})

Function は以下のいずれかを指定できます。

  • sum (数値フィールドの合計を返します)
  • average (数値フィールドの平均を返します)
  • min (数値または日付フィールドの最小値を返します)
  • max (数値または日付フィールドの最大値を返します)
  • countdistinct (フィールドのユニークな値の数を返します)

上記に加えて、結果セットのリソースの総数を数えるために $count 関数もご利用できます。 この関数はプロパティを必要とせず、以下のように使用されます。

aggregate($count as {Alias})

複数のプロパティを一度に集計することができ、カンマで区切って指定します。Property は階層的要素へのパスとして指定できます。 規則として、集計は常に計算された値を持つ、単一のデータ行を返します。

使用例：

GET /products/:productId/variants?$apply=aggregate(price.amount with sum as totalPrice, price.amount with average as avgPrice, $count as variantCount)

変換: グループ化 (groupby)​

groupby 変換は、リソースをプロパティでグループ化し、グループ化されたリソースに変換（最も一般的には集計）を適用するために使用されます。次のようの形式をしています。

groupby(({Property1}, {Property2}, ...), {Transformation})

変換を使用しない場合、単純に指定されたプロパティでリソースをグループ化します。

GET /products?$apply=groupby((organizationId))

// レスポンス
{
    "total": 2,
    "count": 2,
    "value": [
        {
            "organizationId": "org1",
        },
        {
            "organizationId": "org2",
        },
        ...
    ]
}

変換を使用する場合、指定されたプロパティでリソースをグループ化後、各グループのリソースに指定された変換を適用します。

GET /products?$apply=groupby((organizationId), aggregate($count as productCount))

// レスポンス
{
    "total": 2,
    "count": 2,
    "value": [
        {
            "organizationId": "org1",
            "productCount": 5
        },
        {
            "organizationId": "org2",
            "productCount": 10
        },
        ...
    ]
}

top 変換をご利用すると、各グループの上位N件のレコードを返します。最良の結果を得るためには、orderBy と組み合わせて使用してください。

GET /products?$apply=groupby((organizationId), orderBy(createdAt desc) then top(3))

// レスポンス
{
    "total": 2,
    "count": 2,
    "value": [x
        {
            "organizationId": "org1",
            "top": [
                {
                    "id": "product1",
                    ...
                },
                {
                    "id": "product2",
                    ...
                },
                {
                    "id": "product3",
                    ...
                }
            ]
        },
        {
            "organizationId": "org2",
            "top": [
                {
                    "id": "product4",
                    ...
                },
                {
                    "id": "product5",
                    ...
                },
                {
                    "id": "product6",
                    ...
                }
            ]
        },
        ...
    ]
}

変換: フィルタ (filter)​

filter 変換は、取得したリソースリストをフィルタリングするために使用されます。filter の内容は $filter クエリパラメータと同じで、他の変換を適用する前にリソースをフィルタリングを行うために使用できます。

GET /products/:productId/variants?$apply=filter(price.amount gt 100)

変換: 並び替え (orderby)​

orderby 変換は、取得したリソースリストを並び替えるために使用されます。orderby の内容は $orderby クエリパラメータと同じで、他の変換を適用する前にリソースを並び替えるために使用できます。

GET /products?$apply=orderby(createdAt desc)

変換: 上位 (top)​

top 変換は、返されるリソースの数を制限するために使用されます。

GET /products?$apply=top(5)