OData を使用して行をフィルター処理する

OData クエリ オプションを使用して、リソースのコレクションをフィルター処理します。

Dataverse は、 の式セットを使用して、コレクション内の各リソースを評価します。 応答には、式が に評価されるレコードのみが含まれます。 式が または に評価された場合、またはユーザーがレコードへの読み取りアクセス権を持っていない場合、レコードは含まれません。

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

比較演算子

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

列の比較

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

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

には完全なリストがあります。 各記事に記載された構文の例をコピーできます。

関数の完全に修飾された名前を使用し、Service 名前空間 (Microsoft.Dynamics.CRM) を関数の名前に追加する必要があります。

各関数には、評価するプロパティを指定する パラメーターがあります。 この関数には、 、 、 、 など、より多くのパラメーターが含まれる場合があります。 これらのパラメーターが存在する場合は、 パラメーターと比較する値を指定します。

次の例では、 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 クエリ関数: 、、および を使用できます。 詳細については、「 OData クエリ関数を使用する」を参照してください。
• 文字列値の配列を受け入れるフィルターを使用する場合は、一重引用符を管理する必要があります。 詳細については、 単一引用符の管理を参照してください。

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

フィルター関数の値として使用する文字列に特殊文字が含まれている場合は、URL エンコードする必要があります。 たとえば、 関数を使用する場合、 は URL に含めることができない文字であるため、機能しません。 文字列を URL エンコードすると、文字列が になり、列の値に が含まれる結果が得られます。

次の表は、一般的な特殊文字の URL エンコード値を示しています。

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

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

詳細については、「 文字列値の条件でワイルドカード文字を使用する」を参照してください。

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

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

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

詳細は、先頭のワイルドカードを使用した場合に返されるエラーについての記事をご覧ください

OData クエリ関数を使用する

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

結果を否定するには、論理演算子 と共にこれらの関数を使用します。

一重引用符を管理する

一部のフィルタは、クエリ関数 など、文字列値の配列を受け入れます。 やなどの単一引用符またはアポストロフィ文字を含む値をこれらのフィルターで指定する場合は、値の周りに二重引用符を使用します。次に例を示します。

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"]

そうしないと、次のエラーを取得します。

フィルターを単一の値に使用する場合は、一重引用符を連続する 2 つの一重引用符文字に置き換えます。例えば:

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

そうしないと、次のようなエラーを取得します。

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

関連テーブルの値に基づいて、返された行をフィルターできます。 フィルターする方法は、リレーションシップのタイプによって異なります。

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

1 対多のリレーションシップの場合、フィルターされたコレクションは、リレーションシップの 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>

次の例は、 列の値に基づいてアカウント レコードを返します。

要求:

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"
        }
    ]
}

単一値のナビゲーション プロパティの階層をさらに上位にある値を比較することもできます。

たとえば、以下の例は、取引先担当者レコードが を表し、システム管理者がレコードを作成した最初の取引先企業を、 を で使用した最初の取引先企業を返します。

要求:

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"
                }
            }
        }
    ]
}

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

ラムダ演算子 および を使用してコレクション内の値を評価し、結果をフィルターします。

• : 適用した式が、コレクションのいずれかのメンバーに対して true の場合は を返し、それ以外の場合は false を返します。

  • 引数を指定しない 演算子は、コレクションが空ではない場合に を返します。

• : 適用した式が、コレクションのメンバー全員に対して true の場合は true を返し、それ以外の場合は false を返します。

構文は次のようになります。

<collection>/[any | all](o:<expression to evaluate>)

この場合、 はコレクションが含む項目を表す変数です。 この規則では型の先頭の文字を使用します。 式内で、 を使用して、特定の項目のプロパティまたはコレクションを参照します。

複数のコレクション値ナビゲーション プロパティと、入れ子になったコレクションに、条件を含めることができます。 ルックアップ ナビゲーション プロパティにネストされているコレクション値のナビゲーション プロパティに条件を含めることはできません。 例えば、 はサポートされていません。

詳細情報: 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

次の例では 演算子と 演算子を使用して入れ子のクエリを作成します。

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 個の合計条件を含めることができます。 それ以外の場合は、次のエラー メッセージが表示されます。

名前:
コード:
番号:
メッセージ:

クエリを実行するための条件数を減らす必要があります。 最大 850 文字の数値、一意識別子、文字列で使用できる In または NotIn クエリ関数を使用すると、条件の数を減らすことができる場合があります。

次の手順

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