Web API を使用してテーブルの行を取得する

[アーティクル]
06/20/2022

注意

エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

GET 要求を使用して、一意の識別子を持つリソースとして指定されたテーブルのデータを取得します。テーブルの行 (エンティティレコード) を取得するときに、特定のプロパティを要求し、ナビゲーションプロパティを展開して、関連するテーブルからプロパティを返すこともできます。

注意

テーブル定義の取得については、Web API を使用してテーブル定義をクエリするを参照してください。

基本的な取得例

この例では、主キーの値が 00000000-0000-0000-0000-000000000001 である取引先企業エンティティレコードのデータが返されます。

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)

1 件のエンティティレコードを一度に取得するには、Web API を使用してデータをクエリするトピックのベーシッククエリの例を参照してください。

注意事項

上記の例では、取引先企業レコードのすべてのプロパティが返されますが、これはデータを取得するためのパフォーマンスのベストプラクティスではありません。この例は、Microsoft Dataverse でエンティティレコードの基本的な取得方法を説明するためのものでした。すべてのプロパティは戻されたので、この例の要求に対する応答情報は含めていませんでした。

パフォーマンスのベストプラクティスとして、データを取得する際に返されるプロパティを制限するためには、$select システムクエリオプションを使用する必要があります。これについては、次のセクション、固有のプロパティの取得 を参照してください。

特定のプロパティの取得

プロパティ名のコンマ区切りリストを含めることにより返されるプロパティを制限するためには $select システムクエリオプションを使用します。これは重要なパフォーマンスのベストプラクティスです。プロパティが $select を使用して指定されない場合、すべてのプロパティが返されます。

次の例では、00000000-0000-0000-0000-000000000001 に等しい主キーの値を含むアカウントエンティティの name および revenue プロパティを取得します

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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.0/$metadata#accounts(name,revenue)/$entity",  
"@odata.etag": "W/\"502186\"",  
"name": "A. Datum Corporation (sample)",  
"revenue": 10000,  
"accountid": "00000000-0000-0000-0000-000000000001",  
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"  
}

特定の種類のプロパティを要求すると、さらに追加の読み取り専用プロパティが自動的に返されることを予期できます。

金額値を要求した場合、_transactioncurrencyid_value 検索プロパティが返されます。このプロパティには取引通貨の GUID 値のみが含まれますので、この値を使用することにより transactioncurrency EntityType / を使用して通貨に関する情報を取得できます。または、コメントを要求することにより、同じ要求の追加データも取得できます。詳細については、検索プロパティに関するデータの取得を参照してください。

アドレスの複合属性の一部のプロパティを要求する場合は、複合プロパティも取得します。たとえば、クエリ要求が、取引先担当者の address1_line1 プロパティの場合は、address1_composite プロパティも返されます。

代替キーの使用の取得

エンティティで代替キーを定義している場合、さらに、代替キーを使用して、エンティティの一意の識別子ではないエンティティを取得することができます。たとえば、Contact エンティティに firstname と emailaddress1 のプロパティの両方を含む代替キーの定義がある場合、ここで示されているように、それらのキーに対して用意されているデータを含むクエリを使用して取引先担当者を取得できます。

GET [Organization URI]/api/data/v9.0/contacts(firstname='Joe',emailaddress1='abc@example.com')

代替キー定義に検索タイプフィールドが含まれている場合 (たとえば、account エンティティの primarycontactid のプロパティ)、表示されているように検索プロパティを使用して account を取得することができます。

GET [Organization URI]/api/data/v9.0/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000001)

取得、更新、または削除するエンティティを一意に識別する必要のある場合には必ず、エンティティに対して構成された代替キーを使用できます。既定では、エンティティに構成された代替キーがありません。代替キーは、組織またはソリューションがそれらを追加する場合にのみ使用できます。

ストレージのパーティション内のドキュメントを取得する

パーティションに格納されているエンティティデータを取得する場合は、そのデータを取得するときに必ずパーティションキーを指定してください。

詳細: ストレージパーティションを使用したテーブルデータへの高速アクセス

単一のプロパティ値の取得

