OData を使用した結果のページ分け

Prefer: odata.maxpagesize要求ヘッダーと共に OData ページングを使用して、Microsoft Dataverse Web API から返されるレコードの数を制御します。 数値を指定しない場合、各要求は最大 5,000 行のテーブル行を返す可能性があります。 標準テーブルとエラスティック テーブルの両方で、最大ページ サイズを 5,000 まで指定できます。 このサービスでは、標準テーブルとエラスティック テーブルの両方で 5,000 を超える最大ページ サイズ要求が無視されます。

Note

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 注釈を含まなくなるまで、データのページングを続行できます。

前の例では、$skiptoken URL 値の @odata.nextLink パラメーターの値にエンコードされた情報が含まれています。 サーバーは、このエンコードした情報を設定し、ページングを制御します。 エンコードされた情報を変更したり、さらにエンコードしたりしないでください。 指定された URL 値を使用して、次のページを取得します。

レコードのページング中は $top クエリ オプションを使用しないでください

$top クエリ オプションを使用して、返される結果の数を制限することができます。 $top を Prefer: odata.maxpagesize 要求ヘッダーとともに使用しないでください。 両方とも含めると $top は無視されます。

次の例では、最初 3 件のアカウント行のみを返します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3

PowerShell RetrieveAll の例

次の例 Get-AllRecords PowerShell 関数は、フィルター条件だけで絞り込まれたテーブルのすべてのレコードを取得する方法を示しています。

この関数は、Get-NextLink で説明されている 関数と Get-Records 関数に依存します。

<#
.SYNOPSIS
Retrieves all records matching an OData query.

.DESCRIPTION
Uses Get-Records for the first page and Get-NextLink for subsequent pages.
Follows each @odata.nextLink unchanged, using the same maximum page size.
Returns the combined records only after all requests succeed.

.PARAMETER setName
The entity set name, such as contacts.

.PARAMETER query
The OData query string, beginning with ?, or a related collection path as accepted
by Get-Records. Do not use the top-level $top or $skip query options with paging.
Include a deterministic $orderby, preferably including the primary key.
Use single quotes to prevent PowerShell from expanding OData option names.

.PARAMETER maxPageSize
Maximum records per page, from 1 to 5000. Defaults to 5000.

