OData を使用してデータのクエリを実行する

すべてのクエリはエンティティのコレクションで始まります。 エンティティ コレクションは次のようなものです:

• EntitySet リソース: Web API EntitySet コレクションのひとつです。
• フィルターしたコレクション: 特定のレコードに対して コレクション値ナビゲーション プロパティ ごとに返される一連のエンティティ。
• 展開したコレクション値ナビゲーション プロパティ。
• 関数によって返されるコレクション。

EntitySetリソース

ご利用の環境で利用可能なすべての EntitySet リソースを見つけるには、Web API サービス ドキュメント に GET リクエストを送信します:

要求:

GET [Organization URI]/api/data/v9.2/
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

たとえば、accounts EntitySet リソースから開始して、アカウント エンティティ型からデータを取得します。

GET [Organization URI]/api/data/v9.2/accounts

フィルターしたコレクション

指定したレコードのコレクション値ナビゲーション プロパティで表されるエンティティの、任意のコレクションをクエリできます。 たとえば、特定のユーザーが OwningUser であるアカウント エンティティ タイプからデータを取得する場合は、指定の systemuser レコードから user_accounts コレクション値のナビゲーション プロパティを使用できます。

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

コレクション値のナビゲーション プロパティの名前を見つけます:

• Dataverse テーブルと関係については Web API Entity Type Reference を確認できます
• カスタム テーブルやリレーションシップについては、$metadata サービス ドキュメント で コレクション値ナビゲーション プロパティ を探します

データの取得

コレクションからデータを取得するには、 GET 要求をコレクション リソースに送信します。 次の例では、アカウント エンティティ タイプからデータを取得しています。

この例では、次のことも示しています。

• $selectを使用して返される列を制限する。 列の選択に関する詳細情報
• $orderby を使用した並び順の結果。 並び順列に関する詳細情報
• $topを使用して返される行を制限する。 行数の制限について学習する
• 要求ヘッダーを使用してフォーマットされた値を表示する: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"。 書式設定された値について説明します

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,statecode,statuscode&$orderby=name&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,statecode,statuscode)",
   "value": [
      {
         "@odata.etag": "W/\"112430907\"",
         "name": "A. Datum Corporation (sample)",
         "statecode@OData.Community.Display.V1.FormattedValue": "Active",
         "statecode": 0,
         "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
         "statuscode": 1,
         "accountid": "4b757ff7-9c85-ee11-8179-000d3a9933c9"
      }
   ]
}

クエリを絞り込む

クエリを開始するテーブルを選択した後、クエリを調整して必要なデータを取得します。 次の記事では、クエリを完了する方法について説明します。

OData クエリ オプション

これらのオプションを使用して、コレクションから返される結果を変更する。 次の表では、Dataverse Web API がサポートする OData クエリ オプションについて説明します。

複数のオプションを適用するためには、クエリ オプションとリソース パスを疑問符 (?) で区切ります。 最初の後の各オプションはアンパサンド (&) で区切ります。 オプション名は大文字と小文字が区別されます。

クエリ オプションを持つパラメーター エイリアスを使用します

次のパラメーター エイリアスを、$expand オプション内ではなく、$filter と $orderby クエリ オプションで使用できます。 パラメーターのエイリアスを使用すると、要求の中で同じ値を複数回使用することができます。 エイリアスがの値が割り当てられていない場合は、null であると判断します。

パラメーター エイリアスなし:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

パラメーター エイリアスあり:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

また、関数を使用するとき、パラメーター エイリアスを使用することもできます。 Web API 機能の使用方法を説明します

サポートされていない OData クエリ オプション

Dataverse Web API は、次の OData クエリ オプション: $skip、$search、$format をサポートしていません。

URL 長さ制限

GET 要求内の URL の長さは 32 KB (32,768 文字) に制限されています。 URL にパラメーターとして複雑な OData クエリ オプションを多数含めると、制限に達する可能性があります。 長さ制限が 2 倍の要求本体に URL から OData クエリ オプションを移動する方法として、POST 要求を使用する $batch オペレーションを実行することができます。 $batch 内での GET 要求の送信では、最大 64 KB (65,536 文字) の長さの URL を使用できます。 Web API を使用したバッチ操作の詳細。

行数の制限

返される行数を制限するには、$topOData クエリ オプションを使用します。 この制限がない場合、Dataverse 最大 5,000 の標準テーブル行と 500 のエラスティック テーブル行を返します。

または、ページングを使用して、返すレコードの数を指定します。 データのページを要求するときは、$top を使用しないでください。 ページングされた結果をリクエストする方法を解説します

制限

FetchXml を使用して実行できるが、OData がサポートしていない操作がいくつかあります。

• テーブルリレーションシップのない結合をすることはできません。 OData では、データ モデル内のリレーションシップの一部であるナビゲーション プロパティを使用してテーブルを結合するための $expand クエリ オプションのみが許可されます。

• ネストされた $expand を N:N の関係で使用することはできません。

• 集計の制限事項には、OData を使用した集計に関する以下の制限が記載されています:

  • CountColumn で一意の数値を取得する
  • 日付でグループ化する場合のタイム ゾーン
  • 行の集計
  • クエリごとの制限

• テーブル間の列比較を実行します。 OData は、同じ行の列値のフィルタリングをサポートしていますが、同じテーブル内にある必要があります。

• 選択肢列の既定の並べ替え順序を上書きする必要はありません。 選択肢列を並べ替えるときの既定の動作では、ローカライズされたラベル値ではなく整数値が使用されます。

• Late Materialize クエリ パフォーマンス最適化は使用できません。

コミュニティ ツール

Dataverse REST Builder は、クエリの作成を含め、Dataverse Web API を使用して多くのことを行う際に役立つユーザー インターフェイスを提供するオープンソースのプロジェクトです。

XrmToolBoxFetchXMLBuilder は、FetchXml リクエストを構成してテストするための無料のツールですが、同じデザイナー エクスペリエンスを使用して OData クエリのコードも生成します。

OData バージョン 4.0 の機能

Dataverse Web API は OData バージョン 4.0 サービスです。 OData 4.0 仕様の次のセクションでは、データを取得する方法について説明します。

• OData バージョン 4.0。 パート 1: Protocol Plus Errata 03. 11.2 データの要求
• OData バージョン 4.0。 パート 2: URL Conventions Plus Errata 03 5 クエリ オプション

この記事とこのセクションの他の記事では、Dataverse Web API で実装されている 4.0 OData 仕様の部分と、それを使用して Dataverse からビジネス データを取得する方法について説明します。

次の手順

列を選択する方法について説明します。