エンティティの単一のプロパティ値を取得する必要がある場合、そのプロパティの値のみを返すために、エンティティの URI にプロパティの名前を付けることができます。これは、応答で返されるものよりデータの必要が少ないために、パフォーマンスのベストプラクティスです。

この例では、account エンティティの name プロパティの値のみ返します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/name 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.0/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

個々のプロパティ値が取得できることと同様に、個々のエンティティを参照する URI にナビゲーションプロパティ名を追加することによって、ナビゲーションプロパティ (検索フィールド) の値にもアクセスできます。

次の例では、primarycontactid 単一値ナビゲーションプロパティを使用して account の主 contact の fullname を返します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$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.0/$metadata#contacts(fullname)/$entity",  
"@odata.etag": "W/\"500128\"",  
"fullname": "Rene Valdes (sample)",  
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"  
}

コレクション値ナビゲーションプロパティでは、関連するエンティティに対する参照だけまたは関連エンティティの数のみを返すオプションがあります。

次の例では、/$refを要求に追加することによって、ちょうど特定の取引先企業に関連したタスクへの参照を返します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$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.0/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.0/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.0/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)" }
  ]
}

次の例では、/$count が追加された Account_Tasks コレクション値ナビゲーションプロパティを使用して特定の取引先企業と関連するタスクの数を返します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答

ï»¿2

注意

戻る値には、これが UTF-8 ドキュメントであることを表す、UTF-8 バイトのオーダーマーク (BOM) 文字 (ï»¿) が含まれています。

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

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

単にナビゲーションプロパティ名を含める場合、関連レコードのすべてのプロパティが表示されます。ナビゲーションプロパティ名の後にかっこで示される、$select システムクエリオプションを使用して、関連レコードに対して返されるプロパティを制限できます。これは、単一値とコレクション値のナビゲーションプロパティの両方で使用します。

注意

エンティティセットの関連エンティティを取得する際は、クエリで関連テーブルレコードを取得するを参照してください。

単一値ナビゲーションプロパティの拡張によるエンティティインスタンスに対する関連エンティティの取得:
以下の例は、取引先企業エンティティの取引先担当者を取得する方法を示します。関連する取引先担当者レコードの場合、取引先担当者 ID およびフルネームのみを取得します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$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.0/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "primarycontactid":
  {  
  "@odata.etag":"W/\"550626\"",  
  "contactid":"c59648c3-68f7-e511-80d3-00155db53318",  
  "fullname":"Nancy Anderson (sample)"  
  }
}

エンティティレコードの関連エンティティを返す代わりに、$ref オプションを使用して単一値ナビゲーションプロパティを展開することにより、関連エンティティへの参照 (リンク) を返すこともできます。次の例では、すべての取引先企業エンティティの取引先担当者レコードに対するリンクを返します。

要求

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$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.0/$metadata#accounts(name,primarycontactid)/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",  
  "primarycontactid": { "@odata.id":"[Organization URI]/api/data/v9.0/contacts(c59648c3-68f7-e511-80d3-00155db53318)" }
}

コレクション値ナビゲーションプロパティの拡張によるエンティティインスタンスに対する関連エンティティの取得:
以下の例は、取引先企業レコードに割り当てたすべてのタスクを取得する方法を示します。

要求

GET [Organization URI]/api/data/v9.0/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name
&$expand=Account_Tasks($select=subject,scheduledstart)
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.0/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
  "@odata.etag": "W/\"514069\"",
  "name": "Sample Child Account 1",
  "accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
  "Account_Tasks":
   [
    {
      "@odata.etag": "W/\"514085\"",
      "subject": "Sample Task 1",
      "scheduledstart": "2016-04-11T15:00:00Z",
      "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
    },
    {
      "@odata.etag": "W/\"514082\"",
      "subject": "Sample Task 2",
      "scheduledstart": "2016-04-13T15:00:00Z",
      "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
    }
   ]
}

単一値およびコレクション値ナビゲーションプロパティ両方の拡張によるエンティティインスタンスの関連エンティティの取得: 以下の例は、単一およびコレクション値ナビゲーションプロパティの両方を使用して、エンティティインスタンスの関連エンティティを拡張する方法を示します。

