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

  • [アーティクル]

注意

エンティティとテーブルの違いがわかりませんか？ 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 分かかります。 個人データは収集されません (プライバシー ステートメント)。