OData エンドポイントを使用する OData システム クエリ オプション
公開日: 2016年11月
対象: Dynamics CRM 2015
システム クエリ オプションを使用すると、クエリ結果を調整できます。 次の表は Microsoft Dynamics CRM 2015 および Microsoft Dynamics CRM Online 2015 更新プログラム の OData エンドポイントに実装される OData プロトコルで定義されるクエリ ストリング オプションを一覧しています。
オプション |
説明 |
|---|---|
$expand |
取得するレコードまたはコレクションに関連レコードを含めるよう指示します。 |
$filter |
コレクションに返されるレコードに対して評価が true になる式または関数を指定します。 |
$orderby |
レコードのコレクションを並べ替えるために使用する値を決定します。 |
$select |
返されるプロパティのサブセットを指定します。 |
$skip |
コレクションにレコードを取得する前にスキップするレコード数を設定します。 |
$top |
返されるレコードの最大数を決定します。 |
$expand
取得するレコードまたはコレクションに関連レコードを含めるよう指示します。
関連レコードを取得する場合は、この関連付けを定義するエンティティの関連付け名を探します。 関連付けまたは組織データ サービスの概念スキーマ定義言語 (CSDL) を正しく識別するため、エンティティの関連付け情報をアプリケーションに表示する必要があります。
たとえば、取引先企業に関連する営業案件レコードを取得するには、opportunity_customer_accounts エンティティの関連付けを使用します。 クエリ /AccountSet?$expand=opportunity_customer_accounts は、営業案件レコードと取引先企業レコードを返します。
返す列数を制限する場合は、ナビゲーション プロパティ名もクエリに含める必要があります。 たとえば、クエリ /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts は、取引先企業名と展開された営業案件レコードのみを返します。
Microsoft Dynamics CRM 2015 および Microsoft Dynamics CRM Online 2015 更新プログラム は、複数レベルの関連付けプロパティのクエリをサポートしていません。 たとえば、取引先企業に関連付けられた営業案件の所有ユーザーに関する情報の取得を目的としたクエリ /AccountSet?$expand=opportunity_customer_accounts/opportunity_owning_user は機能しません。
既定では、展開する関連付けを 6 つまで定義できます。 営業案件と、取引先企業を所有するシステム ユーザーの両方を展開するクエリ /AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts は機能します。
注意
返される関連レコード数は、返されるレコード数に対する制限と同じ制限を受けます。 詳細については、「返されるレコード数の制限」を参照してください。ServerSettingsMaxExpandCount の設定値を変更することによって、展開する関連付けの数を増やすことができます。
詳細:「OData: Filter System Query Option ($expand)」を参照してください
$filter
コレクションに返されるレコードに対して評価が true になる式または関数を指定します。
next リンクを使用して追加のデータ セットを取得する場合は、予期せぬ結果が生じるため、$filter クエリ オプションの値を変更しないでください。
フィルター システム クエリ オプションの OData 仕様 では、フィルターで評価する式の作成に使用する演算子について説明しています。Microsoft Dynamics 365 利用可能なすべての論理演算子と関数のサブセットを使用しますが、算術演算子の使用はサポートされていません。 フィルターは、かっこで示される、グループ化された条件を使用できます。 時間値の比較には、datetime’<time value>’ という形式を使用する必要があります。たとえば、datetime'2010-07-15' または datetime'2010-07-15T16:19:54Z' のようになります。
次の表は Microsoft Dynamics 365でサポートされている演算子の一覧を示します。
[演算子] |
説明 |
例 |
|---|---|---|
eq |
等号 |
/AccountSet?$filter=Address1_City eq 'Redmond' |
ne |
不等号 |
/AccountSet?$filter=Address1_City ne null |
gt |
より大きい |
/AccountSet?$filter=CreditLimit/Value gt 1000 |
ge |
以上 |
/AccountSet?&$filter=CreditLimit/Value ge 1000 |
Lt |
より小さい |
/AccountSet?$filter=CreditLimit/Value lt 1000 |
le |
以下 |
/AccountSet?$filter=CreditLimit/Value le 1000 |
and |
論理積 |
/AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX' |
or |
論理和 |
/AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1 |
not |
論理否定 |
/AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1) |
$filter クエリ オプションを使用したフィルタ処理によって、EntityReference 属性の値を取得することもできます。 たとえば、SystemUser レコードの Id 値がある場合は、次のフィルターを使用することで、ユーザーが割り当てられているすべての取引先企業レコードの一覧を取得できます。
/AccountSet?$filter=OwnerId/Id eq (guid'" + SystemUserId + "')
次の表は Microsoft Dynamics 365でサポートされている関数の一覧を示します。
関数 |
例 |
|---|---|
startswith |
/AccountSet?$filter=startswith(Name, 'a') |
substringof |
/AccountSet?$filter=substringof('store',Name) |
endswith |
/AccountSet?$filter=endswith(Name, '(sample)') |
詳細:OData: フィルター システム クエリ オプション ($filter)
$orderby
レコードのコレクションを並べ替えるために使用する値を決定します。 既定では、順序は昇順です。 順序を降順にするには desc を、既定値を明示的に設定するには asc を使用します。
next リンクを使用して追加のデータ セットを取得する場合は、予期せぬ結果が生じるため、$orderby クエリ オプションの値を変更しないでください。
注意
$orderby を使用して、最大 12 の列を選択できます。
EntityReference や OptionSetValue などの複合型によって並べ替えを行う場合は、属性名のみを指定してください。 たとえば、取引先企業の取引先責任者によって並べ替えを行うには、クエリ $orderby=PrimaryContactId を使用します。$orderby=PrimaryContactId/Name を指定すると、「要求が正しくありません」HTTP エラー (HTTP エラー コード 400) が発生します。
次のサンプルでは、取引先企業レコードを国/地域によって昇順に、かつ都市によって降順に表示します。
/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)
詳細:「OData: Filter System Query Option ($orderby)」を参照してください
$select
返されるプロパティのサブセットと、データ列を編成する順序を指定します。 既定では、$select=* に対応するすべての列が返されます。
$expand を使用して関連データを含める場合、および $select を使用して返される列数を制限する場合は、ナビゲーション プロパティ名もクエリに含める必要があります。 たとえば、次のクエリ /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts では、取引先企業名と、展開された営業案件レコードのみが返されます。
注意
Internet Explorer の POST 要求および GET 要求の最大パス長は 2048 文字です。$select オプションに取引先企業エンティティのすべての属性を含めようとすると、この制限にすぐに達する可能性があります。 詳細については、Microsoft KB 208427 を参照してください
詳細:「OData: Filter System Query Option ($select)」を参照してください
$skip
コレクションにレコードを取得する前にスキップするレコード数を設定します。
next リンクを使用して追加のデータ セットを取得する場合は、予期せぬ結果が生じるため、$skip クエリ オプションの値を変更しないでください。
詳細:「OData: Filter System Query Option ($skip)」を参照してください
$top
返される最大レコード数を決定します。
next リンクを使用して追加のデータ セットを取得する場合は、予期せぬ結果が生じるため、$top クエリ オプション値を変更しないでください。
詳細:「OData: Filter System Query Option ($top)」を参照してください
サポートされないシステム クエリ オプション
Microsoft Dynamics CRM 2015 および Microsoft Dynamics CRM Online 2015 更新プログラム は、以下のシステム クエリ オプションの使用をサポートしていません。
$inlinecount
$count
$format
関連項目
OData エンドポイントを使用した Microsoft Dynamics CRM 2015 データをクエリ
OData: URI 規則
© 2017 Microsoft. All rights reserved. 著作権