Web API を使用したデータのクエリ

  • [アーティクル]

Web API を使用して Dataverse テーブルに対するクエリを作成する場合は、次の決定を下す必要があります。

決定 Description
列を選択する どのデータ列を返すか
テーブルの結合 どの関連テーブルを結果に含めるか
行を並べ替える どの順序で結果を返すか
行のフィルター どのデータ行を返すか
ページの結果 何件のデータ行を返すか
データの集計 返されたデータのグループ化と集計を行う方法
行数をカウントする 行数の数え方

この記事では、テーブルで見つかったデータのクエリを解説します。 Web API を使用して、テーブル定義またはエンティティ メタデータに関するデータをクエリすることもできます。 データの構造が異なるため、ここで説明する機能のほとんどが適用されません。 詳細情報: Web API を使用してテーブル定義をクエリ と スキーマ定義のクエリ

エンティティ コレクション

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

EntitySet リソース

環境で利用できるすべての EntitySet リソースを見つける場合は、GET 要求を Web API サービス ドキュメント に送信します。

要求:

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 リソース名を使用していることを確認します。

アカウント EntityType からデータを取得するには、accounts EntitySet リソースから始めます。

GET [Organization URI]/api/data/v9.2/accounts?$select=name

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

指定したレコードのコレクション値ナビゲーション プロパティで表されるエンティティの、任意のコレクションをクエリできます。

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

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

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

OData クエリ オプション

次の表では、Dataverse Web API がサポートする OData クエリ オプションについて説明します。

回答内容 用途 詳細情報
$select エンティティや複合型ごとに特定のプロパティ セットを要求します。 列を選択する
$expand 取得したリソースに合わせて、含めるべき関連リソースを指定します。 テーブルの結合
$filter リソースのコレクションをフィルターします。 行のフィルター
$orderby 特定の順序でリソースを要求します。 行を並べ替える
$apply データを集約し、グループ化します。 データの集計
$top クエリしたコレクションの、結果に含めるべき項目の数を指定します。 データのページを取得するときは、$top を使用しないでください。 $top クエリ オプションの使用
$count 応答のリソースに含まれる、一致するリソースの件数を要求します。 行数をカウントする

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

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

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

次のパラメーター エイリアスを、$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 機能を使用

列を選択する

重要

データをクエリする場合、パフォーマンスを最適化するために返されるデータの量を制限することが重要です。 必要なデータを含む列のみを選択してください。

$select クエリ オプション を使用して、クエリで返す列を選択します。 OData では、すべての列をプロパティ として表現します。 $select クエリ オプションを含めない場合、すべてのプロパティを返します。

次の例では、accounts EntitySet リソースの 1 つの行から、name と revenue のプロパティを要求します:

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
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#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

主キー プロパティは常に返されるため、$select に含める必要はありません。 この例では accountid が主キーです。

他のプロパティ値も含む場合があります。 この場合、revenue は通貨プロパティであるため、関連する 通貨 (TransactionCurrency) テーブル/エンティティ参照 の _transactioncurrencyid_value 検索プロパティ を含みます。

どのプロパティを利用できますか?

エンティティで使用できるプロパティは、すべて $metadata サービス ドキュメント で確認できます。 詳細情報: Web API プロパティ

Dataverse に含まれるエンティティ タイプは、Web API Entity Type Reference で説明されています。

ヒント

どのプロパティを利用できるかをすばやく発見する最も簡単な方法は、$select を使用せずに 1 の値で $top クエリ オプションを使用し、要求を送信することです。

書式設定された値

書式設定した値とは、サーバーで生成される文字列値であり、これはアプリケーションで使用できます。 書式設定した値を次に示します。

  • 単一選択、複数選択、はい/いいえ、状態、ステータス列のローカライズされたラベル
  • 検索と所有者のプロパティに対するプライマリ名の値
  • 通貨記号を含む通貨値
  • ユーザーのタイムゾーンに合わせて書式設定した日付値

書式設定された値を結果に含める際は、次の要求ヘッダーを使用します。

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

