クエリで関連テーブル レコードを取得する

  • [アーティクル]

ナビゲーション プロパティの $expand システム クエリ オプションを使用して、関連テーブル レコードからどのデータが返されるかをコントロールします。

注意

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

特定の $expand オプション内で、次のシステム クエリ オプションを適用できます。

回答内容 Description
$select どのプロパティが返されたかを選択します。 詳細: $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 のあるこれらのオプションは、ナビゲーション プロパティの名前の後に括弧で囲んで追加して使用します。 各オプションをセミコロンで区切ります。 例:

/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)

$selectで列を制限する

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

Request

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject) HTTP/1.1
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 対多または多対多の関連付けに対応します。

コレクション値のナビゲーション プロパティを展開すると、応答のサイズが拡大し、その予測が困難になる場合があります。 返されるデータの量をコントロールする制限を含めることが重要です。 Prefer: odata.maxpagesize 要求ヘッダーは、返されるレコードの数を制限する最も一般的な方法ですが、$top を使用することもできます。 詳細: ページに戻す行数の指定

注意

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

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

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

Request

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname) HTTP/1.1  
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"
}

参照を返す

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

Request

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref HTTP/1.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=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))) HTTP/1.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=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 展開された行のページング。 リソース エンティティセットのみのページング。 展開された行の <property name>@odata.nextLink URL には、ページング情報は含まれません。
$top または $orderby がサポートされています 番号 イエス

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

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

展開されたコレクション値の各ナビゲーション プロパティは、ページング情報を含まない <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) HTTP/1.1
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)) HTTP/1.1
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 にページング情報が含まれているかを確認するには、応答例を水平方向にスクロールします。

参照

Web API を使用したクエリ データ
Web API を使用してテーブルの行を取得する
Web API クエリ データのサンプル (C#)

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。