要求

GET [Organization URI]/api/data/v9.0/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid
&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) 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.0/$metadata#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity",
"@odata.etag": "W/\"514069\"",
"accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid": 
    {
      "@odata.etag": "W/\"514074\"",
      "createdon": "2016-04-06T00:29:04Z",
      "name": "Adventure Works (sample)",
      "accountid": "3adbf27c-8efb-e511-80d2-00155db07c77"
    },
  "Account_Tasks":
    [
      {
        "@odata.etag": "W/\"514085\"",
        "subject": "Sample Task 1",
        "scheduledstart": "2016-04-11T15:00:00Z",
        "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
      },
      {
        "@odata.etag": "W/\"514082\"",
        "subject": "Sample Task 2",
        "scheduledstart": "2016-04-13T15:00:00Z",
        "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
      }
    ]
}

注意

関連するエンティティの URI のみ、または関連するエンティティの数のカウントを返すためには、/$count または /$ref パスセグメントを使用できません。

展開されたテーブルに適用するオプション

コレクション値ナビゲーションプロパティに対して返されるエンティティに特定のシステムクエリオプションを適用することができます。コレクション値ナビゲーションプロパティ名の後に、かっこで囲まれるシステムクエリオプションのセミコロン区切りリストを使用します。 $select、$filter、$orderby、$top、$expand を使用することができます。

次の例では、account に関連するタスクエンティティの結果を、"1" で終わる件名を含むものにフィルター処理します。

?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

次の例では、関連タスクが createdon プロパティに基づいて昇順で返される必要のあることを指定します。

?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

次の例では、最初の関連するタスクのみ返します。

?$expand=Account_Tasks($top=1;$select=subject)

次の例では、入れ子になった $expand オプションを適用して、アカウントを最後に変更した systemuser に関する詳細と、ユーザーが属する businessunit の名前を返します。

?$select=name&$expand=modifiedby($select=fullname;$expand=businessunitid($select=name))

注意

入れ子になった $expand オプションは、単一値ナビゲーションプロパティにのみ適用できます。
各リクエストには最大 15 個の $expand オプションを含めることができます。入れ子になった $expand オプションの深さに制限はありませんが、合計 15 個の $expand オプションの制限はこれらにも適用されます。
これは、OData バージョン 4.0 パート 1: プロトコルプラス Errata 02 の「11.2.4.2.1 展開オプション」セクションに記載のシステムクエリオプションの一部です。オプション $skip、$count、$search、$levels は Web API ではサポートされていません。

入れ子になった $expand オプションの使用に関する詳細: 単一値ナビゲーションプロパティの複数レベルの展開

テーブルが取得されてから変更されたかどうかを検出する

パフォーマンスのベストプラクティスとして、必要なデータのみを使用する必要があります。以前にエンティティレコードを取得した場合、以前に取得したレコードに関連する ETag を使用して、そのレコードを条件を付けて検索できます。詳細: 条件付き検索。

書式設定された値の取得

個々のレコードの取得での書式設定された値の要求は、エンティティセットへのクエリ時と同じ方法で行われます。詳細: 書式設定値を含める。

Web API を使用してテーブルの行を取得する

基本的な取得例

特定のプロパティの取得

代替キーの使用の取得

ストレージのパーティション内のドキュメントを取得する

単一のプロパティ値の取得

ナビゲーションプロパティ値の取得

展開されたテーブルに適用するオプション

テーブルが取得されてから変更されたかどうかを検出する

書式設定された値の取得

関連項目

フィードバック

Web API を使用してテーブルの行を取得する

基本的な取得例

特定のプロパティの取得

代替キーの使用の取得

ストレージのパーティション内のドキュメントを取得する

単一のプロパティ値の取得

ナビゲーション プロパティ値の取得

ナビゲーション プロパティの拡張によるテーブルの関連テーブルの取得

展開されたテーブルに適用するオプション

テーブルが取得されてから変更されたかどうかを検出する

書式設定された値の取得

関連項目

フィードバック

ナビゲーションプロパティ値の取得

ナビゲーションプロパティの拡張によるテーブルの関連テーブルの取得