OData を使用してデータのクエリを実行する
すべてのクエリはエンティティのコレクションで始まります。 エンティティ コレクションは次のようなものです:
- EntitySetリソース: Web API
EntitySetコレクションの1つ。 - フィルター処理されたコレクション: 特定のレコードの コレクション値ナビゲーション プロパティ によって返されるエンティティのセット。
- 拡張されたコレクション値ナビゲーション プロパティ。
- 関数 によって返されるコレクション。
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>
[
}
ヒント
これらの値は通常、テーブルの複数名ですが、異なる場合もあります。 このリクエストの結果を使用して、正しい EntitySet リソース名を使用していることを確認します。
たとえば、 accounts EntitySetリソースから始めて、 アカウント エンティティ タイプ からデータを取得します。
GET [Organization URI]/api/data/v9.2/accounts
フィルターしたコレクション
指定したレコードのコレクション値ナビゲーション プロパティで表されるエンティティの、任意のコレクションをクエリできます。 たとえば、特定のユーザーが OwningUser である アカウント エンティティ タイプ からデータを取得する場合は、指定された user_accounts systemuser レコードの コレクション値ナビゲーション プロパティを使用できます。
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"
}
]
}
クエリを絞り込む
クエリを開始するテーブルを選択した後、クエリを調整して必要なデータを取得します。 次の記事では、クエリを完了する方法について説明します。
| 記事 | Task |
|---|---|
| 列を選択する | 返すデータの列を指定します。 |
| テーブルの結合 | 結果としてどの関連テーブルを返すかを指定します。 |
| 行を並べ替える | 返す行の並べ替え順を指定します。 |
| 行のフィルター | 返すデータの行を指定します。 |
| ページの結果 | 各リクエストで返すデータの行数を指定します。 |
| データの集計 | 返されたデータのグループ化と集計を行う方法。 |
| 行数をカウントする | 返された行数を取得する方法。 |
| パフォーマンスの最適化 | パフォーマンスを最適化する方法 |
OData クエリ オプション
これらのオプションを使用して、コレクションから返される結果を変更します。 次の表では、Dataverse Web API がサポートする OData クエリ オプションについて説明します。
| 回答内容 | 用途 | 詳細情報 |
|---|---|---|
$select |
エンティティや複合型ごとに特定のプロパティ セットを要求します。 | 列を選択する |
$expand |
取得したリソースに合わせて、含めるべき関連リソースを指定します。 | テーブルの結合 |
$orderby |
特定の順序でリソースを要求します。 | 行を並べ替える |
$filter |
リソースのコレクションをフィルターします。 | 行のフィルター |
$apply |
データを集約し、グループ化します。 | データの集計 |
$top |
クエリしたコレクションの、結果に含めるべき項目の数を指定します。 | 行数を制限する |
$count |
応答のリソースに含まれる、一致するリソースの件数を要求します。 | 行数をカウントする |
複数のオプションを適用するには、クエリ オプションとリソース パスを疑問符 (?) で区切ります。 最初のオプションの後のオプションはアンパサンド (&) で区切ります。 オプション名は大文字と小文字が区別されます。
クエリ オプションを持つパラメーター エイリアスを使用します
次のパラメーター エイリアスを、$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クエリ オプションを多数含めると、制限に達する可能性があります。 ODataクエリ オプションをURLからリクエストの本文に移動する手段として、 $batch リクエストを使用して POST 操作を実行できます。この場合、制限は2倍になります。 $batch 内での GET 要求の送信では、最大 64 KB (65,536 文字) の長さの URL を使用できます。 Web APIを使用したバッチ操作の詳細については、 をご覧ください。
行数の制限
返される行数を制限するには、 $top ODataクエリ オプションを使用します。 この制限がない場合、 Dataverse 最大5,000行が返されます。
または、ページングを使用して、返すレコードの数を指定します。 データのページを要求するときは、 $top を使用しないでください。 ページングされた結果をリクエストする方法を解説します
制限
FetchXmlを使用して実行できるが、ODataではサポートされていない操作がいくつかあります。
関係のないテーブルを結合 することはできません。 ODataでは、データ モデル内の リレーションシップ の一部であるナビゲーション プロパティを使用してテーブルを結合するために、
$expandクエリ オプションのみを使用できます。集計の制限 には、ODataを使用した集計に関する次の制限がリストされています。
テーブル間の列比較を実行します。 ODataは、 同じ行の列値のフィルタリング をサポートしていますが、それらは同じテーブル内にある必要があります。
選択列のデフォルトの並べ替え順序を上書きする必要はありません。 選択列を並べ替えるときのデフォルトの動作では、ローカライズされたラベル値ではなく整数値が使用されます。
Late Materialize クエリ パフォーマンス最適化は使用できません。
コミュニティ ツール
注意
コミュニティによって作成されたツールは、Microsoft によってサポートされていません。 コミュニティ ツールに関する質問や問題は、ツールの公開元にお問い合わせください。
Dataverse REST Builder は、クエリの作成など、 Dataverse Web APIを使用してさまざまな操作を実行するのに役立つユーザー インターフェイスを提供するオープン ソース プロジェクトです。
XrmToolBox FetchXMLBuilder は、FetchXml要求を作成してテストするための無料ツールですが、同じデザイナー エクスペリエンスを使用してODataクエリのコードも生成します。
ODataバージョン4.0の機能
Dataverse Web APIはODataバージョン4.0サービスです。 OData 4.0仕様の次のセクションでは、データを取得する方法について説明します。
この記事とこのセクションの他の記事では、 Dataverse Web APIによって実装される4.0 OData仕様の部分と、それを使用して Dataverse からビジネス データを取得する方法について説明します。
注意
ODataバージョン4.01が最新バージョンです。 これにはバージョン4.0では利用できない拡張機能と追加機能が含まれており、そのため現在 Dataverse Web APIでは利用できません。
次の手順
列を選択する方法について説明します。
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。