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

[アーティクル]
02/06/2023

注意

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

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

注意

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

基本的な取得例

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

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

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

注意事項

上記の例では、取引先企業レコードのすべてのプロパティが返されますが、これはデータを取得するためのパフォーマンスのベストプラクティスではありません。

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

特定のプロパティの取得

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

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

Request

GET [Organization URI]/api/data/v9.2/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.2/$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.2/contacts(firstname='Joe',emailaddress1='abc@example.com')

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

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

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

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

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

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

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

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

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

Request

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

プロパティの生値を取得する

JSON ではなくプリミティブプロパティの生値を取得するには、/$value を URL に追加します。

Request

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

回答

HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

Adventure Works (sample)

注意

ファイルまたは画像データを扱う場合を除き、生値の使用は一般的ではありません。詳細: Web API を使用して 1 回のリクエストでファイルをダウンロードする

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

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

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

Request

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

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

要求

GET [Organization URI]/api/data/v9.2/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 システムクエリオプションを使用して、関連レコードに対して返されるプロパティを制限します。単一値とコレクション値のナビゲーションプロパティの両方で返されるプロパティを制限します。

注意

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

単一値のナビゲーションプロパティの拡張による関連レコードの取得

以下の例は、取引先企業エンティティの取引先担当者を取得する方法を示します。関連する取引先担当者レコードの場合は、contactid および fullname のみを取得します。

Request

GET [Organization URI]/api/data/v9.2/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.2/$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 オプションを使用して単一値ナビゲーションプロパティを展開することにより、関連エンティティへの参照 (リンク) を返すこともできます。次の例では、すべての取引先企業エンティティの取引先担当者レコードに対するリンクを返します。

Request

GET [Organization URI]/api/data/v9.2/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.2/$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.2/contacts(c59648c3-68f7-e511-80d3-00155db53318)" }
}

コレクション値ナビゲーションプロパティの拡張による、テーブル行の関連レコードの取得

以下の例は、取引先企業レコードに割り当てたすべてのタスクを取得する方法を示します。

Request

GET [Organization URI]/api/data/v9.2/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.2/$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"
    }
    ]
}

注意

ページングは、コレクション値のナビゲーションプロパティで $expand を使用して返された行では使用できません。返されるレコードの最大数は 5000 です。ページングが必要な場合は、クエリを変更して、拡張しているコレクションを返します。たとえば、上記の例では、ページングで次の URL を使用できます。

GET [Organization URI]/api/data/v9.2/accounts(915e89f5-29fc-e511-80d2-00155db07c77)/Account_Tasks?$select=subject,scheduledstart

コレクション値のナビゲーションプロパティでネスト済み $expand を使用する場合は、最初のレベルのデータのみが返されます。第 2 のレベルデータは、空の配列を返します。たとえば、以下のクエリ:

GET [Organization URI]/api/data/v9.2/accounts(226e5c0d-8e12-ed11-b83d-0022482df33a)?$select=name
&$expand=primarycontactid($select=firstname,lastname),opportunity_customer_accounts($select=name;
$expand=Opportunity_Tasks($select=subject))

次のようなデータが返されます:

{
  "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(firstname,lastname),opportunity_customer_accounts(name,Opportunity_Tasks> (subject)))/$entity",
  "@odata.etag": "W/\"71457700\"",
  "name": "Sample Account",
  "accountid": "226e5c0d-8e12-ed11-b83d-0022482df33a",
  "primarycontactid": {
    "@odata.etag": "W/\"71457682\"",
    "firstname": "John",
    "lastname": "Smith",
    "contactid": "236e5c0d-8e12-ed11-b83d-0022482df33a"
  },
  "opportunity_customer_accounts": [
    {
      "@odata.etag": "W/\"71457705\"",
      "name": "Opportunity associated to Sample Account",
      "opportunityid": "246e5c0d-8e12-ed11-b83d-0022482df33a",
      "Opportunity_Tasks": []
    }
  ]
}

拡張済み Opportunity_Tasks コレクション値ナビゲーションプロパティは、空の配列です。そのコレクションにはデータがあるかもしれませんが、それを取得するには別のクエリが必要になります。

単一値とコレクション値の両方のナビゲーションプロパティを拡張して、エンティティインスタンスの関連するエンティティを取得します

次の例では、単一値とコレクション値の両方のナビゲーションプロパティを使用して、エンティティインスタンスの関連エンティティを拡張する方法を示します。

Request

GET [Organization URI]/api/data/v9.2/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.2/$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 のみ、または関連するエンティティの数のカウントを返すためには、/$ref または /$count パスセグメントを使用できません。

展開されたレコードに適用するオプション

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

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

?$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 を使用してテーブルの行を取得する

基本的な取得例

特定のプロパティの取得

代替キーの使用の取得

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

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

プロパティの生値を取得する

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

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

単一値のナビゲーション プロパティの拡張による関連レコードの取得

コレクション値ナビゲーション プロパティの拡張による、テーブル行の関連レコードの取得

単一値とコレクション値の両方のナビゲーション プロパティを拡張して、エンティティ インスタンスの関連するエンティティを取得します

展開されたレコードに適用するオプション

レコードが取得されてから変更されたかどうかを検出する

書式設定された値の取得

関連項目

フィードバック

その他のリソース

その他のリソース

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

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

単一値のナビゲーションプロパティの拡張による関連レコードの取得

コレクション値ナビゲーションプロパティの拡張による、テーブル行の関連レコードの取得

単一値とコレクション値の両方のナビゲーションプロパティを拡張して、エンティティインスタンスの関連するエンティティを取得します