次の方法で共有

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

行数の制限

返される行数を制限するには、$topOData クエリ オプションを使用します。 この制限がない場合、Dataverse が最大 5,000 行が返します。

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

制限

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

コミュニティ ツール

注意

コミュニティによって作成されたツールは、Microsoft によってサポートされていません。 コミュニティ ツールに関する質問や問題は、ツールの公開元にお問い合わせください。

Dataverse REST Builder は、クエリの作成など、 Dataverse Web API を使用してさまざまな操作を実行するのに役立つユーザー インターフェイスを提供するオープン ソース プロジェクトです。

XrmToolBoxFetchXMLBuilder は、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 では利用できません。

次の手順

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

列を選択する