ODataを使用したページ結果
Prefer: odata.maxpagesize 要求ヘッダーを使用して、返されるレコードの数を制御します。 数値を指定しない場合、要求ごとに最大 5,000 件のレコードが返される可能性があります。 5000 件を超えるページ サイズは要求できません。
注意
Dataverse は $skip クエリ オプションをサポートしていないため、ページングに $top と $skip の組み合わせを使用できません。 $topクエリオプションを使用して行数を制限する方法について学習します
次の例では、最初 2 件の連絡先レコードのみを返します。
要求:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
応答:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"72201545\"",
"fullname": "Yvonne McKay (sample)",
"contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
},
{
"@odata.etag": "W/\"80648695\"",
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
要求したよりも多くのレコードが存在する場合、@odata.nextLink 注釈は次の例に示すように GET で使用できる URL を提供し、データの次のページを返します。
要求:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
応答:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"80648710\"",
"fullname": "Nancy Anderson (sample)",
"contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
},
{
"@odata.etag": "W/\"80648724\"",
"fullname": "Maria Campbell (sample)",
"contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
返された結果や @odata.nextLink URL 値をキャッシュし、それを使用して前のページに戻る必要があります。
@odata.nextLink URL 値を変更したり、クエリ オプションを追加したりしないでください。 さらに多くのページに対する後に続くすべての要求では、元の要求で使用したのと同じ odata.maxpagesize 基本設定値を必ず使用します。 結果が @odata.nextLink 注釈を含まなくなるまで、データのページングを続行できます。
前の例では、エンコードされた情報は、@odata.nextLink URL 値の $skiptoken パラメーターの値として設定されました。 サーバーは、このエンコードした情報を設定し、ページングを制御します。 エンコードされた情報を変更したり、さらにエンコードしたりしないでください。 指定された URL 値を使用して、次のページを取得します。
レコードをページングする際には $topクエリ オプションを使用しないでください。
$top クエリ オプションを使用して、返される結果の数を制限することができます。 $top を Prefer: odata.maxpagesize 要求ヘッダーとともに使用しないでください。 両方とも含めると $top は無視されます。
次の例では、最初 3 件のアカウント行のみを返します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3
ページングと並び順
ページの順序は、データをページングする際に大きな違いをもたらします。 結果の順序に関する情報があいまいな場合、Dataverse はページングされたデータを一貫して効率的に返すことができません。
クエリの順序を指定します。 FetchXml では、クエリに順序要素を追加しない場合、Dataverse がテーブルの主キーに基づいて順序を追加します。 ただし、QueryExpression の場合は異なり、クエリで distinct 結果を指定すると、主キー値が返されないため、Dataverse はこの既定の順序を追加することはできません。 ページングの順序を指定してください。 順序を指定しないと、distinct クエリの結果がランダムな順序で返される可能性があります。 OData では個別の結果を返すオプションは提供されていませんが、ページ化された結果を取得するときには順序を適用する必要があります。
ページングは動的です。 各リクエストは受信時に独立して評価されます。 ページング Cookie は Dataverse に前のページを伝えます。 このページング Cookie データを使用すると、Dataverse は前のページの最後のレコードの次のレコードから開始できます。
ページングは今後も最適に機能します。 以前に取得したページに戻って取得すると、最後にページを取得してからの間にレコードが追加、削除、または変更されている可能性があるため、結果が異なる可能性があります。 つまり、ページ サイズが 50 で前に戻ると、50 レコードが取得されますが、それらは同じ 50 レコードではない可能性があります。 データ セットのページを進め続けると、すべてのレコードが一貫した順序で返されることが期待できます。
決定論的な順序付けが重要となります
決定的順序付け とは、順序を一貫して計算する方法があることを意味します。 指定されたレコードのセットでは、レコードは常に同じ順序で返されます。 一貫した順序とページングが必要な場合は、一意の値または列値の組み合わせをいくつか含め、それらが評価される順序を指定する必要があります。
非決定的な例
ここで nondeterministic のサンプルを見てみましょう。 このデータセットには 状態 と ステータス の情報のみが含まれ、オープン 状態 のレコードのみを返すようにフィルターされています。 結果は、ステータス によって次のように並べ替えられます。 最初の 3 ページが要求されます。 結果はこのようになります:
| 状態 | Status | ぺージ |
|---|---|---|
| 始 | アクティブです | 1 スタート |
| 始 | アクティブです | 1 |
| 始 | アクティブです | 1 終了 |
| 始 | アクティブです | |
| 始 | アクティブです | |
| 始 | 非アクティブ | |
| 始 | 非アクティブ |
ページング Cookie は、ページ上の最後のレコードに関する情報を保存します。 次のページが要求された場合、最初のページの最後のレコードは含まれません。 ただし、非決定的なデータを考えると、最初のページの他の 2 つのレコードが 2 番目のページに含まれていないという保証はありません。
決定的な順序付けを実現するには、一意の値または半一意の値を含む列に順序を追加します。
決定的な例
このクエリは非決定的なクエリと似ていますが、一意な値を含むケース ID 列を含んでいます。 ステータス順でもありますが、ケース ID の使用用途順でもあります。 結果はこのようになります:
| 状態 | Status | サポート案件 ID | ぺージ |
|---|---|---|---|
| 始 | アクティブです | Case-0010 | 1 スタート |
| 始 | アクティブです | Case-0021 | 1 |
| 始 | アクティブです | Case-0032 | 1 終了 |
| 始 | アクティブです | Case-0034 | |
| 始 | アクティブです | Case-0070 | |
| 始 | 非アクティブ | Case-0015 | |
| 始 | 非アクティブ | Case-0047 |
次のページでは、cookie は最初のページの最後のレコードとして Case-0032 を保存しているので、2 ページ目はそのレコードの次のレコードから始まります。 結果はこのようになります:
| 状態 | Status | サポート案件 ID | ぺージ |
|---|---|---|---|
| 始 | アクティブです | Case-0010 | 1 スタート |
| 始 | アクティブです | Case-0021 | 1 |
| 始 | アクティブです | Case-0032 | 1 終了 |
| 始 | アクティブです | Case-0034 | 2 スタート |
| 始 | アクティブです | Case-0070 | 2 |
| 始 | 非アクティブ | Case-0015 | 2 終了 |
| 始 | 非アクティブ | Case-0047 |
このクエリは一意の列値を順序付けするため、順序は一貫しています。
データをページングするときの注文のベスト プラクティス
注意
可能な場合、クエリはテーブルの主キーに基づいて順序付けされる必要があります。 Dataverse は、既定で主キーの順序付けに最適化されています。 一意でないフィールドまたは複雑なフィールドで順序付けすると、過剰なオーバーヘッドが発生し、クエリが遅くなります。
アプリケーションで表示するために限られたデータセットを取得する場合、または 5,000 行以上のデータを返す必要がある場合は、結果をページングする必要があります。 結果の順序を決定する際の選択によって、取得するデータの各ページの行が他のページと重なるかどうかが決まります。 適切に順序付けしない場合、同じレコードが複数のページに表示される可能性があります。
同じレコードが複数のページに表示されないようにするには、次のベスト プラクティスを適用します:
一意の識別子を持つ列を含めることをお勧めします。 例:
- テーブルの主キー列
- オートナンバー列
- ユーザー/連絡先 ID
一意の識別子を持つ列を含めることができない場合は、一意の組み合わせになる可能性が最も高い複数のフィールドを含めます。 例:
- 名 + 姓 + メールアドレス
- 姓名 + メールアドレス
- メールアドレス + 会社名
データをページングする際の注文のアンチパターン
避けるべき順序の選択肢は次のとおりです:
一意識別子を含まない並び順
計算フィールドの注文
次のような一意性を提供する可能性が低い単一または複数のフィールドを持つ並び順:
- 状態と進捗状況
- 選択肢または、はい/いいえ
- 値自体に名前を付けます。 例:
name、firstname、lastname。 - タイトル、説明、複数行テキストなどのテキスト フィールド
- 一意でない数値フィールド
次の手順
データ集計の方法について解説します。
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。