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

リソースのコレクションをフィルタリングするには、 $filter クエリ オプション を使用します。

Dataverse は、$filter に設定した式によって、コレクションが含む各リソースを評価します。 その式が true と評価したレコードのみを応答で返します。 その式が false や null と評価する場合、またはユーザーがレコードへの読み取りアクセス許可を持っていない場合、レコードは返されません。

以下の表では、$filter 式で使用できる演算子と関数について説明します。

比較演算子

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

列の比較

比較演算子を使用して、同じ行が含むプロパティ値を比較できます。 同じ行内の値を比較するために使用できるのは比較演算子のみであり、列の型が一致する必要があります。 たとえば、次のクエリは、firstname が lastname に等しい連絡先を返します。

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

論理演算子

以下の表では、より複雑な式を作成するために使用できる論理演算子について説明します。

グループ化演算子

複雑な式を評価する優先順位を指定するには、論理演算子とともに括弧 () を使用します。例:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Dataverse クエリ関数

ビジネス アプリケーション向けに設計された、60 を超える特化した機能を使用します。 こうした関数は、次のテーブルで説明する特化した機能を提供します。

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 エンコード値を示しています。

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

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

詳細情報: 文字列値の条件でワイルドカード文字を使用する

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

先頭のワイルドカード カード はサポートされていないため、使用しないことが重要です。 これらのアンチ パターンを使用するクエリでは、クエリを最適化できないため、パフォーマンスの問題が発生します。 先頭のワイルドカードの例をいくつか示します。

startswith(name,'%value')
endswith(name,'value%')

先頭のワイルドカードが使用された場合に返されるエラーの詳細

OData クエリ関数を使用する

次の表では、文字列値のフィルター処理に使用できる OData クエリ関数について説明します。

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

次の手順

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