ODataを使用して行をフィルタリングする

[アーティクル]
08/05/2024

リソースのコレクションをフィルタリングするには、 $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 クエリ関数
ラムダ式	関連するコレクションの値に基づいて式を作成します。	関連するコレクションの値でフィルターする

比較演算子

以下の表では、プロパティと値を比較するために使用できる演算子について説明します。

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 を超える特化した機能を使用します。こうした関数は、次のテーブルで説明する特化した機能を提供します。

Group	関数
日付	InFiscalPeriod、InFiscalPeriodAndYear、InFiscalYear、InOrAfterFiscalPeriodAndYear、InOrBeforeFiscalPeriodAndYear、 Last7Days、LastFiscalPeriod、LastFiscalYear、LastMonth、LastWeek、LastXDays、LastXFiscalPeriods、LastXFiscalYears、 LastXHours、LastXMonths、LastXWeeks、LastXYears、LastYear、Next7Days、NextFiscalPeriod、NextFiscalYear、 NextMonth、NextWeek、NextXDays、NextXFiscalPeriods、NextXFiscalYears、NextXHours、NextXMonths、 NextXWeeks、NextXYears、NextYear、OlderThanXDays、OlderThanXHours、OlderThanXMinutes、OlderThanXMonths、 OlderThanXWeeks、OlderThanXYears、On、OnOrAfter、OnOrBefore、ThisFiscalPeriod、ThisFiscalYear、ThisMonth、ThisWeek、ThisYear、Today、Tomorrow、Yesterday
ID 値	EqualBusinessId、EqualUserId、NotEqualBusinessId、NotEqualUserId
階層	Above、AboveOrEqual、EqualUserOrUserHierarchy、EqualUserOrUserHierarchyAndTeams、EqualUserOrUserTeams、 EqualUserTeams、NotUnder、Under、UnderOrEqual 詳細情報: 階層データのクエリ
選択肢の列	ContainValues、DoesNotContainValues 詳細情報: 選択肢からデータを照会する
次の範囲内	Between、NotBetween
後	In、NotIn
言語	EqualUserLanguage

注意

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`

ワイルドカード文字を使用する

文字列を使用してフィルターを構成する場合、次のワイルドカード文字を適用できます。

登場人物	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 などの一重引用符、アポストロフィ、文字を含む値を指定する場合は、値を二重引用符で囲む必要があります。例えば:

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対多のリレーションシップの場合、フィルター処理されたコレクションは、リレーションシップの eq $filter Lookupプロパティを使用した場合と同じ結果を返します。たとえば、次のフィルタリングされたコレクション:

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 を表す最初のアカウントを返します。ここで、「システム管理者」が $filter の primarycontactid/createdby/fullname を使用してレコードを作成しました。

要求:

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 クエリ関数を使用すると、条件の数を減らすことができる場合があります。

次の手順

結果を表示する方法をご覧ください。

ページの結果

注意

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

次の方法で共有

ODataを使用して行をフィルタリングする

比較演算子

列の比較

論理演算子

グループ化演算子

Dataverse クエリ関数

文字列値を使用してフィルターする

URL は特殊文字をエンコードします

ワイルドカード文字を使用する

先頭のワイルドカードはサポートされていません

OData クエリ関数を使用する

一重引用符を管理する

ルックアッププロパティのフィルター

検索列のプロパティ値を使用してフィルターする

ラムダ演算子の例

条件の制限

次の手順

その他のリソース

次の方法で共有

ODataを使用して行をフィルタリングする

比較演算子

列の比較

論理演算子

グループ化演算子

Dataverse クエリ関数

文字列値を使用してフィルターする

URL は特殊文字をエンコードします

ワイルドカード文字を使用する

先頭のワイルドカードはサポートされていません

OData クエリ関数を使用する

一重引用符を管理する

関連するデータ値に基づくフィルター

ルックアッププロパティのフィルター

検索列のプロパティ値を使用してフィルターする

関連するコレクションの値でフィルターする

ラムダ演算子の例

条件の制限

次の手順

その他のリソース