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

  • [アーティクル]

クエリを作成する際は、必ず次の決定を行います。

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

この記事では、Dataverse Web API でデータを取得するクエリを構築する際に、これらの決定で求められる情報を提供します。

注意

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

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

すべてのクエリはエンティティのコレクションで始まります。 エンティティ コレクションは、次のいずれかです。

EntitySet リソース

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

Request

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

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

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

特定のユーザーが OwningUser である アカウント EntityType からデータを取得する場合は、指定した 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 クエリ オプションで使用できます。 パラメーター エイリアスは、1 つの要求の中で同じ値を複数回使用することができます。 エイリアスに値を割り当てていない場合は、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 クエリ オプション を使用して、クエリで返す列を選択します。 $select クエリ オプションを含めない場合、すべてのプロパティを返します。 OData では、すべての列を プロパティ として表現します。 詳細情報: Web API プロパティ

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

Request

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

これを次の例で示します。

Request

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 で使用できます。

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

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

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

ヒント

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

Request

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 は最初のものを所有し、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 クエリ オプション を使用して、関連テーブル レコードからどのデータが返されるかをコントロールします。

注意

  • クエリ内の $expand オプションは 15 個までに制限されています。 これはパフォーマンスを保護するためです。 各 $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 を使用して返される列を常に制限します。 たとえば、次のリクエストは、エンティティ型から拡張された結果の contact.fullname``account と task.subject の値を返します。

Request

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 オプションにページングが適用される方法には、大きな違いがあります。 詳細情報: コレクション値のナビゲーション プロパティを展開する

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

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

Request

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 オブジェクトを返します。

Request

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 を展開します。

Request

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 つだけ返されることが保証されます。

Request

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."
    }
}

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

Request

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～2000 人であるアカウントの検索方法を示しています。

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

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

文字列値をフィルターする際は、次の点に注意してください。

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

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

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

登場人物 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 のように、一重引用符 ' (アポストロフィ) 文字を含む In クエリ関数 のような文字列値の配列を受け入れるフィルターで比較する値を指定する場合、値を二重引用符で囲む必要があります。 例:

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 列の値に基づいてアカウント レコードを返します。

Request

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"
        }
    ]
}

また、単一値のナビゲーション プロパティのさらに上の階層の値も比較できます。

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

Request

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 を使用してコレクションが含む値を評価し、結果をフィルターします。

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

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

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

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

複数のコレクション値ナビゲーション プロパティと、入れ子になったコレクションに、条件を含めることができます。

詳細情報: 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" が含まれ、statecode がアクティブな電子メールが 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 要求ヘッダーを使用して、返されるレコードの件数を制御できます。 返されるレコード件数を指定しない場合、要求ごとに最大 5000 件のレコードを返す可能性があります。 5000 件を超えるページ サイズは要求できません。

注意

Dataverse は $skip クエリ オプションに対応していないため、$top と $skip の組み合わせはページングに使用できません。 詳細情報: $top クエリ オプションを使用する

次の例では、最初 2 件の連絡先レコードのみを返します。

Request

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 を提供し、データの次のページを返します。

Request

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 クエリ オプションを使用して、返される結果の件数を制限できます。 次の例では、最初 3 件のアカウント行のみを返します。

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

注意

$top は Prefer: odata.maxpagesize 要求ヘッダーと一緒に使用できません。 両方とも含めると $top は無視されます。

データの集計

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

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

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

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

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

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

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 クエリ オプションを使用して、フィルター条件と一致するエンティティ数を最大 5000 件まで含めます。

Request

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 件) を含みます。

注意

5000 件を超えるテーブルの合計行数の、過去 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 クエリ オプションと一緒に使用する場合に、5000 件を超えるレコードがあると、次の値が表示されます:

"@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 件のアカウントのみが返されます。

Request

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 を追加してその値を取得します。

Request

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 要求の作成とエラーの処理