$filter
OData クエリ オプションを使用して、リソースのコレクションをフィルター処理します。
Dataverse は、 $filterの式セットを使用して、コレクション内の各リソースを評価します。 応答には、式が trueに評価されるレコードのみが含まれます。 式が false または nullに評価された場合、またはユーザーがレコードへの読み取りアクセス権を持っていない場合、レコードは含まれません。
以下の表では、$filter 式で使用できる演算子と関数について説明します。
| 説明 | 詳細情報 | |
|---|---|---|
| 比較演算子 | プロパティと値を比較する際は演算子 eq、ne、gt、ge、lt、le を使用します。 |
比較演算子 |
| 論理演算子 |
and、or、not を使用して、より複雑な式を作成します。 |
論理演算子 |
| グループ演算子 | 括弧 () を使用して、複雑な式を評価する優先順位を指定します。 |
グループ演算子 |
| OData クエリ関数 |
contains、endswith、およびstartswith関数を使用して文字列値を評価します。 |
OData クエリ関数を使用する |
| Dataverse クエリ関数 | ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 | Dataverse クエリ関数 |
| ラムダ式 | 関連するコレクションの値に基づいて式を作成します。 | 関連するコレクションの値でフィルターする |
比較演算子
以下の表では、プロパティと値を比較するために使用できる演算子について説明します。
| オペレーター | 説明 | 例 |
|---|---|---|
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
論理演算子
以下の表では、より複雑な式を作成するために使用できる論理演算子について説明します。
| オペレーター | 説明 | 例 |
|---|---|---|
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 ~ 2,000 人のアカウントを検索する方法を示します。
GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])
文字列値を使用してフィルター処理する
文字列値を使用してフィルター処理する場合は、次の点に注意してください。
- 文字列値を使用するすべてのフィルターでは、大文字と小文字が区別されません。
- フィルター条件では特殊文字を URL エンコードする必要があります。 詳細については、「 URL エンコードの特殊文字」を参照してください。
- ワイルドカード文字は使用できますが、正しく使用しないでください。 詳細については、「 ワイルドカード文字を使用する」を参照してください。
- OData クエリ関数:
contains、startswith、およびendswithを使用できます。 詳細については、「 OData クエリ関数を使用する」を参照してください。 - 文字列値の配列を受け入れるフィルターを使用する場合は、一重引用符を管理する必要があります。 詳細については、 単一引用符の管理を参照してください。
URL は特殊文字をエンコードします
フィルター関数の値として使用する文字列に特殊文字が含まれている場合は、URL エンコードする必要があります。 たとえば、 contains(name,'+123')関数を使用する場合、 + は URL に含めることができない文字であるため、機能しません。 文字列を URL エンコードすると、文字列が contains(name,'%2B123') になり、列の値に +123が含まれる結果が得られます。
次の表は、一般的な特殊文字の URL エンコード値を示しています。
| スペシャル 文字 |
エンコードされた URL 文字 |
|---|---|
$ |
%24 |
& |
%26 |
+ |
%2B |
, |
%2C |
/ |
%2F |
: |
%3A |
; |
%3B |
= |
%3D |
? |
%3F |
@ |
%40 |
ワイルドカード文字を使用する
文字列を使用してフィルターを作成する場合は、次のワイルドカード文字を使用できます。
| 文字 | 説明 | T-SQL のドキュメントと例 |
|---|---|---|
% |
0 文字以上の任意の文字列に一致します。 このワイルドカード文字は、プレフィックスまたはサフィックスとして使用します。 | パーセント記号 (ワイルドカード - 一致する文字) (Transact-SQL) |
_ |
アンダースコア文字を使用して、パターン マッチングを含む文字列比較操作で任意の 1 文字を照合します。 | _ (ワイルドカード - 1 つの文字に一致) (Transact-SQL) |
[] |
角括弧に指定した範囲またはセット内の任意の 1 文字に一致します。 | [ ] (ワイルドカード - 一致する文字) (Transact-SQL) |
[^] |
角かっこの間に指定した範囲内またはセット内にない任意の 1 文字と一致します。 | [^] (ワイルドカード - 一致しない文字) (Transact-SQL) |
詳細については、「 文字列値の条件でワイルドカード文字を使用する」を参照してください。
先頭のワイルドカードはサポートされていません
先頭のワイルドカードはサポートされていないため、使用しないでください。 これらのアンチ パターンを使用するクエリでは、クエリを最適化できないため、パフォーマンスの問題が発生します。 先頭のワイルドカードの例:
startswith(name,'%value')
endswith(name,'value%')
詳細は、先頭のワイルドカードを使用した場合に返されるエラーについての記事をご覧ください
OData クエリ関数を使用する
次の表では、文字列値のフィルター処理に使用できる OData クエリ関数について説明します。
| 関数 | 例 |
|---|---|
contains |
$filter=contains(name,'(sample)') |
endswith |
$filter=endswith(name,'Inc.') |
startswith |
$filter=startswith(name,'a') |
結果を否定するには、論理演算子 not と共にこれらの関数を使用します。
一重引用符を管理する
一部のフィルタは、クエリ関数 など、文字列値の配列を受け入れます。
O'BrianやMen's clothesなどの単一引用符またはアポストロフィ文字を含む値をこれらのフィルターで指定する場合は、値の周りに二重引用符を使用します。次に例を示します。
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''.
関連するデータ値に基づくフィルター
関連テーブルの値に基づいて、返された行をフィルターできます。 フィルターする方法は、リレーションシップのタイプによって異なります。
ルックアップ プロパティのフィルター
1 対多のリレーションシップの場合、フィルターされたコレクションは、リレーションシップの Lookup プロパティで eq$filter を使用するのと同じ結果を返します。 たとえば、次のフィルター処理されたコレクションがあるとします。
GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name
ルックアップ プロパティのこの フィルター と同じです。
GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name
検索列のプロパティ値を使用してフィルターする
検索列を表す単一値ナビゲーション プロパティの値に基づいてフィルターできます。 このパターンを使用します:
<single-valued navigation property>/<property name>
次の例は、primarycontactid/fullname 列の値に基づいてアカウント レコードを返します。
要求:
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"
}
]
}
単一値のナビゲーション プロパティの階層をさらに上位にある値を比較することもできます。
たとえば、以下の例は、取引先担当者レコードが primarycontactid を表し、システム管理者がレコードを作成した最初の取引先企業を、primarycontactid/createdby/fullname を $filter で使用した最初の取引先企業を返します。
要求:
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 を使用してコレクション内の値を評価し、結果をフィルターします。
any: 適用した式が、コレクションのいずれかのメンバーに対して true の場合はtrueを返し、それ以外の場合は false を返します。- 引数を指定しない
any演算子は、コレクションが空ではない場合にtrueを返します。
- 引数を指定しない
all: 適用した式が、コレクションのメンバー全員に対して true の場合は true を返し、それ以外の場合は false を返します。
構文は次のようになります。
<collection>/[any | all](o:<expression to evaluate>)
この場合、o はコレクションが含む項目を表す変数です。 この規則では型の先頭の文字を使用します。
式内で、o/<property or collection name> を使用して、特定の項目のプロパティまたはコレクションを参照します。
複数のコレクション値ナビゲーション プロパティと、入れ子になったコレクションに、条件を含めることができます。 ルックアップ ナビゲーション プロパティにネストされているコレクション値のナビゲーション プロパティに条件を含めることはできません。 例えば、$filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') はサポートされていません。
詳細情報: 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 」を含むメールが 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
条件の制限
クエリには、最大 500 個の合計条件を含めることができます。 それ以外の場合は、次のエラー メッセージが表示されます。
名前:
TooManyConditionsInQuery
コード:0x8004430C
番号:-2147204340
メッセージ:Number of conditions in query exceeded maximum limit.
クエリを実行するための条件数を減らす必要があります。 最大 850 文字の数値、一意識別子、文字列で使用できる In または NotIn クエリ関数を使用すると、条件の数を減らすことができる場合があります。
次の手順
結果を表示する方法をご覧ください。