書式設定した値は、要求できるいくつかの注釈の 1 つです。 Prefer: odata.include-annotations="*" を使用すると注釈をすべて含めます。 詳細情報: 注釈の要求

書式設定された値が、次の規則に沿った注釈付きのレコードと共に返されます。

<property name>@OData.Community.Display.V1.FormattedValue

例:

要求:

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

次の表では、要求されたプロパティに対して返される値とフォーマットされた値について説明します。

Property 価値 書式設定された値
name Litware, Inc. (sample) None
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd None

応答:

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,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

検索プロパティ データ

検索プロパティ が複数テーブルまたはポリモーフィック、リレーションシップを表す場合、どのテーブルに関連データが含まれているかを判断するために特定の注釈を要求する必要があります。

たとえば多くのテーブルは、ユーザーやチームが所有する可能性があるレコードを含みます。 所有権データは、ownerid という名前の検索列に保存されます。 この列は OData の単一値ナビゲーション プロパティです。 $expand を使用して結合を作成し、この値を取得できますが、$select は使用できません。 ただし、対応する _ownerid_value 検索プロパティを $select で使用できます。

_ownerid_value 検索プロパティを ``$select` に含めると、GUID 値が返されます。 レコードの所有者がユーザーかチームかを、この値から判断できません。 このデータを取得する場合は、注釈を要求する必要があります。

これらの注釈を結果に含める際は、次の要求ヘッダーを使用します。

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

ヒント

または Prefer: odata.include-annotations="*" を使用して、注釈をすべて含めます。 詳細情報: 注釈の要求

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

次の応答は、異なるアカウント レコードを 2 つ返します。 team は 1 つ目のものを所有し、systemuser は 2 つ目のものを所有します。 _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname 注釈は、次の情報を提供します。

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname は関連するテーブルの論理名です。
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty は、対応する単一値ナビゲーション プロパティの名前です。 別の要求でこの値を使用する $expand を使用し、さらに多くのデータを関連レコードから取得できます。

テーブルの結合

関連テーブル レコードから返されるデータを制御するには、ナビゲーション プロパティで $expand クエリ オプション を使用します。

  • クエリには最大 15 個の $expand オプションを含めることができます。 各 $expand オプションは、パフォーマンスに影響を与える可能性のある結合を作成します。
  • コレクション値ナビゲーション プロパティを展開するクエリは、最新の変更を反映しないそれらのプロパティのキャッシュされたデータを返すことがあります。 ブラウザのキャッシュを上書きするには、If-None-Match ヘッダーと値 null を使用することをお勧めします。 詳細については、HTTP ヘッダー をお読みください。

次の表では、特定の $expand オプションに適用できるクエリ オプション について説明します。

回答内容 Description
$select どのプロパティが返されたかを選択します。 詳細情報: 列の選択
$filter コレクション値ナビゲーション プロパティの場合は、返されたレコードを制限します。 詳細情報: 行のフィルター
$orderby コレクション値のナビゲーション プロパティの場合は、返されたレコードの順序をコントロールします。 入れ子になった $expand は、サポートされていません。 詳細情報: コレクション値のナビゲーション プロパティで入れ子になった $expand
$top コレクション値のナビゲーション プロパティの場合は、返されたレコードの数を制限します。 入れ子になった $expand は、サポートされていません。 詳細情報: コレクション値のナビゲーション プロパティで入れ子になった $expand
$expand 関連するエンティティのセットでナビゲーション プロパティを拡張します。 $expand 内で $expand を使用することは、入れ子になった $expand と呼ばれます。 詳細: 単一値ナビゲーション プロパティの入れ子になった拡張 & コレクション値のナビゲーション プロパティで入れ子になった $expand

OData バージョン 4.0 パート 1: プロトコル プラス Errata 02 の 11.2.4.2.1 拡張オプション セクションに記載されているクエリ オプションの一部です。 オプション $skip、$count、$search、および $levelsは、Dataverse Web API ではサポートされていません。

$expand のあるこれらのオプションは、ナビゲーション プロパティの名前の後に括弧で囲んで追加して使用します。 各オプションをセミコロン (;) で区切ります。

たとえば、以下のクエリ:

  • account.name プロパティを要求します

  • 以下を要求する AccountTasks コレクション値ナビゲーション プロパティを結合します。

    • task.subject プロパティ
    • task.subject が文字列 "Task" を含む場所
    • task.createdon の日付で降順に並べ替え済み
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)

$selectで列を制限する

他のクエリと同様に、$expand を使用する場合は、$select を使用して返される列を常に制限します。 たとえば、次のリクエストは、account エンティティ型から拡張された結果の contact.fullname と task.subject の値を返します。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=1

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
            },
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80649460\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

ナビゲーション プロパティには次の 2 種類があることにご注意ください。 詳細情報: Web API ナビゲーション プロパティ

  • 単一値 ナビゲーション プロパティは、多対一関係をサポートし、別のレコードに対する参照が設定できるような検索属性に対応します。

  • コレクション値 ナビゲーション プロパティは 1 対多または多対多の関連付けに対応します。

コレクション値のナビゲーション プロパティを展開すると、応答のサイズが拡大し、その予測が困難になる場合があります。 返されるデータの量をコントロールする制限を含めることが重要です。 ページングを使用して、レコード件数を制限できます。 詳細情報: ページの結果

コレクション値のナビゲーション プロパティに適用される入れ子になった $expand オプションにページングが適用される方法には、大きな違いがあります。 詳細情報: コレクション値のナビゲーション プロパティを展開する

単一値のナビゲーション プロパティを展開する

次の例は、取引先責任者とレコードを作成したユーザーを含む取引先担当者レコードを取得する方法を示しています。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)  
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Susanna Stubberod (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Nancy Anderson (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

createdby 単一値ナビゲーション プロパティは、systemuser EntityType のインスタンスを返します。 systemuserid と ownerid のプロパティを両方とも返します。 この理由は、systemuser が プリンシパル EntityType から継承し、この継承によって ownerid プライマリ キーを チーム EntityType と共有するためです。

ただし、ユーザー (SystemUser) テーブル は SystemUserId の主キーを含みます。 systemuserid と ownerid のプロパティは両方とも同じ値を含みます。 詳細: EntityType の継承

参照を返す

データを返す代わりに、/$ref オプションを使用して単一値ナビゲーション プロパティを展開することにより、関連レコードへの参照またはリンクを返すこともできます。 次の例では、各取引先責任者の URL を含む @odata.id プロパティを持つ JSON オブジェクトを返します。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

単一値ナビゲーション プロパティのある /$ref オプションのみを使用できます。 コレクション値ナビゲーション プロパティで使用する場合、以下のエラーが表示されます。

{
    "error": {
        "code": "0x80060888",
        "message": "Expand with $ref is only supported on lookup type navigation property."
    }
}

単一値ナビゲーション プロパティの入れ子になった展開

$expand オプションを別の $expand オプション内に入れ子にすることで、単一値ナビゲーション プロパティを複数のレベルに展開することができます。

次のクエリは、task レコードを返し、関連する contact、contact に関連する account、そして account レコードを作成した systemuser を展開します。

要求:

GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
 $expand=parentcustomerid_account($select=name;
  $expand=createdby($select=fullname)))  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
    "value": [
        {
            "@odata.etag": "W/\"80730855\"",
            "subject": "Task 1 for Susanna Stubberod",
            "activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        },
        {
            "@odata.etag": "W/\"80730861\"",
            "subject": "Task 2 for Susanna Stubberod",
            "activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

コレクション値のナビゲーション プロパティの展開

クエリ内の任意の場所で、コレクション値ナビゲーション プロパティのある入れ子になった $expand を使用するかどうかによって、応答に重大な違いが発生します。

入れ子になった $expand 単一 $expand
Paging 展開された行のページング。 EntitySet リソース でのみページングします。 展開された行の <property name>@odata.nextLink URL には、ページング情報は含まれません。
$top または $orderby がサポートされています いいえ はい

コレクション値ナビゲーション プロパティの単一 $expand

単一レベルの $expand のみを使用する場合、展開された行にはページングは適用されません。 Prefer: odata.maxpagesize 要求ヘッダーを含めると、ページングはクエリの EntitySet リソースにのみ適用されます。

展開されたコレクション値の各ナビゲーション プロパティは、ページング情報を含まない <property>@odata.nextLink URL を返します。 これはクエリ オプションを追加したリレーションシップの フィルターしたコレクション を表す URL です。 その URL を使用して別の GET 要求を送信すると、元の要求で返されたものと同じ行が返されます。 その要求にページングを適用できます。

展開したレコードにはページングが適用されないため、展開したコレクション値の各ナビゲーション プロパティに対して、最大 5000 件の関連レコードを返すことができます。 データとクエリによっては、大量のデータになる可能性があります。 大量のデータを返すとパフォーマンスに影響し、要求がタイムアウトになる可能性があります。作成するクエリには注意してください。 $top、$filter、および $orderby オプションを使用して、返されるレコードの総数をコントロールできます。

次の例には、アカウント レコードを取得する際の Account_Tasks と contact_customer_accounts の単一の展開が含まれています。 Prefer: odata.maxpagesize=1 要求ヘッダーにより、最初のページで 1 つのアカウント レコードのみが返されるようになります。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80730894\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730903\"",
                    "subject": "Task 2 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730909\"",
                    "subject": "Task 3 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
            "contact_customer_accounts": [
                {
                    "@odata.etag": "W/\"80648695\"",
                    "fullname": "Susanna Stubberod (sample)",
                    "_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

この応答を、入れ子になった $expand を含む次の例と比較してください。 応答例を水平にスクロールして、アカウント結果の @odata.nextLink URL のみにページング情報が含まれていることを確認します。

コレクション値ナビゲーション プロパティの入れ子になった $expand

入れ子になった $expand をクエリの任意の場所で使用し、Prefer: odata.maxpagesize 要求ヘッダーを含めた場合、展開された各コレクションにページングが適用されます。

展開されたコレクション値の各ナビゲーション プロパティは、ページング情報を含む <property>@odata.nextLink URL を返します。 その URL を使用して別の GET 要求を送信すると、元の要求で含まれていなかった次のレコード セットが返されます。

$top または $orderby オプションを使用して、入れ子になった $expand で返されるレコードの総数を制限することはできません。 これらのオプションを使用すると、次のエラーが返されます。

{
    "error": {
        "code": "0x80060888",
        "message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
    }
}

次の例は前の例に基づいており、同じデータを使用します。 唯一の違いは、連絡先の所有ユーザーを返すために、この入れ子になった $expand の URL を単一値のナビゲーション プロパティに追加することです: ;$expand=owninguser($select=fullname)。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname))
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "subject": "Task 1 for Litware",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
            "contact_customer_accounts": [
                {
                    "fullname": "Susanna Stubberod (sample)",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                    "owninguser": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

この応答を、入れ子になった $expand を使用しない前の例と比較してください。 この応答では、Prefer: odata.maxpagesize=1 要求ヘッダーは、Account_Tasks と一緒に返された task レコードに適応されます。 3 つではなく、1 つのタスクのみが返されます。 Account_Tasks@odata.nextLink URL は次の 2 つのタスクを返します。 応答例を水平にスクロールして、Account_Tasks@odata.nextLink、contact_customer_accounts@odata.nextLink、@odata.nextLink の URL にページング情報が含まれていることを確認します。

行を並べ替える

$orderby クエリ オプション を使用して、項目が返される順序を指定します。 asc または desc 接尾辞を使用して、それぞれ昇順または降順を指定します。 既定は昇順です。 以下の例では、アカウントの name プロパティと revenue プロパティを、revenue を昇順で、name を降順で取得します。

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

行のフィルター

$filter クエリ オプション を使用して、リソースのコレクションをフィルターします。

Dataverse は、$filter に設定した式によって、コレクションが含む各リソースを評価します。 その式が true と評価したレコードのみを応答で返します。 その式が false や null と評価する場合、またはユーザーがレコードへの読み取りアクセス許可を持っていない場合、レコードは返されません。

以下の表では、$filter 式で使用できる演算子と関数について説明します。

Description 詳細情報
比較演算子 プロパティと値を比較する際は演算子 eq、ne、gt、ge、lt、le を使用します。 比較演算子
論理演算子 and、or、not を使用して、より複雑な式を作成します。 論理演算子
グループ化演算子 括弧: () を使用して、複雑な式を評価する優先順位を指定します。 グループ化演算子
OData クエリ関数 contains、endswith、startswith 関数を使用して文字列値を評価します。 OData クエリ関数を使用する
Dataverse クエリ関数 ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 Dataverse クエリ関数
ラムダ式 関連するコレクションの値に基づいて式を作成します。 関連するコレクションの値でフィルターする

$filterで検索プロパティ を使用している場合は、フィルタリングされたコレクション を対応するコレクション値のナビゲーション プロパティで使用することもできます。 たとえば、次の 2 つのクエリは同じ結果を返します。

accounts?$filter=_owninguser_value eq '<systemuserid value>'&$select=name

systemusers(<systemuserid value>)/user_accounts?$select=name

比較演算子

以下の表では、プロパティと値を比較するために使用できる演算子について説明します。

Operator Description 例
eq 等しい $filter=revenue eq 100000
ne 等しくない $filter=revenue ne 100000
gt より大きい $filter=revenue gt 100000
ge 以上 $filter=revenue ge 100000
lt より小さい $filter=revenue lt 100000
le 以下 $filter=revenue le 100000

列の比較

比較演算子を使用して、同じ行が含むプロパティ値を比較できます。 同じ行内の値を比較するために使用できるのは比較演算子のみであり、列の型が一致する必要があります。 たとえば、次のクエリは、firstname が lastname に等しい連絡先を返します。

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

論理演算子

以下の表では、より複雑な式を作成するために使用できる論理演算子について説明します。

Operator Description 例
and 論理積 $filter=revenue lt 100000 and revenue gt 2000
or 論理和 $filter=contains(name,'(sample)') or contains(name,'test')
not 論理否定 $filter=not contains(name,'sample')

グループ化演算子

論理演算子で括弧 () を使用して、複雑な式を評価する優先順位を指定します。例えば:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Dataverse クエリ関数

ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 こうした関数は、次のテーブルで説明する特化した機能を提供します。

Group 関数
日付 InFiscalPeriod、InFiscalPeriodAndYear、InFiscalYear、InOrAfterFiscalPeriodAndYear、InOrBeforeFiscalPeriodAndYear、
Last7Days、LastFiscalPeriod、LastFiscalYear、LastMonth、LastWeek、LastXDays、LastXFiscalPeriods、LastXFiscalYears、
LastXHours、LastXMonths、LastXWeeks、LastXYears、LastYear、Next7Days、NextFiscalPeriod、NextFiscalYear、
NextMonth、NextWeek、NextXDays、NextXFiscalPeriods、NextXFiscalYears、NextXHours、NextXMonths、
NextXWeeks、NextXYears、NextYear、OlderThanXDays、OlderThanXHours、OlderThanXMinutes、OlderThanXMonths、
OlderThanXWeeks、OlderThanXYears、On、OnOrAfter、OnOrBefore、ThisFiscalPeriod、ThisFiscalYear、ThisMonth、ThisWeek、ThisYear、Today、Tomorrow、Yesterday
ID 値 EqualBusinessId、EqualUserId、NotEqualBusinessId、NotEqualUserId
階層 Above、AboveOrEqual、EqualUserOrUserHierarchy、EqualUserOrUserHierarchyAndTeams、EqualUserOrUserTeams、
EqualUserTeams、NotUnder、Under、UnderOrEqual
詳細: クエリ階層型データ
選択肢の列 ContainValues、DoesNotContainValues
詳細情報: 選択肢からデータをクエリする
次の範囲内 Between、NotBetween
後 In、NotIn
言語 EqualUserLanguage

注意

Contains 関数 は、全文インデックスをもった列で使用します。 全文インデックスをもった列を含むのは Dynamics 365 KBArticle (記事) テーブルのみです。 代わりに OData contains 関数を使用してください。

Web API Query Function Reference には完全なリストがあります。 各記事に記載された構文の例をコピーできます。

関数の完全修飾名を使用し、サービス名前空間 (Microsoft.Dynamics.CRM) を関数の名前に追加する必要があります。

各関数には、評価するプロパティを指定する PropertyName パラメータがあります。 一部の関数には、PropertyValue、PropertyValues、PropertyValue1、PropertyValue2 などのパラメーターが、さらに存在する場合があります。 これらのパラメーターが存在する場合、PropertyName パラメーターと比較する値を必ず指定します。

以下の例では、Between 関数 を使用して、従業員数が 5 ～ 2,000 の間の従業員数の取引企業の検索を示しています。

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

文字列値を使用してフィルターする

文字列値でフィルタリングするときは、次の点に留意してください。

  • 文字列値を使用するすべてのフィルターは、大文字と小文字を区別しません。
  • フィルター条件では特殊文字を URL エンコードする必要があります。 詳細: URL エンコード特殊文字
  • ワイルドカード文字を使用できますが、末尾に使用するべきではありません。 詳細情報: ワイルドカード文字を使用する
  • OData クエリ関数: contains、startswith、および endswith を使用できます。 詳細情報: OData クエリ関数を使用する
  • 文字列値の配列を受け入れるフィルターを使用する場合は、一重引用符を管理する必要があります。 詳細情報: 一重引用符を管理する

URL は特殊文字をエンコードします

フィルター関数の値として使用している文字列に特殊文字が含まれている場合は、それを URL エンコードする必要があります。 たとえば、この関数を使用すると、contains(name,'+123')、+ が URL に含めることができない文字であるため、うまくいきません。 文字列を URL エンコードすると、contains(name,'%2B123') となり、列の値に +123 が含まれる結果が得られます。

次の表は、一般的な特殊文字の URL エンコード値を示しています。

スペシャル
文字		 エンコードされた URL
文字
$ %24
& %26
+ %2B
, %2C
/ %2F
: %3A
; %3B
= %3D
? %3F
@ %40

ワイルドカード文字を使用する

文字列を使用してフィルターを構成する場合、次のワイルドカード文字を適用できます。

登場人物 Description T-SQL のドキュメントと例
% 0 文字以上の任意の文字列に一致します。 このワイルドカード文字は、接頭辞または接尾辞として使用できます。 パーセント記号 (ワイルドカード - 一致する文字) (Transact-SQL)
_ アンダースコア文字を使用して、パターン マッチングを含む文字列比較操作で任意の 1 文字を照合します。 _ (ワイルドカード - 1 つの文字に一致) (Transact-SQL)
[] かっこで囲まれた指定範囲またはセット内の任意の 1 文字に一致します。 [ ] (ワイルドカード - 一致する文字) (Transact-SQL)
[^] 角かっこで囲まれた指定範囲またはセット内にはない任意の 1 文字に一致します。 [^] (ワイルドカード - 一致しない文字) (Transact-SQL)

詳細: 文字列値の条件でワイルドカード文字を使用する

末尾のワイルドカードには対応していません

末尾のワイルドカードはサポートされていないため、使用しないことが重要です。 これらのアンチ パターンを使用するクエリでは、クエリを最適化できないため、パフォーマンスの問題が発生します。 次に、末尾のワイルドカードの例をいくつか示します。

startswith(name,'%value')
endswith(name,'value%')

OData クエリ関数を使用する

次の表では、文字列値のフィルター処理に使用できる OData クエリ関数について説明します。

Function 例
contains $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

これらの関数を論理演算子 not とともに使用すると、結果を否定できます。

一重引用符を管理する

一部のフィルタは、クエリ関数 など、文字列値の配列を受け入れます。 これらのフィルターで、O'Brian または Men's clothes などの一重引用符、アポストロフィ、文字を含む値を指定する場合は、値を二重引用符で囲む必要があります。例えば:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

そうしないと、次のエラーを取得します。Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

フィルターを単一の値に使用する場合は、一重引用符を連続する 2 つの一重引用符文字に置き換えます。例えば:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

そうしないと、次のようなエラーを取得します。There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

関連テーブルの値に基づいて、返された行をフィルターできます。 フィルターする方法は、リレーションシップのタイプによって異なります。

検索列のプロパティ値を使用してフィルターする

検索列を表す単一値ナビゲーション プロパティの値に基づいてフィルターできます。 このパターンを使用します:

<single-valued navigation property>/<property name>

次の例は、primarycontactid/fullname 列の値に基づいてアカウント レコードを返します。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
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,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

単一値のナビゲーション プロパティの階層をさらに上位にある値を比較することもできます。

次の例では、取引担当者レコードが primarycontactid を表す最初のアカウントを返します。ここで、「システム管理者」が $filter の primarycontactid/createdby/fullname を使用してレコードを作成しました。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$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,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

ラムダ演算子 any および all を使用してコレクション内の値を評価し、結果をフィルターします。

  • any: 適用した式が、コレクションのいずれかのメンバーに対して true の場合は true を返し、それ以外の場合は false を返します。 引数を指定しないany 演算子は、コレクションが空ではない場合に true を返します。
  • all: 適用した式が、コレクションのメンバー全員に対して true の場合は true を返し、それ以外の場合は false を返します。

構文は次のようになります。

<collection>/[any | all](o:<expression to evaluate>)

この場合、o はコレクションが含む項目を表す変数です。 この規則では型の先頭の文字を使用します。 式内で、o/<property or collection name> を使用して、特定の項目のプロパティまたはコレクションを参照します。

複数のコレクション値ナビゲーション プロパティと、入れ子になったコレクションに、条件を含めることができます。 ルックアップ ナビゲーション プロパティにネストされているコレクション値のナビゲーション プロパティに条件を含めることはできません。 例えば、$filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') はサポートされていません。

詳細情報: odata.org のラムダ演算子

ラムダ演算子の例

以下の例では、件名に「sometext」を含む電子メールを少なくとも 1 つ含むすべてのアカウント エンティティ レコードを取得します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

以下の例では、関連付けられているすべてのタスクが閉じられているすべてのアカウント エンティティ レコードを取得します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

次の例では、件名に「sometext」を含む電子メールが 1 つ以上あり、状態コードがアクティブであるすべてのアカウント エンティティ レコードを取得します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

次の例では any 演算子と all 演算子を使用して入れ子のクエリを作成します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

ページの結果

Prefer: odata.maxpagesize 要求ヘッダーを使用して、返されるレコードの数を制御します。 数値を指定しない場合、要求ごとに最大 5,000 件のレコードが返される可能性があります。 5000 件を超えるページ サイズは要求できません。

注意

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

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

$top クエリ オプションの使用

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

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

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

データの集計

$apply オプションを使用して、データの動的な集約とグループ化を行います。

集計機能は 50,000 レコードのコレクションに制限されます。 Dataverse での集計機能の使用については、FetchXml を使用したデータの集計を参照してください

OData データ集計の詳細についてはこちらを参照してください: データ集計用 OData 拡張 バージョン 4.0。 Dataverse は、これらの集計方法のサブセットのみに対応しています。

注意

  • datetime 値のある groupby はサポートされていません。

  • 集計値のある $orderby はサポートされていません。 これにより、エラー: The query node SingleValueOpenPropertyAccess is not supported が返されます。

その例を以下に示します。

これらのサンプルは、簡潔にするために完全な要求と応答を示していません。

クエリ内の一意のステータスのリスト

GET accounts?$apply=groupby((statuscode))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2
        }
    ]
}

状態の値ごとの件数

GET accounts?$apply=groupby((statuscode),aggregate($count as count))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "count@OData.Community.Display.V1.FormattedValue": "8",
            "count": 8
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "count@OData.Community.Display.V1.FormattedValue": "1",
            "count": 1
        }
    ]
}

合計売上を集計する

GET accounts?$apply=aggregate(revenue with sum as total)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$440,000.00",
            "total": 440000.000000000
        }
    ]
}

状態に基づく平均売上

GET accounts?$apply=groupby((statuscode),aggregate(revenue with average as averagevalue))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$53,750.00",
            "averagevalue": 53750.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "averagevalue": 10000.000000000
        }
    ]
}

状態に基づく合計売上

GET accounts?$apply=groupby((statuscode),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "total@OData.Community.Display.V1.FormattedValue": "$430,000.00",
            "total": 430000.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000
        }
    ]
}

取引先責任者名ごとのアカウント合計売上

GET accounts?$apply=groupby((primarycontactid/fullname),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000,
            "contact_fullname": "Jim Glynn (sample)"
        },
        {
            "total@OData.Community.Display.V1.FormattedValue": "$80,000.00",
            "total": 80000.000000000,
            "contact_fullname": "Maria Campbell (sample)"
        },
      ... <truncated for brevity>
      
    ]
}

「WA」 の取引先企業の取引先責任者名

GET accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "contact_fullname": "Rene Valdes (sample)"
        },
        {
            "contact_fullname": "Robert Lyon (sample)"
        },
        {
            "contact_fullname": "Scott Konersmann (sample)"
        }
    ]
}

最後に作成されたレコードの日時

GET accounts?$apply=aggregate(createdon with max as lastCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "lastCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "lastCreate": "2023-03-25T17:42:47Z"
        }
    ]
}

最初に作成されたレコードの日時

GET accounts?$apply=aggregate(createdon with min as firstCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

応答本文

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "firstCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "firstCreate": "2023-03-25T17:42:46Z"
        }
    ]
}

行数をカウントする

$count=true クエリ オプションを使用して、フィルター条件と一致するエンティティ数を最大 5,000 件まで含めます。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=accountid&$count=true
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

応答:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid)",
    "@odata.count": 9,
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        },
        ... <Truncated for brevity>
    ]
}

応答の @odata.count 注釈は、要求したページ サイズに関係なく、フィルター条件と一致する行数 (最大 5000 件) を含みます。

注意

5,000 件を超えるテーブルの合計行数の、過去 24 時間以内のスナップショットを取得する場合は、RetrieveTotalRecordCount 関数 を使用します。

カウント値が 5000 である場合に、カウントがちょうど 5000 であるか、5000 より大きいかを知る必要がある場合は、次のヘッダーを追加できます。

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.totalrecordcount,Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded"

このヘッダーは結果に次の注釈を追加します。

  • @Microsoft.Dynamics.CRM.totalrecordcount
  • @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded

$count=true クエリ オプションと一緒に使用する場合に、5,000 を超えるレコードがあると、次の値が返されます。

"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,

5000 件未満のレコードがある場合は、実際のカウントが返されます。

"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,

$count=true クエリ オプションを含めない場合、@Microsoft.Dynamics.CRM.totalrecordcount の合計値は -1 になります。

次の例は、$filter と一致するアカウントが 10 件存在することを示しますが、最初 3 件のアカウントのみが返されます。

要求:

GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.maxpagesize=3
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
   "value":[  
      {  
         "@odata.etag":"W/\"502482\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502483\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502484\"",
         "name":"Adventure Works (sample)",
         "accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
      }
   ],
   "@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

コレクションの数を表す数値だけを取得するには、次の例のように /$count を追加します。

要求:

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

応答:

HTTP/1.1 200 OK  
Content-Type: text/plain  
OData-Version: 4.0  
  
10

参照

Dataverse レコードの検索
Web API クエリ データのサンプル (C#)
Web API クエリ データのサンプル (クライアント側の JavaScript)
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理