Web API を使用したデータのクエリ
注意
エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。
エンティティ セットのデータを取得する場合は、GET
要求を使用します。 データを取得するときに、クエリ オプションを適用して、必要なエンティティ (テーブル) データの条件、および返されるエンティティ プロパティ (列) を設定することができます。
ベーシック クエリの例
この例は、取引先企業エンティティ セットをクエリし、$select
および $top
システム クエリ オプションを使用して、最初の 3 つの取引先企業の名前プロパティを返します。
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$top=3 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)",
"value":[
{
"@odata.etag":"W/\"501097\"",
"name":"Fourth Coffee (sample)",
"accountid":"89390c24-9c72-e511-80d4-00155d2a68d1"
},
{
"@odata.etag":"W/\"501098\"",
"name":"Litware, Inc. (sample)",
"accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1"
},
{
"@odata.etag":"W/\"501099\"",
"name":"Adventure Works (sample)",
"accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1"
}
]
}
返されるテーブル行 (エンティティ) 数の制限
小さなページ サイズを指定しない限り、各要求に対して最大 5000 行が返されます。 クエリ フィルターの条件と一致する行がさらに存在する場合、@odata.nextLink
プロパティが結果と共に返されます。 @odata.nextLink
プロパティの値を新しい GET
要求と共に使用して、次のページの行を返します。
注意
エンティティ (テーブル) 定義に関するクエリには、制限やページングがありません。 詳細: Web API を使用したテーブル定義のクエリ
$top
クエリ オプションを使用する
$top
システム クエリ オプションを使用して、返される結果の数を制限することができます。 次の例では、最初の 3 つの取引先企業の行のみを返します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3
注意
$top
を使用して結果を制限すると、odata.maxpagesize
の基本設定が適用されることを防ぎます。 odata.maxpagesize
基本設定または $top
を使用することができますが、同時に両方を使用することはできません。 odata.maxpagesize
の詳細については、ページに戻す行数の指定 を参照してください。
また、$top
を $count
と共に使用しないでください。
ページに戻す行数の指定
odata.maxpagesize
の基本設定値を使用して、応答で返される行数を要求します。
注意
5000 を超える odata.maxpagesize
基本設定の値を使用することはできません。
基準に一致するレコードが他にもある場合は、@odata.nextLink
プロパティは、後続の GET
要求で、条件に一致するレコードの次のページを取得ために使用できる URL とともに返されます。
次の例は取引先企業エンティティ セットをクエリし、最初の 3 つの取引先企業のために name
プロパティを戻します。
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3
応答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
"value":[
{
"@odata.etag":"W/\"437194\"",
"name":"Fourth Coffee (sample)",
"accountid":"7d51925c-cde2-e411-80db-00155d2a68cb"
},
{
"@odata.etag":"W/\"437195\"",
"name":"Litware, Inc. (sample)",
"accountid":"7f51925c-cde2-e411-80db-00155d2a68cb"
},
{
"@odata.etag":"W/\"468026\"",
"name":"Adventure Works (sample)",
"accountid":"8151925c-cde2-e411-80db-00155d2a68cb"
}
],
"@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}
@odata.nextLink
プロパティの値を使用して、次のレコードのセットを要求します。 値に対する追加のシステム クエリ オプションを変更または追加しないでください。 追加ページのすべての後続要求に対して、元の要求で使用したものと同じ odata.maxpagesize 基本設定値を使用する必要があります。 また、返された結果または @odata.nextLink
プロパティの値をキャッシュし、以前取得したページが返されるようにします。
注意
@odata.nextLink
プロパティの値は URI エンコードされます。 送信前に値を URI エンコードすると、URL 内の XML Cookie 情報によりエラーが発生します。
システム クエリ オプションの適用
エンティティ セットのために URL に追加する各システム クエリ オプションは、クエリ文字列の構文を使用して追加されます。 最初のクエリは [?] の後に追加され、それ以降のクエリ オプションは [&] を使用して分割されます。 すべてのクエリ オプションは、次の例のように大文字と小文字が区別されます。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$top=3
&$filter=revenue gt 100000
特定のプロパティの要求
$select
システム クエリ オプションを使用して、以下の例に示すように、返されるプロパティを制限します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
重要
これはパフォーマンスのベスト プラクティスです。 プロパティが $select
を使用して指定されない場合、すべてのプロパティが返されます。
特定の種類のプロパティを要求すると、さらに追加の読み取り専用プロパティが自動的に返されることを予期できます。
金額値を要求した場合、_transactioncurrencyid_value
検索プロパティが返されます。 このプロパティには取引通貨の GUID 値のみが含まれますので、この値を使用することにより transactioncurrency EntityType を使用して通貨に関する情報を取得できます。 または、コメントを要求することにより、同じ要求の追加データも取得できます。 詳細: 検索プロパティに関するデータの取得
アドレスの複合属性の一部のプロパティを要求する場合は、複合プロパティも取得します。 たとえば、クエリ要求が、取引先担当者の address1_line1
プロパティの場合は、address1_composite
プロパティも返されます。
結果のフィルター
$filter
システム クエリ オプションを使用して、行が返される条件を設定します。
標準フィルタ演算子
Web API は、以下の表にリストされる標準 OData フィルタ演算子をサポートしています。
演算子 | 内容 | 例 |
---|---|---|
比較演算子 | ||
eq |
等号 | $filter=revenue eq 100000 |
ne |
等しくない | $filter=revenue ne 100000 |
gt |
より大きい | $filter=revenue gt 100000 |
ge |
以上 | $filter=revenue ge 100000 |
lt |
より小さい | $filter=revenue lt 100000 |
le |
以下 | $filter=revenue le 100000 |
論理演算子 | ||
and |
論理積 | $filter=revenue lt 100000 and revenue gt 2000 |
or |
論理和 | $filter=contains(name,'(sample)') or contains(name,'test') |
not |
論理否定 | $filter=not contains(name,'sample') |
グループ化演算子 | ||
( ) |
優先順位によるグループ化 | (contains(name,'sample') or contains(name,'test')) and revenue gt 5000 |
注意
これは 11.2.5.1.1 組み込みフィルター処理 の一部です。 算術演算子と比較演算子は Web API ではサポートされていません。
文字列値のすべてのフィルター条件では、大文字と小文字は区別されません。
標準クエリ機能
Web API では、以下の標準 OData 文字列クエリ機能がサポートされています。
機能 | 例 |
---|---|
contains |
$filter=contains(name,'(sample)') |
endswith |
$filter=endswith(name,'Inc.') |
startswith |
$filter=startswith(name,'a') |
注意
これは 11.2.5.1.2 組み込みフィルター処理 の一部です。 Date
、Math
、Type
、Geo
および他の文字列機能は Web API ではサポートされません。
文字列値を使用する条件でワイルドカード文字を使用する
文字列内で標準クエリ機能を使用してクエリを作成する場合は、ワイルドカード文字を使用できます。 詳細: 文字列値の条件でワイルドカード文字を使用する
Microsoft Dataverse Web API クエリ機能
Dataverse には、パラメーターを受入れ、ブール値を返し、クエリでフィルター条件として使用できる、様々な特別な関数が用意されています。 これらの関数の一覧は、Web API Query Function Referenceを参照してください。 以下は Between Functionの例で、5 ~ 2000 の間の従業員数の取引先企業を検索します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])
詳細: 関数を使用してクエリを作成する
ラムダ演算子を使用する
Web APIでは、 any
と all
の2つのラムダ演算子を使用して、コレクションのブール式を評価することができます。
any
演算子
any
演算子は、適用されたブール式がコレクションのメンバーに対して true
である場合は true
を返し、それ以外の場合は false
を返します。 引数を指定しないany
演算子は、コレクションが空ではない場合に true
を返します。
例
以下の例では、件名に "sometext" が含まれる電子メールが 1 つ以上ある、すべてのアカウント エンティティ レコードを取得する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(o:contains(o/subject,'sometext')) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
all
演算子
all
演算子は、適用されたブール式がコレクションのすべてのメンバに対して true
である場合は true
を返し、それ以外の場合は false
を返します。
例
以下の例では、関連するすべてのタスクがクローズされている、すべてのアカウント エンティティ レコードを取得する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(o:o/statecode eq 1) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
次の例では、件名に "sometext" が含まれ、statecode がアクティブな電子メールが 1 つ以上ある、すべてのアカウント エンティティ レコードを取得する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(o:contains(o/subject,'sometext') and
o/statecode eq 0) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
以下の例は、 any
と all
演算子を使用してネストされたクエリーを作成する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and
endswith(name,'{0}') HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
子行 (レコード) の値に基づいて親レコードをフィルター処理する
以下の例では、/any 演算子を使用して、以下のものを持つすべての取引先企業レコードを取得する方法を示しています:
- リンクされた営業案件レコードの予算のいずれかが 300 以上の場合、かつ
- 営業案件レコードの摘要に記述がない、または
- 営業案件レコードの摘要に 「不適切」 という語句が含まれている。
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=not opportunity_customer_accounts/any(o:o/description eq null and
o/budgetamount le 300 or
contains(o/description, 'bad')) and
opportunity_customer_accounts/any() and
endswith(name,'{0}') HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
単一値のナビゲーション プロパティに基づく行 (レコード) のフィルター処理
ナビゲーション プロパティを使用すると、現在のエンティティと関連付けられたデータにアクセスすることができます。 単一値 ナビゲーション プロパティは、多対 1 関係をサポートし、別のエンティティに対する参照が設定できるような検索属性に対応します。 詳細: ナビゲーション プロパティ を参照してください。
単一値ナビゲーション プロパティの値に基づき、エンティティ セット レコードをフィルター処理することができます。 たとえば、指定された取引先企業の、子取引先企業を取得することができます。
たとえば、次のようなものです。
指定された取引先担当者 ID に一致するすべての取引先企業を取得する
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name &$filter=primarycontactid/contactid eq a0dbf27c-8efb-e511-80d2-00155db07c77 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)", "value":[ { "@odata.etag":"W/\"513479\"", "name":"Adventure Works (sample)", "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77" }, { "@odata.etag":"W/\"514057\"", "name":"Blue Yonder Airlines (sample)", "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77" } ] }
指定された取引先企業 ID に対する子会社を取得
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name &$filter=parentaccountid/accountid eq 3adbf27c-8efb-e511-80d2-00155db07c77 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)", "value":[ { "@odata.etag":"W/\"514058\"", "name":"Sample Child Account 1", "accountid":"915e89f5-29fc-e511-80d2-00155db07c77" }, { "@odata.etag":"W/\"514061\"", "name":"Sample Child Account 2", "accountid":"03312500-2afc-e511-80d2-00155db07c77" } ] }
コレクション値ナビゲーション プロパティの値に基づいて結果をフィルター処理します。
注意
$expand
で $filter
を使用して、取得操作で関連レコードの結果をフィルターすることは可能です。 コレクション値ナビゲーション プロパティ名の後に、かっこで囲まれるシステム クエリ オプションのセミコロン区切りリストを使用できます。 $expand
でサポートされているクエリ オプションは $select
、$filter
、$top
、および $orderby
です。 詳細: 拡張されたレコードに適用するためのオプション。
コレクション値ナビゲーション プロパティの値に基づいて結果をフィルター処理する 2 つのオプションを次に示します:
ラムダ演算子を使用してクエリを構築する
ラムダ演算子を使用することで、リンク エンティティの収集プロパティの値にフィルターを適用することができます。 以下の例では、
team
およびteammembership
エンティティ タイプにリンクされている、systemuser
エンティティ タイプのレコードを取得します。つまり、「CITTEST」 という名前のチームの管理者を兼ねているsystemuser
レコードを取得します。GET [Organization URI]/api/data/v9.2/systemusers?$filter=(teammembership_association/any(t:t/name eq 'CITTEST')) &$select=fullname,businessunitid,title,address1_telephone1,systemuserid &$orderby=fullname Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0
詳細については次を参照してください: ラムダ演算子を使用する
複数の操作を使用して、コレクションの値に基づく個々のエンティティの結果フィルター処理を繰り返します
上記の例と同じ結果を得るには、2つのエンティティ タイプのレコードを取得し、一方のエンティティのコレクションの値を他方のエンティティの値と繰り返し照合することで、コレクションの値に基づいてエンティティをフィルター処理します。
以下の例の手順に従って、反復メソッドを使用して結果をフィルターする方法を理解します。
- team._administratorid_value 値の個別一覧を入手してください。
GET [OrganizationURI]/api/data/v9.2/teams?$select=_administratorid_value&$filter=_administrator_value ne null
- 次に戻り値をループ処理して重複を取り除き、個別一覧を取得します。 すなわち、新しい配列を作成し、クエリ結果をループしてそれぞれが新しい配列にすでに存在するかどうかを確認し、存在しない場合は追加します。 これで個別の
systemuserid
値の一覧を与えます。 - JavaScript と C# でこれをする方法は異なりますが、基本的に同じ結果が得られます。
- ContainValues Query Function を使用して systemuser をクエリし、
systemuserid
値をステップ 1 で収集した一覧と比較します。
- team._administratorid_value 値の個別一覧を入手してください。
文字列フィルター値で一重引用符を管理する
O'Brian
または Men's clothes
のように、一重引用符 (アポストロフィ) 文字を含む In Query Function のような文字列値の配列を受け入れるフィルターで比較する値を指定する場合、値を二重引用符で囲む必要があります。 例:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]
そうしない場合、次のエラーが発生します。Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.
フィルターを単一の値に使用する場合は、一重引用符を連続する 2 つの一重引用符文字に置き換えます。 例:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'
そうしない場合、次のようなエラーが発生します。There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.
結果を並べ替える
項目が返される順番を、$orderby
システム クエリ オプションを使用して指定します。 asc
または desc
接尾辞を使用して、それぞれ昇順または降順を指定します。 接尾辞が適用されない場合、既定は昇順です。 以下の例では、取引先企業の名前および売り上げプロパティを、売り上げを昇順で、名前を降順で取得します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null
結果の集計およびグループ化
$apply
を使用すると、データを動的に集計およびグループ化することができます。 $apply
を使用する可能性のある例:
使用例 | 例 |
---|---|
クエリ内の一意のステータスのリスト | accounts?$apply=groupby((statuscode)) |
状態の値ごとの件数 | accounts?$apply=groupby((statuscode),aggregate($count as count)) |
予想値合計の集計 | opportunities?$apply=aggregate(estimatedvalue with sum as total) |
予想値およびステータスに基づく取引の平均サイズ | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)) |
ステータスに基づく予測値の合計 | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total)) |
アカウント名ごとの営業案件の売上合計 | opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total)) |
「WA」 の取引先企業の取引先責任者名 | accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname)) |
最後に作成されたレコードの日時 | accounts?$apply=aggregate(createdon with max as lastCreate) |
最初に作成されたレコードの日時 | accounts?$apply=aggregate(createdon with min as firstCreate) |
集計機能は 50,000 レコードのコレクションに制限されます。 Dataverse での集計機能の使用については、FetchXML の使用によるクエリの作成を参照してください
OData データ集計の追加の詳細はこちらを参照してください: データ集計用 OData 拡張 バージョン 4.0。 Dataverse はこれらの集計手法のサブセットのみをサポートすることに注意してください。
システム クエリ オプションを持つパラメーター エイリアスを使用します
次のパラメータ エイリアスを $filter
と $orderby
システム クエリ オプションで使用できますが、現在は$expand
オプション内ではありません。 パラメーター エイリアスは、1 つの要求の中で同じ値を複数回使用することができます。 エイリアスが値が割り当てられていない場合は、null であると判断します。
パラメーター エイリアスなし:
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null
パラメーター エイリアスあり:
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name
また、関数を使用するとき、パラメーター エイリアスを使用することもできます。 詳細: Web API 機能を使用
行数の取得
$count
システム クエリ オプションを true
の値と共に使用して、フィルター条件と一致するエンティティ数を最大 5000 含めます。
注意
カウント値はシステム内の行の総数を表すものではありません。 これは、返される行数の最大数により制限されています。 詳細: 返される行数の制限
5000 行を超えるテーブルの総行数を取得したい場合は、RetrieveTotalRecordCount Function を使用します。
応答の @odata.count
注釈には、odata.maxpagesize
基本設定の制限に関係なく、最大 5000 の行数が含まれます。
カウント値が 5000 で、カウントがちょうど 5000 であるか、5000 より大きいかを知る必要がある場合は、Prefer``odata.include-annotations="Microsoft.Dynamics.CRM.*"
ヘッダーを追加できます。 これにより、結果に次の注釈が追加されます: @Microsoft.Dynamics.CRM.totalrecordcount
と @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded
。
$count
クエリ オプションと一緒に使用する場合に、5000 を超えるレコードがあると、次の値が表示されます:
"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
5000 未満のレコードがある場合は、実際のカウントが返されます。
"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
$count
クエリ オプションを含めない場合、@Microsoft.Dynamics.CRM.totalrecordcount
の合計値は -1
になります。
注意
$top
を $count
と共に使用しないでください。
次の例では、名前に "sample" が含まれるという条件と一致する 10 の取引先企業があることが示されますが、最初の 3 つの取引先企業のみが返されます。
要求
GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"
応答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
"@odata.count":10,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
"value":[
{
"@odata.etag":"W/\"502482\"",
"name":"Fourth Coffee (sample)",
"accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
},
{
"@odata.etag":"W/\"502483\"",
"name":"Litware, Inc. (sample)",
"accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
},
{
"@odata.etag":"W/\"502484\"",
"name":"Adventure Works (sample)",
"accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
}
],
"@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
カウント以外のデータを返さないようにするには、$count
を任意のコレクションに適用して、値のみを取得します。 この場合、結果がコレクションではなく数字であるため、Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"
ヘッダーを適用できません。
要求
GET [Organization URI]/api/data/v9.2/accounts/$count 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
10
書式設定値を含める
プロパティが結果と共にフォーマットされた値を受け取るようにしたいときは、odata.include-annotations
基本設定を OData.Community.Display.V1.FormattedValue
の値で使用します。 応答には、以下の命名規則と一致するプロパティと共に、これらの値が含まれます。
<propertyname>@OData.Community.Display.V1.FormattedValue
次の例は、取引先企業用のエンティティ セットをクエリし、フォーマットされた値をサポートするプロパティを含む、最初のレコードを返します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue
&$top=1 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
"value":[
{
"@odata.etag":"W/\"502170\"",
"name":"Fourth Coffee (sample)",
"donotpostalmail@OData.Community.Display.V1.FormattedValue":"Allow",
"donotpostalmail":false,
"accountratingcode@OData.Community.Display.V1.FormattedValue":"Default Value",
"accountratingcode":1,
"numberofemployees@OData.Community.Display.V1.FormattedValue":"9,500",
"numberofemployees":9500,
"revenue@OData.Community.Display.V1.FormattedValue":"$100,000.00",
"revenue":100000,
"accountid":"89390c24-9c72-e511-80d4-00155d2a68d1",
"transactioncurrencyid_value":"50b6dd7b-f16d-e511-80d0-00155db07cb1"
}
]
}
クエリで関連テーブル レコードを取得する
ナビゲーション プロパティの $expand
システム クエリ オプションを使用して、関連エンティティからどのデータが返されるかをコントロールします。 詳細: クエリで関連テーブル レコードを取得する。
検索プロパティに関するデータの取得
クエリに検索プロパティが含まれる場合、これらのプロパティ内のデータに関する追加情報を提供する、注釈を要求することができます。 通常、同じデータは、単一値のナビゲーション プロパティの知識、および関連するエンティティに含まれるデータを使用して生成することができます。 ただし、プロパティが、複数の種類のエンティティを参照する可能性がある検索属性である場合、この情報から検索プロパティがどの種類のエンティティを参照するか知ることができます。 詳細: 検索プロパティ。
これらのプロパティで使用できる、2 種類の追加の注釈があります。
Annotation | 内容 |
---|---|
Microsoft.Dynamics.CRM.associatednavigationproperty | エンティティへの参照を含む、単一値のナビゲーション プロパティの名前。 |
Microsoft.Dynamics.CRM.lookuplogicalname | 検索が参照するエンティティの論理名。 |
また、これらのプロパティには、「書式設定値を含める」で説明されているように、フォーマットされた値を含めることができます。 書式設定されている値と同様に、odata.include-annotations
基本設定セットを使用して、適切な特定の注釈の種類に対して他の注釈を返したり、値に "*"
を設定して 3 つすべてを返すことができます。 次の例では、インシデント エンティティの _customerid_value
検索プロパティおよびそれに含まれる注釈に関する情報を取得するための、要求および応答を示します。
要求
GET [Organization URI]/api/data/v9.2/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,_customerid_value
&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"
応答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
"@odata.etag":"W/\"504696\"",
"_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
"_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
"_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
"_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
"incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
"customerid_contact":{
"@odata.etag":"W/\"503587\"",
"fullname":"Susanna Stubberod (sample)",
"contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
}
}
変更の追跡を使用してデータを外部システムに同期
変更の追跡機能を使用することで、データが最初に抽出された後、あるいはデータが最後に同期された後で変更されたデータを検出し、データの同期を効率的に維持することができます。 エンティティの変更は、odata.track-changes
を基本設定ヘッダーとして追加し、Web API リクエストを使用して追跡できます。 プリファレンス ヘッダーの odata.track-changes
は、エンティティの変更を取得するために使用する、デルタ リンクを返すことを要求します。
詳細については次を参照してください: 変更の追跡を使用して、データを外部システムと同期する
Web API を使用した列の比較
次の例は、Web API を使用して列を比較する方法を示しています。
https://<environment-root>/contacts?$select=firstname&$filter=firstname eq lastname
詳細: クエリで列比較を使用する
参照
Dataverse 検索を使用してテーブル データ全体を検索する
簡易検索の検索アイテム制限の操作
Web API クエリ データのサンプル (C#)
Web API クエリ データのサンプル (クライアント側の JavaScript)
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用してテーブル行を作成する
Web API を使用してテーブルの行を取得する
Web API を使用したテーブル行の更新と削除
Web API を使用したテーブル行の関連付けと関連付け解除
Web API 関数の使用
Web API アクションの使用
Web API を使用してバッチ操作を実行する
Web API を使用して別のユーザーを偽装する
Web API を使用する条件付き演算を実行する
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
フィードバックの送信と表示