Web API を使用したデータのクエリ
クエリを作成する際は、必ず次の決定を行います。
決定 | Description |
---|---|
列を選択する | どのデータ列を返すか |
テーブルの結合 | どの関連テーブルを結果に含めるか |
行を並べ替える | どの順序で結果を返すか |
行のフィルター | どのデータ行を返すか |
ページの結果 | 何件のデータ行を返すか |
データの集計 | 返されたデータのグループ化と集計を行う方法 |
行数をカウントする | 行数の数え方 |
この記事では、Dataverse Web API でデータを取得するクエリを構築する際に、これらの決定で求められる情報を提供します。
注意
この記事では、テーブルで見つかったデータのクエリを解説します。 また Web API を使用して、テーブル定義 またはエンティティに関するデータもクエリできます。 データの構造が異なるため、ここで説明する機能のほとんどが適用されません。 詳細情報: Web API を使用してテーブル定義をクエリ と スキーマ定義のクエリ
エンティティ コレクション
すべてのクエリはエンティティのコレクションで始まります。 エンティティ コレクションは、次のいずれかです。
- EntitySet resources: Web API EntitySet コレクションの 1 つ。
- フィルターしたコレクション: 特定のレコードに対して コレクション値ナビゲーション プロパティ ごとに返される一連のエンティティ。
- 展開したコレクション値ナビゲーション プロパティ。 詳細情報: コレクション値のナビゲーション プロパティを展開する
EntitySet リソース
環境で利用できるすべての EntitySet リソースを見つける場合は、GET
要求を Web API サービス ドキュメント に送信します。
Request
GET [Organization URI]/api/data/v9.2/
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",
"value": [
{
"name": "aadusers",
"kind": "EntitySet",
"url": "aadusers"
},
{
"name": "accountleadscollection",
"kind": "EntitySet",
"url": "accountleadscollection"
},
{
"name": "accounts",
"kind": "EntitySet",
"url": "accounts"
},
... <Truncated for brevity>
[
}
ヒント
これらの値は通常、テーブル名の複数形です。 しかし異なる場合があります。 このクエリを使用して、使用している EntitySet リソース名が適切であることを確認します。
アカウント EntityType からデータを取得する場合は、accounts
EntitySet リソースから始めます。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
フィルターしたコレクション
指定したレコードのコレクション値ナビゲーション プロパティで表されるエンティティの、任意のコレクションをクエリできます。
特定のユーザーが OwningUser である アカウント EntityType からデータを取得する場合は、指定した systemuser レコードの user_accounts
コレクション値ナビゲーション プロパティを使用できます。
GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name
コレクション値のナビゲーション プロパティの名前を見つけます
- Dataverse テーブルと関係については Web API Entity Type Reference を確認できます
- カスタム テーブルやリレーションシップについては、$metadata サービス ドキュメント で コレクション値ナビゲーション プロパティ を探します
OData クエリ オプション
Dataverse Web API は、次の OData クエリ オプションに対応しています。
回答内容 | 用途 | 詳細情報 |
---|---|---|
$select |
エンティティや複合型ごとに特定のプロパティ セットを要求します。 | 列を選択する |
$expand |
取得したリソースに合わせて、含めるべき関連リソースを指定します。 | テーブルの結合 |
$filter |
リソースのコレクションをフィルターします。 | 行のフィルター |
$orderby |
特定の順序でリソースを要求します。 | 行を並べ替える |
$apply |
データを集約し、グループ化します。 | データの集計 |
$top |
クエリしたコレクションの、結果に含めるべき項目の数を指定します。 データのページを取得する際は $top を使用できません。 |
$top クエリ オプションを使用する |
$count |
応答のリソースに含まれる、一致するリソースの件数を要求します。 | 行数をカウントする |
クエリには複数のオプションを適用できます。 必ず '?
' を使用し、すべてのクエリ オプションをリソース パスから分離します。 最初のオプションの後に、アンパサンド ('&
') を使用して各オプションを区切ります。 すべてのオプションの名前では大文字と小文字を区別します。
Dataverse Web API は次の OData クエリ オプション に対応していません: $skip
、$search
、$format
。
クエリ オプションを持つパラメーター エイリアスを使用します
次のパラメーター エイリアスを、$expand
オプション内ではなく、$filter
と $orderby
クエリ オプションで使用できます。 パラメーター エイリアスは、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 機能を使用
列を選択する
重要
データをクエリする場合は、返されるデータの量を制限してパフォーマンスを最適化することが重要です。 必要なデータを含む列のみを選択してください。
$select
クエリ オプション を使用して、クエリで返す列を選択します。 $select
クエリ オプションを含めない場合、すべてのプロパティを返します。 OData では、すべての列を プロパティ として表現します。 詳細情報: Web API プロパティ
次の例では、accounts
EntitySet リソースの 1 つの行から、name
と revenue
のプロパティを要求します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=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,revenue)",
"value": [
{
"@odata.etag": "W/\"81052965\"",
"name": "Litware, Inc. (sample)",
"revenue": 20000.0000,
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
"accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
}
]
}
主キー プロパティは常に返されるため、$select
に含める必要はありません。 この例では accountid
が主キーです。
他のプロパティ値も含む場合があります。 この場合、revenue
は通貨プロパティであるため、関連する 通貨 (TransactionCurrency) テーブル/エンティティ参照 の _transactioncurrencyid_value
検索プロパティ を含みます。
どのプロパティを利用できますか?
エンティティで使用できるプロパティは、すべて $metadata サービス ドキュメント で確認できます。 詳細情報: Web API プロパティ
Dataverse が含むエンティティ タイプについては、Web API Entity Type Reference を参照してください。
ヒント
どのプロパティを利用できるかをすばやく発見する最も簡単な方法は、$select
を使用せずに 1
の値で $top
クエリ オプションを使用し、要求を送信することです。
書式設定された値
書式設定した値とは、サーバーで生成される文字列値であり、これはアプリケーションで使用できます。 書式設定した値を次に示します。
- 単一選択、複数選択、はい/いいえ、状態、ステータス列のローカライズされたラベル
- 検索と所有者のプロパティに対するプライマリ名の値
- 通貨記号を含む通貨値。
- ユーザーのタイムゾーンに合わせて書式設定した日付値
書式設定された値を結果に含める際は、次の要求ヘッダーを使用します。
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
書式設定した値は、要求できるいくつかの注釈の 1 つです。 Prefer: odata.include-annotations="*"
を使用すると注釈をすべて含めます。 詳細情報: 注釈の要求
書式設定された値が、次の規則に沿った注釈付きのレコードと共に返されます。
<property name>@OData.Community.Display.V1.FormattedValue
これを次の例で示します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
この応答は、要求したプロパティの値と書式設定された値を返します。
Property | 価値 | 書式設定された値 |
---|---|---|
name |
Litware, Inc. (sample) |
None |
revenue |
20000.0000 |
$20,000.00 |
_primarycontactid_value |
70bf4d48-34cb-ed11-b596-0022481d68cd |
Susanna Stubberod (sample) |
customertypecode |
1 |
Competitor |
modifiedon |
2023-04-07T21:59:01Z |
4/7/2023 2:59 PM |
_transactioncurrencyid_value |
228f42f8-e646-e111-8eb7-78e7d162ced1 |
US Dollar |
accountid |
78914942-34cb-ed11-b596-0022481d68cd |
None |
回答
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,revenue)",
"value": [
{
"@odata.etag": "W/\"81359849\"",
"name": "Litware, Inc. (sample)",
"revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
"revenue": 20000.0000,
"_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
"_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
"customertypecode": 1,
"modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
"modifiedon": "2023-04-07T21:59:01Z",
"_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd"
}
]
}
検索プロパティ データ
検索プロパティ が複数テーブル (ポリモーフィック) のリレーションシップを表す場合、特定の注釈を要求して、どのテーブルが関連データを含むかを判断する必要があります。
たとえば多くのテーブルは、ユーザーやチームが所有する可能性があるレコードを含みます。 このデータは ownerid
という名前の検索列に格納されます。 この列は OData の単一値ナビゲーション プロパティです。 $expand
を使用して結合を作成し、この値を取得できますが、$select
は使用できません。 ただし、対応する _ownerid_value
検索プロパティを $select
で使用できます。
$select
に _ownerid_value
検索プロパティを含めると、GUID 値を返します。 レコードの所有者がユーザーかチームかを、この値から判断できません。 このデータを取得する場合は、注釈を要求する必要があります。
これらの注釈を結果に含める際は、次の要求ヘッダーを使用します。
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"
ヒント
または Prefer: odata.include-annotations="*"
を使用して、注釈をすべて含めます。 詳細情報: 注釈の要求
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"
次の応答は、異なるアカウント レコードを 2 つ返します。 team
は最初のものを所有し、systemuser
は 2 番目のものを所有します。 _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname
注釈は、次の情報を提供します。
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
"value": [
{
"@odata.etag": "W/\"81550512\"",
"name": "Adventure Works (sample)",
"_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
"_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
"_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
"accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
},
{
"@odata.etag": "W/\"81359849\"",
"name": "Litware, Inc. (sample)",
"_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
"_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
"_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd"
}
]
}
<lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname
は関連するテーブルの論理名です。<lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty
は、対応する単一値ナビゲーション プロパティの名前です。 別の要求でこの値を使用する$expand
を使用し、さらに多くのデータを関連レコードから取得できます。
テーブルの結合
ナビゲーション プロパティの $expand
クエリ オプション を使用して、関連テーブル レコードからどのデータが返されるかをコントロールします。
注意
- クエリ内の
$expand
オプションは 15 個までに制限されています。 これはパフォーマンスを保護するためです。 各$expand
オプションは、パフォーマンスに影響を与える可能性のある結合を作成します。 - コレクション値ナビゲーション プロパティを展開するクエリは、最新の変更を反映しないそれらのプロパティのキャッシュされたデータを返すことがあります。 ブラウザのキャッシュを上書きするには、
If-None-Match
ヘッダーと値null
を使用することをお勧めします。 詳細については、HTTP ヘッダー をお読みください。
特定の $expand
オプションで、次の クエリ オプション を適用できます。
回答内容 | Description |
---|---|
$select |
どのプロパティが返されたかを選択します。 詳細情報: 列の選択 |
$filter |
コレクション値ナビゲーション プロパティの場合は、返されたレコードを制限します。 詳細情報: 行のフィルター |
$orderby |
コレクション値のナビゲーション プロパティの場合は、返されたレコードの順序をコントロールします。 入れ子になった $expand は、サポートされていません。 詳細情報: コレクション値のナビゲーション プロパティで入れ子になった $expand |
$top |
コレクション値のナビゲーション プロパティの場合は、返されたレコードの数を制限します。 入れ子になった $expand は、サポートされていません。 詳細情報: コレクション値のナビゲーション プロパティで入れ子になった $expand |
$expand |
関連するエンティティのセットでナビゲーション プロパティを拡張します。 $expand で $expand を使用することを、入れ子になった $expand と呼びます。 詳細: 単一値ナビゲーション プロパティの入れ子になった拡張 & コレクション値のナビゲーション プロパティで入れ子になった $expand |
OData バージョン 4.0 パート 1: プロトコル プラス Errata 02 の 11.2.4.2.1 拡張オプション セクションに記載されているクエリ オプションの一部です。 オプション $skip
、$count
、$search
、および $levels
は、Dataverse Web API ではサポートされていません。
$expand
のあるこれらのオプションは、ナビゲーション プロパティの名前の後に括弧で囲んで追加して使用します。 各オプションをセミコロンで区切ります。
たとえば、以下のクエリ:
account.name
プロパティを要求します以下を要求する
AccountTasks
コレクション値ナビゲーション プロパティを結合します。task.subject
プロパティtask.subject
が文字列 "Task
" を含む場所task.createdon
の日付で降順に並べ替え済み
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)
$selectで列を制限する
他のクエリと同様に、$expand
を使用する場合は、$select
を使用して返される列を常に制限します。 たとえば、次のリクエストは、エンティティ型から拡張された結果の contact.fullname``account
と task.subject
の値を返します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=1
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
},
"Account_Tasks": [
{
"@odata.etag": "W/\"80649460\"",
"subject": "Task 1 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
ナビゲーション プロパティ型の違い
ナビゲーション プロパティには次の 2 種類があることにご注意ください。 詳細情報: Web API ナビゲーション プロパティ
単一値 ナビゲーション プロパティは、多対一関係をサポートし、別のレコードに対する参照が設定できるような検索属性に対応します。
コレクション値 ナビゲーション プロパティは 1 対多または多対多の関連付けに対応します。
コレクション値のナビゲーション プロパティを展開すると、応答のサイズが拡大し、その予測が困難になる場合があります。 返されるデータの量をコントロールする制限を含めることが重要です。 ページングを使用して、レコード件数を制限できます。 詳細情報: ページの結果
注意
コレクション値のナビゲーション プロパティに適用される入れ子になった $expand オプションにページングが適用される方法には、大きな違いがあります。 詳細情報: コレクション値のナビゲーション プロパティを展開する
単一値のナビゲーション プロパティを展開する
次の例は、取引先責任者とレコードを作成したユーザーを含む取引先担当者レコードを取得する方法を示しています。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"fullname": "Susanna Stubberod (sample)"
},
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
},
{
"@odata.etag": "W/\"80649580\"",
"name": "Adventure Works (sample)",
"accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
"fullname": "Nancy Anderson (sample)"
},
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
注意
createdby
単一値ナビゲーション プロパティは、systemuser EntityType のインスタンスを返します。 systemuserid
と ownerid
のプロパティを両方とも返します。 この理由は、systemuser
が プリンシパル EntityType から継承し、この継承によって ownerid
プライマリ キーを チーム EntityType と共有するためです。
ただし、ユーザー (SystemUser) テーブル は SystemUserId の主キーを含みます。 systemuserid
と ownerid
のプロパティは両方とも同じ値を含みます。 詳細: EntityType の継承
参照を返す
データを返す代わりに、/$ref
オプションを使用して単一値ナビゲーション プロパティを展開することで、関連レコードへの参照 (リンク) を返すこともできます。 次の例では、各取引先責任者の URL を含む @odata.id
プロパティを持つ JSON オブジェクトを返します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
}
},
{
"@odata.etag": "W/\"80649580\"",
"name": "Adventure Works (sample)",
"_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
単一値ナビゲーション プロパティのある /$ref
オプションのみを使用できます。 コレクション値ナビゲーション プロパティで使用する場合、以下のエラーが表示されます。
{
"error": {
"code": "0x80060888",
"message": "Expand with $ref is only supported on lookup type navigation property."
}
}
単一値ナビゲーション プロパティの入れ子になった展開
$expand
オプションを別の $expand
オプション内に入れ子にすることで、単一値ナビゲーション プロパティを複数のレベルに展開することができます。
次のクエリは、task
レコードを返し、関連する contact
、contact
に関連する account
、そして最後に account
レコードを作成した systemuser
を展開します。
Request
GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
$expand=parentcustomerid_account($select=name;
$expand=createdby($select=fullname)))
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
"value": [
{
"@odata.etag": "W/\"80730855\"",
"subject": "Task 1 for Susanna Stubberod",
"activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"parentcustomerid_account": {
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
},
{
"@odata.etag": "W/\"80730861\"",
"subject": "Task 2 for Susanna Stubberod",
"activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"parentcustomerid_account": {
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
コレクション値のナビゲーション プロパティの展開
クエリ内の任意の場所で、コレクション値ナビゲーション プロパティのある入れ子になった $expand
を使用するかどうかによって、応答に重大な違いが発生します。
入れ子になった $expand | 単一 $expand | |
---|---|---|
Paging | 展開された行のページング。 | EntitySet リソース でのみページングします。 展開された行の <property name>@odata.nextLink URL には、ページング情報は含まれません。 |
$top または $orderby がサポートされています |
番号 | イエス |
コレクション値ナビゲーション プロパティの単一 $expand
単一レベル $expand
のみを使用する場合、展開された行にページングは適用されません。 Prefer: odata.maxpagesize
要求ヘッダーを含めると、ページングはクエリの EntitySet リソースにのみ適用されます。
展開されたコレクション値の各ナビゲーション プロパティは、ページング情報を含まない <property>@odata.nextLink
URL を返します。 これはクエリ オプションを追加したリレーションシップの フィルターしたコレクション を表す URL です。 その URL を使用して別の GET
要求を送信すると、元の要求で返されたものと同じ行が返されます。 その要求にページングを適用できます。
注意
展開したレコードにはページングが適用されないため、展開したコレクション値の各ナビゲーション プロパティに対して、最大 5000 件の関連レコードを返すことができます。 データとクエリによって、これは大量のデータになる可能性があります。 これはパフォーマンスに影響を与え、要求のタイムアウトを引き起こします。作成するクエリに注意してください。 $top
、$filter
、および $orderby
オプションを使用して、返されるレコードの総数をコントロールできます。
次の例には、取引先企業レコードを取得する際の Account_Tasks
と contact_customer_accounts
の単一展開が含まれています。 Prefer: odata.maxpagesize=1
要求ヘッダーにより、最初のページで取引先企業レコードが 1 つだけ返されることが保証されます。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)
Prefer: odata.maxpagesize=1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"Account_Tasks": [
{
"@odata.etag": "W/\"80730894\"",
"subject": "Task 1 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
},
{
"@odata.etag": "W/\"80730903\"",
"subject": "Task 2 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
},
{
"@odata.etag": "W/\"80730909\"",
"subject": "Task 3 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
"contact_customer_accounts": [
{
"@odata.etag": "W/\"80648695\"",
"fullname": "Susanna Stubberod (sample)",
"_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
注意
この応答を、入れ子になった $expand
を含む次の例と比較してください。
例の応答を水平方向にスクロールして、取引先企業結果の @odata.nextLink
URL にのみページング情報が含まれていることを確認できます。
コレクション値ナビゲーション プロパティの入れ子になった $expand
入れ子になった $expand
をクエリの任意の場所で使用し、Prefer: odata.maxpagesize
要求ヘッダーを含めた場合、展開された各コレクションにページングが適用されます。
展開されたコレクション値の各ナビゲーション プロパティは、ページング情報を含む <property>@odata.nextLink
URL を返します。 その URL を使用して別の GET
要求を送信すると、元の要求で含まれていなかった次のレコード セットが返されます。
$top
または $orderby
オプションを使用して、入れ子になった $expand
で返されるレコードの総数を制限することはできません。 これらのオプションを使用すると、次のエラーが返されます。
{
"error": {
"code": "0x80060888",
"message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
}
}
この例は、前の例に基づいており、同じデータを使用しています。 この URL の唯一の違いは、取引先企業の所有ユーザを返すために、入れ子になった $expand
を単一値のナビゲーション プロパティに追加したことです: ;$expand=owninguser($select=fullname)
。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname))
Prefer: odata.maxpagesize=1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"Account_Tasks": [
{
"subject": "Task 1 for Litware",
"activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
"contact_customer_accounts": [
{
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"owninguser": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
],
"contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
注意
この応答を、入れ子になった $expand
を使用しない前の例と比較してください。
この応答では、Prefer: odata.maxpagesize=1
要求ヘッダーは、Account_Tasks
と一緒に返された task
レコードに適応されます。 3 つではなく、1 つのタスクのみが返されます。 Account_Tasks@odata.nextLink
URL は次の 2 つのタスクを返します。
Account_Tasks@odata.nextLink
、contact_customer_accounts@odata.nextLink
、および @odata.nextLink
URL にページング情報が含まれているかを確認するには、応答例を水平方向にスクロールします。
行を並べ替える
$orderby
クエリ オプション を使用して、項目が返される順序を指定します。 asc
または desc
接尾辞を使用して、それぞれ昇順または降順を指定します。 接尾辞が適用されない場合、既定は昇順です。 以下の例では、取引先企業の name
および revenue
プロパティを、revenue
を昇順で、name
を降順で取得します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null
行のフィルター
$filter
クエリ オプション を使用して、リソースのコレクションをフィルターします。
Dataverse は、$filter
に設定した式によって、コレクションが含む各リソースを評価します。 その式が true
と評価したレコードのみを応答で返します。 その式が false
や null
と評価する場合、またはユーザーがレコードへの読み取りアクセス許可を持っていない場合、レコードは返されません。
$filter
式を作成する際は、次の演算子と関数を適用できます。
Description | 詳細情報 | |
---|---|---|
比較演算子 | プロパティと値を比較する際は演算子 eq 、ne 、gt 、ge 、lt 、le を使用します。 |
比較演算子 |
論理演算子 | and 、or 、not を使用して、より複雑な式を作成します。 |
論理演算子 |
グループ化演算子 | 括弧 ( & ) を使用して、複雑な式を評価する優先順位を指定します。 |
グループ化演算子 |
OData クエリ関数 | contains 、endswith 、startswith 関数を使用して文字列値を評価します。 |
OData クエリ関数を使用する |
Dataverse クエリ関数 | ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 | Dataverse クエリ関数 |
ラムダ式 | 関連するコレクションの値に基づいて式を作成します。 | 関連するコレクションの値でフィルターする |
ヒント
また、フィルターしたコレクション も使用できることに注意してください。
さらに $filter
で 検索プロパティ を使用している場合、フィルターしたコレクションを対応するコレクション値ナビゲーション プロパティと共に使用できます。
たとえば、次の 2 つのクエリは同じ結果を返します。
accounts?$filter=_owninguser_value eq '<systemuserid value>'&$select=name
systemusers(<systemuserid value>)/user_accounts?$select=name
比較演算子
プロパティと値を比較する際は、次の比較演算子を使用します。
Operator | Description | 例 |
---|---|---|
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 |
列の比較
比較演算子を使用して、同じ行が含むプロパティ値を比較できます。 たとえば次のクエリは、firstname
と lastname
が等しい連絡先をすべて返します。
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname
注意
- 同じ行が含む値の比較に使用できるのは、比較演算子のみです。
- 列のタイプは一致させる必要があります。
詳細: クエリで列比較を使用する
論理演算子
次の論理演算子を使用して、より複雑な式を作成します。
Operator | Description | 例 |
---|---|---|
and |
論理積 | $filter=revenue lt 100000 and revenue gt 2000 |
or |
論理和 | $filter=contains(name,'(sample)') or contains(name,'test') |
not |
論理否定 | $filter=not contains(name,'sample') |
グループ化演算子
論理演算子とともに括弧 (
& )
を使用して、複雑な式を評価する優先順位を指定します。 例:
$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000
Dataverse クエリ関数
ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 こうした関数は、次のテーブルで説明する特化した機能を提供します。
注意
Contains 機能 は、全文インデックスをもった列で使用します。 全文インデックスをもった列を含むのは Dynamics 365 KBArticle (記事) テーブルのみです。 代わりに OData contains
関数を使用してください。
完全なリストは Web API Query Function Reference で参照してください。 各記事に記載された構文の例をコピーできます。
これらの関数の 完全修飾名 を使用する必要があります。 完全修飾名とは、関数の名前に サービス名前空間 (Microsoft.Dynamics.CRM
) を追加する必要があることを意味します。
各関数には、評価するべきプロパティを指定する PropertyName
パラメーターがあります。 一部の関数には、PropertyValue
、PropertyValues
、PropertyValue1
、PropertyValue2
などのパラメーターが、さらに存在する場合があります。 これらのパラメーターが存在する場合、PropertyName
パラメーターと比較する値を必ず指定します。
次の例は、Between 関数 を使用して従業員数が 5~2000 人であるアカウントの検索方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])
文字列値を使用してフィルターする
文字列値をフィルターする際は、次の点に注意してください。
- 文字列値を使用するすべてのフィルターは、大文字と小文字を区別しません。
- ワイルドカード文字を使用できますが、末尾に使用するべきではありません。 詳細情報: ワイルドカード文字を使用する
- OData クエリ関数
contains
、startswith
、endswith
を使用できます。 詳細情報: OData クエリ関数を使用する - 文字列値の配列を受け入れるフィルターを使用する場合は、一重引用符を管理する必要があります。 詳細情報: 一重引用符を管理する
ワイルドカード文字を使用する
文字列を使用してフィルターを構成する場合、次のワイルドカード文字を適用できます。
登場人物 | Description | T-SQL のドキュメントと例 |
---|---|---|
% |
0 文字以上の任意の文字列に一致します。 このワイルドカード文字は、接頭辞または接尾辞として使用できます。 | パーセント記号 (ワイルドカード - 一致する文字) (Transact-SQL) |
_ |
アンダースコア文字を使用して、パターン マッチングを含む文字列比較操作で任意の 1 文字を照合します。 | _ (ワイルドカード - 1 つの文字に一致) (Transact-SQL) |
[] |
かっこで囲まれた指定範囲またはセット内の任意の 1 文字に一致します。 | [ ] (ワイルドカード - 一致する文字) (Transact-SQL) |
[^] |
角かっこで囲まれた指定範囲またはセット内にはない任意の 1 文字に一致します。 | [^] (ワイルドカード - 一致しない文字) (Transact-SQL) |
末尾のワイルドカードには対応していません
ワイルドカード文字を使用する場合、ワイルド カードを末尾に使用しないことが重要です。 これには対応していません。 これらのアンチ パターンを使用するクエリでは、クエリを最適化できないため、パフォーマンスの問題が発生します。 末尾に使用したワイルドカードの例:
startswith(name,'%value')
endswith(name,'value%')
OData クエリ関数を使用する
次の OData クエリ関数を使用して、文字列値をフィルターします。
Function | 例 |
---|---|
contains |
$filter=contains(name,'(sample)') |
endswith |
$filter=endswith(name,'Inc.') |
startswith |
$filter=startswith(name,'a') |
これらの関数を論理演算子 not
と一緒に使用し、結果を否定できます。
一重引用符を管理する
O'Brian
や Men's clothes
のように、一重引用符 '
(アポストロフィ) 文字を含む In クエリ関数 のような文字列値の配列を受け入れるフィルターで比較する値を指定する場合、値を二重引用符で囲む必要があります。 例:
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''.
関連するデータ値に基づくフィルター
関連テーブルの値に基づいて、返された行をフィルターできます。 フィルターする方法は、リレーションシップのタイプによって異なります。
検索列のプロパティ値を使用してフィルターする
検索列を表す単一値ナビゲーション プロパティの値に基づいてフィルターできます。 このパターンを使用します:
<single-valued navigation property>/<property name>
次の例は、primarycontactid/fullname
列の値に基づいてアカウント レコードを返します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
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,_primarycontactid_value)",
"value": [
{
"@odata.etag": "W/\"81359849\"",
"name": "Litware, Inc. (sample)",
"_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
"_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd"
}
]
}
また、単一値のナビゲーション プロパティのさらに上の階層の値も比較できます。
この例では、'システム管理者' が $filter
で primarycontactid/createdby/fullname
を使用してレコードを作成した、primarycontactid
を表す連絡先レコードの最初のアカウントを返します。
Request
GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$top=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,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
"value": [
{
"@odata.etag": "W/\"81359849\"",
"name": "Litware, Inc. (sample)",
"_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
"_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"fullname": "Susanna Stubberod (sample)",
"_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
"_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
]
}
関連するコレクションの値でフィルターする
ラムダ演算子、any
& all
を使用してコレクションが含む値を評価し、結果をフィルターします。
Operator | Description |
---|---|
any |
適用した式が、コレクションのいずれかのメンバーに対して true の場合は true を返し、それ以外の場合は false を返します。 引数を指定しないany 演算子は、コレクションが空ではない場合に true を返します。 |
all |
適用した式が、コレクションのメンバー全員に対して true の場合は true を返し、それ以外の場合は false を返します。 |
構文は次のようになります。
<collection>/[any | all](o:<expression to evaluate>)
この場合、o
はコレクションが含む項目を表す変数です。 この規則では型の先頭の文字を使用します。
式で o/<property or collection name>
を使用し、特定の項目のプロパティやコレクションを参照します。
複数のコレクション値ナビゲーション プロパティと、入れ子になったコレクションに、条件を含めることができます。
詳細情報: odata.org のラムダ演算子
ラムダ演算子の例
以下の例では、件名に sometext
を含むメールが 1 件以上存在する、アカウント エンティティ レコードをすべて取得する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
以下の例では、関連するすべてのタスクがクローズされている、すべてのアカウント エンティティ レコードを取得する方法を示しています。
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
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(e:contains(e/subject,'sometext') and
e/statecode eq 0)
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,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
ページの結果
Prefer: odata.maxpagesize
要求ヘッダーを使用して、返されるレコードの件数を制御できます。 返されるレコード件数を指定しない場合、要求ごとに最大 5000 件のレコードを返す可能性があります。 5000 件を超えるページ サイズは要求できません。
注意
Dataverse は $skip
クエリ オプションに対応していないため、$top
と $skip
の組み合わせはページングに使用できません。 詳細情報: $top クエリ オプションを使用する
次の例では、最初 2 件の連絡先レコードのみを返します。
Request
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
回答
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"72201545\"",
"fullname": "Yvonne McKay (sample)",
"contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
},
{
"@odata.etag": "W/\"80648695\"",
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
要求したよりも多くのレコードが存在する場合、@odata.nextLink
注釈は次の例に示すように GET
で使用できる URL を提供し、データの次のページを返します。
Request
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
回答
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"80648710\"",
"fullname": "Nancy Anderson (sample)",
"contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
},
{
"@odata.etag": "W/\"80648724\"",
"fullname": "Maria Campbell (sample)",
"contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
返された結果や @odata.nextLink
URL 値をキャッシュし、それを使用して前のページに戻る必要があります。
@odata.nextLink
URL 値に対して、クエリ オプションを変更または追加しないでください。 さらに多くのページに対する後に続くすべての要求では、元の要求で使用したのと同じ odata.maxpagesize
基本設定値を必ず使用します。 結果が @odata.nextLink
注釈を含まなくなるまで、データのページングを続行できます。
上記の例では、@odata.nextLink
URL 値が含む $skiptoken
パラメーターの値として、エンコードした情報が設定されていることがわかります。 サーバーは、このエンコードした情報を設定し、ページングを制御します。 エンコードした情報の変更や、さらなるエンコードはできません。提供された URL 値を使用し、次のページを取得してください。
$top クエリ オプションを使用する
$top
クエリ オプションを使用して、返される結果の件数を制限できます。 次の例では、最初 3 件のアカウント行のみを返します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3
注意
$top
は Prefer: odata.maxpagesize
要求ヘッダーと一緒に使用できません。 両方とも含めると $top
は無視されます。
データの集計
$apply
オプションを使用して、データの動的な集約とグループ化を行います。
集計機能は 50,000 レコードのコレクションに制限されます。 Dataverse で集計機能を使用する方法については、FetchXML 集計を使用する を参照してください
OData データ集計の追加の詳細はこちらを参照してください: データ集計用 OData 拡張 バージョン 4.0。 Dataverse は、これらの集計方法のサブセットのみに対応しています。
その例を以下に示します。
- クエリ内の一意のステータスのリスト
- 状態の値ごとの件数
- 合計売上を集計する
- 状態に基づく平均売上
- 状態に基づく合計売上
- 取引先責任者名ごとのアカウント合計売上
- 「WA」 の取引先企業の取引先責任者名
- 最後に作成されたレコードの日時
- 最初に作成されたレコードの日時
これらのサンプルは、簡潔にするために完全な要求と応答を示していません。
クエリ内の一意のステータスのリスト
GET accounts?$apply=groupby((statuscode))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Active",
"statuscode": 1
},
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
"statuscode": 2
}
]
}
状態の値ごとの件数
GET accounts?$apply=groupby((statuscode),aggregate($count as count))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Active",
"statuscode": 1,
"count@OData.Community.Display.V1.FormattedValue": "8",
"count": 8
},
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
"statuscode": 2,
"count@OData.Community.Display.V1.FormattedValue": "1",
"count": 1
}
]
}
合計売上を集計する
GET accounts?$apply=aggregate(revenue with sum as total)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"total@OData.Community.Display.V1.FormattedValue": "$440,000.00",
"total": 440000.000000000
}
]
}
状態に基づく平均売上
GET accounts?$apply=groupby((statuscode),aggregate(revenue with average as averagevalue))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Active",
"statuscode": 1,
"averagevalue@OData.Community.Display.V1.FormattedValue": "$53,750.00",
"averagevalue": 53750.000000000
},
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
"statuscode": 2,
"averagevalue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
"averagevalue": 10000.000000000
}
]
}
状態に基づく合計売上
GET accounts?$apply=groupby((statuscode),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Active",
"statuscode": 1,
"total@OData.Community.Display.V1.FormattedValue": "$430,000.00",
"total": 430000.000000000
},
{
"statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
"statuscode": 2,
"total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
"total": 10000.000000000
}
]
}
取引先責任者名ごとのアカウント合計売上
GET accounts?$apply=groupby((primarycontactid/fullname),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
"total": 10000.000000000,
"contact_fullname": "Jim Glynn (sample)"
},
{
"total@OData.Community.Display.V1.FormattedValue": "$80,000.00",
"total": 80000.000000000,
"contact_fullname": "Maria Campbell (sample)"
},
... <truncated for brevity>
]
}
「WA」 の取引先企業の取引先責任者名
GET accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"contact_fullname": "Rene Valdes (sample)"
},
{
"contact_fullname": "Robert Lyon (sample)"
},
{
"contact_fullname": "Scott Konersmann (sample)"
}
]
}
最後に作成されたレコードの日時
GET accounts??$apply=aggregate(createdon with max as lastCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"lastCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
"lastCreate": "2023-03-25T17:42:47Z"
}
]
}
最初に作成されたレコードの日時
GET accounts?$apply=aggregate(createdon with min as firstCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
応答本文
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
"value": [
{
"firstCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
"firstCreate": "2023-03-25T17:42:46Z"
}
]
}
行数をカウントする
$count=true
クエリ オプションを使用して、フィルター条件と一致するエンティティ数を最大 5000 件まで含めます。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=accountid&$count=true
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
回答
HTTP/1.1 200 OK
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid)",
"@odata.count": 9,
"value": [
{
"@odata.etag": "W/\"81359849\"",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd"
},
... <Truncated for brevity>
]
}
応答の @odata.count
注釈は、要求したページ サイズに関係なく、フィルター条件と一致する行数 (最大 5000 件) を含みます。
注意
5000 件を超えるテーブルの合計行数の、過去 24 時間以内のスナップショットを取得する場合は、RetrieveTotalRecordCount 関数 を使用します。
カウント値が 5000 である場合に、カウントがちょうど 5000 であるか、5000 より大きいかを知る必要がある場合は、次のヘッダーを追加できます。
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.totalrecordcount,Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded"
このヘッダーは結果に次の注釈を追加します。
@Microsoft.Dynamics.CRM.totalrecordcount
@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded
$count=true
クエリ オプションと一緒に使用する場合に、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=true
クエリ オプションを含めない場合、@Microsoft.Dynamics.CRM.totalrecordcount
の合計値は -1
になります。
次の例は、$filter
と一致するアカウントが 10 件存在することを示しますが、最初 3 件のアカウントのみが返されます。
Request
GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true
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
を追加してその値を取得します。
Request
GET [Organization URI]/api/data/v9.2/accounts/$count
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
参照
Dataverse 検索を使用してテーブル データ全体を検索する
簡易検索の検索アイテム制限の操作
Web API クエリ データのサンプル (C#)
Web API クエリ データのサンプル (クライアント側の JavaScript)
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
フィードバック
フィードバックの送信と表示