クエリで関連テーブル レコードを取得する
注意
エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。
ナビゲーション プロパティの $expand
システム クエリ オプションを使用して、関連エンティティからどのデータが返されるかをコントロールします。 ナビゲーション プロパティには次の 2 種類があります。
単一値 ナビゲーション プロパティは、多対 1 関係をサポートし、別のエンティティに対する参照が設定できるような検索属性に対応します。
コレクション値 ナビゲーション プロパティは 1 対多または多対多の関連付けに対応します。
ナビゲーション プロパティ名のみを含める場合、関連レコードのすべてのプロパティが表示されます。 ナビゲーション プロパティ名の後にかっこで示される、$select
システム クエリ オプションを使用して、関連レコードに対して返されるプロパティを制限できます。 これは、単一値とコレクション値のナビゲーション プロパティの両方で使用します。
注意
- クエリ内の
$expand
オプションは 15 個までに制限されています。 これはパフォーマンスを保護するためです。 各$expand
オプションは、パフォーマンスに影響を与える可能性のある結合を作成します。 - エンティティ インスタンスの関連エンティティを取得するには、ナビゲーション プロパティの拡張による関連レコードの取得 を参照してください。
- コレクション値ナビゲーション プロパティを展開するクエリは、最新の変更を反映しないそれらのプロパティのキャッシュされたデータを返すことがあります。 ブラウザのキャッシュを上書きするには、
If-None-Match
ヘッダーと値null
を使用することをお勧めします。 詳細については、「HTTP ヘッダー」を参照してください。
単一値のナビゲーション プロパティの拡張による関連テーブル レコードの取得
以下の例は、すべての取引先企業レコードの取引先担当者を取得する方法を示します。 関連する取引先担当者レコードの場合、取引先担当者 ID およびフルネームのみを取得します。
要求
GET [Organization URI]/api/data/v9.1/accounts?$select=name
&$expand=primarycontactid($select=contactid,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
OData-Version: 4.0
{
"@odata.context":"[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))",
"value":[
{
"@odata.etag":"W/\"513475\"",
"name":"Fourth Coffee (sample)",
"accountid":"36dbf27c-8efb-e511-80d2-00155db07c77",
"primarycontactid":{
"contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77",
"fullname":"Yvonne McKay (sample)"
}
},
{
"@odata.etag":"W/\"513477\"",
"name":"Litware, Inc. (sample)",
"accountid":"38dbf27c-8efb-e511-80d2-00155db07c77",
"primarycontactid":{
"contactid":"9edbf27c-8efb-e511-80d2-00155db07c77",
"fullname":"Susanna Stubberod (sample)"
}
}
]
}
エンティティ セットの関連エンティティを返す代わりに、$ref
オプションを使用して単一値ナビゲーション プロパティを展開することにより、関連エンティティへの参照 (リンク) を返すこともできます。 次の例では、すべての取引先企業の取引先担当者レコードに対するリンクを返します。
要求
GET [Organization URI]/api/data/v9.1/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
OData-Version: 4.0
{
"@odata.context":"[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid)",
"value":[
{
"@odata.etag":"W/\"513475\"",
"name":"Fourth Coffee (sample)",
"_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77",
"accountid":"36dbf27c-8efb-e511-80d2-00155db07c77",
"primarycontactid":{
"@odata.id":"[Organization URI]/api/data/v9.1/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
}
},
{
"@odata.etag":"W/\"513477\"",
"name":"Litware, Inc. (sample)",
"_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77",
"accountid":"38dbf27c-8efb-e511-80d2-00155db07c77",
"primarycontactid":{
"@odata.id":"[Organization URI]/api/data/v9.1/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
}
}
]
}
単一値ナビゲーション プロパティの複数レベルの展開
$expand
オプションを別の $expand
オプション内に入れ子にすることで、単一値ナビゲーション プロパティを複数のレベルに展開することができます。
注意
入れ子になった $expand
オプションの深さに制限はありませんが、クエリ内の合計 15 個の $expand
オプションの組み合わせ制限は適用されます。
次のクエリは、task
レコードを返し、関連する contact
、contact
に関連する account
、そして最後に account
レコードを作成した systemuser
を展開します。
Request
GET [Organization URI]/api/data/v9.1/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
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.1/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
"value":
[
{
"@odata.etag": "W/\"28876997\"",
"subject": "Task 1 for Susanna Stubberod",
"activityid": "834814f9-b0b8-ea11-a812-000d3a122b89",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "824814f9-b0b8-ea11-a812-000d3a122b89",
"parentcustomerid_account": {
"name": "Contoso, Ltd. (sample)",
"accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"createdby": {
"fullname": "Nancy Anderson",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
},
{
"@odata.etag": "W/\"28877001\"",
"subject": "Task 2 for Susanna Stubberod",
"activityid": "844814f9-b0b8-ea11-a812-000d3a122b89",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "824814f9-b0b8-ea11-a812-000d3a122b89",
"parentcustomerid_account": {
"name": "Contoso, Ltd. (sample)",
"accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"createdby": {
"fullname": "Nancy Anderson",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
}
]
}
コレクション値ナビゲーション プロパティの拡張による関連レコードの取得
コレクション値のナビゲーション プロパティを拡張してエンティティ セットの関連エンティティを取得する場合、データがある場合は 1 つのレベルの深度のみが返されます。 それ以外の場合、コレクションは空の配列を返します。
いずれの場合も、@odata.nextLink
プロパティは関連するエンティティを返します。 コレクションを個別に取得する場合は、@odata.nextLink
プロパティの値を新しい GET
リクエストとともに使用して、必要なデータを返すことができます。
注意
$expand
を使用して返されたコレクション値のナビゲーション プロパティで使用できるページングはありません。 5000 以下のレコードが返されます。 ページングが必要な場合は、Prefer: odata.maxpagesize
要求ヘッダーを使用して @odata.nextLink
プロパティで URL を使用します。 詳細: ページに戻す行数の指定。
次の例は、上位 2 件の取引先企業レコードに割り当てられたタスクを取得します。 1 つには関連するタスクがあり、もう 1 つにはありません。
Request
GET [Organization URI]/api/data/v9.1/accounts?$top=2
&$select=name
&$expand=Account_Tasks($select=subject,scheduledstart) 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
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.1/$metadata#accounts(name,Account_Tasks(subject,scheduledstart))",
"value": [
{
"@odata.etag": "W/\"37867294\"",
"name": "Contoso, Ltd. (sample)",
"accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"Account_Tasks": [
{
"@odata.etag": "W/\"28876919\"",
"subject": "Task 1 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7b4814f9-b0b8-ea11-a812-000d3a122b89"
},
{
"@odata.etag": "W/\"28876923\"",
"subject": "Task 2 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7c4814f9-b0b8-ea11-a812-000d3a122b89"
},
{
"@odata.etag": "W/\"28876927\"",
"subject": "Task 3 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7d4814f9-b0b8-ea11-a812-000d3a122b89"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.1/accounts(7a4814f9-b0b8-ea11-a812-000d3a122b89)/Account_Tasks?$select=subject,scheduledstart"
},
{
"@odata.etag": "W/\"37526208\"",
"name": "Fourth Coffee",
"accountid": "ccd685f9-cddd-ea11-a813-000d3a122b89",
"Account_Tasks": [],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.1/accounts(ccd685f9-cddd-ea11-a813-000d3a122b89)/Account_Tasks?$select=subject,scheduledstart"
}
]
}
単一値とコレクション値の両方のナビゲーション プロパティを拡張して、関連するレコードを取得します
次の例では、単一値とコレクション値の両方のナビゲーション プロパティを使用して、エンティティセットの関連レコードを拡張する方法を示します。 既に説明しているように、コレクション値ナビゲーション プロパティを拡張してエンティティ セットの関連レコードを取得すると、1 つのレベルの深度と関連エンティティの @odata.nextLink
プロパティが返されます。
この例では、上位 2 件の取引先企業に割り当てられた取引先担当者およびタスクを取得します。
要求
GET [Organization URI]/api/data/v9.1/accounts?$top=2
&$select=name
&$expand=primarycontactid($select=contactid,fullname),
Account_Tasks($select=subject,scheduledstart) 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
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))",
"value": [
{
"@odata.etag": "W/\"37867294\"",
"name": "Contoso, Ltd. (sample)",
"accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"primarycontactid": {
"contactid": "7e4814f9-b0b8-ea11-a812-000d3a122b89",
"fullname": "Yvonne McKay (sample)"
},
"Account_Tasks": [
{
"@odata.etag": "W/\"28876919\"",
"subject": "Task 1 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7b4814f9-b0b8-ea11-a812-000d3a122b89"
},
{
"@odata.etag": "W/\"28876923\"",
"subject": "Task 2 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7c4814f9-b0b8-ea11-a812-000d3a122b89"
},
{
"@odata.etag": "W/\"28876927\"",
"subject": "Task 3 for Contoso, Ltd.",
"scheduledstart": null,
"_regardingobjectid_value": "7a4814f9-b0b8-ea11-a812-000d3a122b89",
"activityid": "7d4814f9-b0b8-ea11-a812-000d3a122b89"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.1/accounts(7a4814f9-b0b8-ea11-a812-000d3a122b89)/Account_Tasks?$select=subject,scheduledstart"
},
{
"@odata.etag": "W/\"37526208\"",
"name": "Fourth Coffee",
"accountid": "ccd685f9-cddd-ea11-a813-000d3a122b89",
"primarycontactid": {
"contactid": "384d0f84-7de6-ea11-a817-000d3a122b89",
"fullname": "Charlie Brown"
},
"Account_Tasks": [],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.1/accounts(ccd685f9-cddd-ea11-a813-000d3a122b89)/Account_Tasks?$select=subject,scheduledstart"
}
]
}
関連テーブルのデータに基づいてコレクション値をフィルターする
Web APIでは、 any
と all
の2つのラムダ演算子を使用して、コレクションのブール式を評価することができます。 詳細については次を参照してください: ラムダ演算子を使用する
関連項目
Dataverse 検索を使用してテーブル データ全体を検索する
Web API を使用したクエリ データ
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用してテーブル行を作成する
Web API を使用してテーブルの行を取得する
Web API を使用したテーブル行の更新と削除
Web API を使用したテーブル行の関連付けと関連付け解除
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
フィードバックの送信と表示