.EXAMPLE
$contacts = @(Get-AllRecords -setName 'contacts' `
   -query '?$select=fullname,jobtitle&$orderby=fullname,contactid' -maxPageSize 1000)

.OUTPUTS
The records themselves, not a Web API response envelope. Use @() to collect an
array even when zero or one record matches. Errors propagate to the caller.
#>
function Get-AllRecords {
   param (
      [Parameter(Mandatory)]
      [String]
      $setName,
      [Parameter(Mandatory)]
      [String]
      $query,
      [ValidateRange(1, 5000)]
      [int]
      $maxPageSize = 5000
   )

   if ($query -match '(?i)[?&](?:\$|%24)(top|skip)=') {
      throw 'The top-level $top and $skip query options cannot be used with paging.'
   }

   $records = [System.Collections.Generic.List[object]]::new()
   $response = Get-Records -setName $setName -query $query -maxPageSize $maxPageSize

   while ($true) {
      foreach ($record in $response.value) {
         $records.Add($record)
      }

      $nextLink = $response.'@odata.nextLink'
      if ([string]::IsNullOrWhiteSpace($nextLink)) {
         break
      }
      $response = Get-NextLink -nextLink $nextLink -maxPageSize $maxPageSize
   }

   return $records.ToArray()
}

並び順とページング

ページの順序は、データをページングする際に大きな違いをもたらします。 結果の順序に関する情報があいまいな場合、Dataverse はページングされたデータを一貫して効率的に返すことができません。

クエリの順序を指定します。 FetchXml では、クエリに順序要素を追加しない場合、Dataverse がテーブルの主キーに基づいて順序を追加します。 ただし、QueryExpression の場合は異なり、クエリで distinct 結果を指定すると、主キー値が返されないため、Dataverse はこの既定の順序を追加することはできません。 ページングの順序を指定してください。 順序を指定しないと、distinct クエリの結果がランダムな順序で返される可能性があります。 OData では個別の結果を返すオプションは提供されていませんが、ページ化された結果を取得するときには順序を適用する必要があります。

ページングは動的です。 各リクエストは受信時に独立して評価されます。 ページング Cookie は Dataverse に前のページを伝えます。 このページング Cookie データを使用すると、Dataverse は前のページの最後のレコードの次のレコードから開始できます。

ページングは今後も最適に機能します。 以前に取得したページに戻って取得すると、最後にページを取得してからの間にレコードが追加、削除、または変更されている可能性があるため、結果が異なる可能性があります。 つまり、ページ サイズが 50 で前に戻ると、50 レコードが取得されますが、それらは同じ 50 レコードではない可能性があります。 データ セットのページを進め続けると、すべてのレコードが一貫した順序で返されることが期待できます。

決定論的な順序付けが重要となります

決定的順序付け とは、順序を一貫して計算する方法があることを意味します。 指定されたレコードのセットでは、レコードは常に同じ順序で返されます。 一貫した順序とページングが必要な場合は、一意の値または列値の組み合わせをいくつか含め、それらが評価される順序を指定する必要があります。

非決定的な例

ここで nondeterministic のサンプルを見てみましょう。 このデータセットには 状態 と ステータス の情報のみが含まれ、オープン 状態 のレコードのみを返すようにフィルターされています。 結果は、ステータス によって次のように並べ替えられます。 最初の 3 ページが要求されます。 結果はこのようになります:

状態 ステータス ページ
Open アクティブ 1 スタート
Open アクティブ 1
Open アクティブ 1 終了
Open アクティブ
Open アクティブ
Open 非アクティブ
Open 非アクティブ

ページング Cookie は、ページ上の最後のレコードに関する情報を保存します。 次のページが要求された場合、最初のページの最後のレコードは含まれません。 ただし、非決定的なデータを考えると、最初のページの他の 2 つのレコードが 2 番目のページに含まれていないという保証はありません。

決定的な順序付けを実現するには、一意の値または半一意の値を含む列に順序を追加します。

決定的な例

このクエリは非決定的なクエリと似ていますが、一意な値を含むケース ID 列を含んでいます。 ステータス順で並べられているだけでなく、ケース IDでも並べられています。 結果はこのようになります:

状態 ステータス ケース ID ページ
Open アクティブ Case-0010 1 スタート
Open アクティブ Case-0021 1
Open アクティブ Case-0032 1 終了
Open アクティブ Case-0034
Open アクティブ Case-0070
Open 非アクティブ Case-0015
Open 非アクティブ Case-0047

次のページでは、cookie は最初のページの最後のレコードとして Case-0032 を保存しているので、2 ページ目はそのレコードの次のレコードから始まります。 結果はこのようになります:

状態 ステータス ケース ID ページ
Open アクティブ Case-0010 1 スタート
Open アクティブ Case-0021 1
Open アクティブ Case-0032 1 終了
Open アクティブ Case-0034 2 開始
Open アクティブ Case-0070 2
Open 非アクティブ Case-0015 2 終了
Open 非アクティブ Case-0047

このクエリは一意の列値を順序付けするため、順序は一貫しています。

ページング処理におけるデータの順序に関するベストプラクティス

Note

可能な場合、クエリはテーブルの主キーに基づいて順序付けされる必要があります。 Dataverse は、既定で主キーの順序付けに最適化されています。 一意でないフィールドまたは複雑なフィールドで順序付けすると、過剰なオーバーヘッドが発生し、クエリが遅くなります。

アプリケーションに表示する限定されたデータ セットを取得する場合、または 5,000 行 (エラスティック テーブルの場合は 500 行) を超えるデータを返す必要がある場合は、結果をページングする必要があります。 結果の順序を決定する際の選択によって、取得するデータの各ページの行が他のページと重なるかどうかが決まります。 適切に順序付けしない場合、同じレコードが複数のページに表示される可能性があります。

同じレコードが複数のページに表示されないようにするには、次のベスト プラクティスを適用します:

一意の識別子を持つ列を含めることをお勧めします。 例:

  • テーブルの主キー列
  • オートナンバー列
  • ユーザー/連絡先 ID

一意の識別子を持つ列を含めることができない場合は、一意の組み合わせになる可能性が最も高い複数のフィールドを含めます。 例:

  • 名 + 姓 + メールアドレス
  • 姓名 + メールアドレス
  • メールアドレス + 会社名

データをページングする際の順序に関するアンチパターン

避けるべき順序の選択肢は次のとおりです:

  • ユニーク識別子を含まない注文

  • 計算フィールドの注文

  • 一意性が提供される可能性が低い単一または複数のフィールドを含む注文:

    • 状態と進捗状況
    • 選択肢または、はい/いいえ
    • 値を単独で名前付けします。 例: name、firstname、lastname。
    • タイトル、説明、複数行テキストなどのテキスト フィールド
    • 一意でない数値フィールド

次のステップ

データ集計の方法について解説します。