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

  • [アーティクル]

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

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

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

データの取得

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

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

要求:

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ではサポートされていない操作がいくつかあります。

コミュニティ ツール

注意

コミュニティによって作成されたツールは、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 分かかります。 個人データは収集されません (プライバシー ステートメント)。