Filtrer les lignes à l’aide d’OData

Utilisez l’option de requête pour filtrer une collection de ressources. $filter ...

Dataverse évalue chaque ressource de la collection en utilisant l’expression définie pour $filter. Seuls les enregistrements pour lesquels l’expression est évaluée comme étant true sont renvoyés dans la réponse. Les enregistrements ne sont pas retournés si l’expression est évaluée comme false ou null, ou si l’utilisateur n’a pas accès en lecture à l’enregistrement.

Le tableau suivant décrit les opérateurs et les fonctions que vous pouvez utiliser dans les expressions $filter.

Les opérateurs de comparaison

Le tableau suivant décrit les opérateurs que vous pouvez utiliser pour comparer une propriété et une valeur.

Comparaison de colonnes

Vous pouvez utiliser des opérateurs de comparaison pour comparer les valeurs des propriétés d'une même ligne. Seuls les opérateurs de comparaison peuvent être utilisés pour comparer des valeurs dans la même ligne, et les types de colonne doivent correspondre. Par exemple, la requête suivante renvoie tous les contacts où firstname est égal à lastname :

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

Opérateurs logiques

La table suivante décrit les opérateurs logiques que vous pouvez utiliser pour créer des expressions plus complexes.

Opérateurs de groupement

Utilisez des parenthèses () avec des opérateurs logiques pour spécifier la priorité pour évaluer une expression complexe ; par exemple :

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

Fonctions de requête Dataverse

Utilisez plus de 60 fonctions spécialisées conçues pour les applications professionnelles. Ces fonctions offrent des possibilités spéciales décrites dans la table suivante.

Le Web API Query Function Reference a la liste complète. Chaque article fournit un exemple de syntaxe que vous pouvez copier.

Vous devez utiliser le nom complet de la fonction et ajouter l’espace de noms du service () au nom de la fonction. ... Microsoft.Dynamics.CRM

Chaque fonction a un paramètre PropertyName qui spécifie la propriété à évaluer. La fonction peut avoir d’autres paramètres tels que PropertyValue, PropertyValues ou PropertyValue1 et PropertyValue2. Lorsque ces paramètres existent, vous devez fournir une ou plusieurs valeurs à comparer au paramètre PropertyName.

L’exemple suivant présente l’utilisation de la fonction Entre pour rechercher des comptes avec un nombre d’employés allant de 5 à 2 000.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])  

Filtrer en utilisant des valeurs de chaîne

Gardez les points suivants à l’esprit lorsque vous filtrez sur des valeurs de chaîne :

• Tous les filtres utilisant des chaînes de caractères sont insensibles à la casse.
• Vous devez coder l’URL des caractères spéciaux dans les critères de filtre. Plus d’informations : Encoder l’URL des caractères spéciaux
• Vous pouvez utiliser des caractères génériques, mais évitez de les utiliser de manière incorrecte. Plus d’informations : Utiliser des caractères génériques
• Vous pouvez utiliser les fonctions de requête OData : contains, startswith et endswith. Plus d’informations : Utiliser les fonctions de requête OData
• Vous devez gérer les guillemets simples lorsque vous utilisez des filtres qui acceptent un tableau de valeurs de chaîne. Pour plus d’informations : Gérer les guillemets simples

Encoder l’URL des caractères spéciaux

Si la chaîne que vous utilisez comme valeur dans une fonction de filtrage comprend un caractère spécial, vous devez l’encoder dans l’URL. Par exemple, si vous utilisez cette fonction : contains(name,'+123'), cela ne fonctionnera pas car + est un caractère qui ne peut pas être inclus dans une URL. Si vous encodez l’URL de la chaîne, elle deviendra contains(name,'%2B123') et vous obtiendrez des résultats où la valeur de la colonne contient +123.

Le tableau suivant montre les valeurs encodées d’URL pour les caractères spéciaux courants.

Utiliser les caractères génériques

Lorsque vous composez des filtres à l’aide de chaînes, vous pouvez utiliser les caractères génériques suivants :

Plus d’informations : Utilisez des caractères génériques dans les conditions pour les valeurs de chaîne

Les caractères génériques de début ne sont pas pris en charge

Il est important de ne pas utiliser le caractère générique Cartes car ils ne sont pas pris en charge. Les requêtes utilisant ces anti-modèles introduisent des problèmes de performances car les requêtes ne peuvent pas être optimisées. Voici quelques exemples de caractères génériques de premier plan :

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

En savoir plus sur les erreurs renvoyées lorsque des caractères génériques de début sont utilisés

Utiliser les fonctions de requête OData

La table suivante décrit les fonctions de requête OData que vous pouvez utiliser pour filtrer les valeurs de chaîne :

Vous pouvez utiliser ces fonctions avec l’opérateur logique not pour annuler le résultat.

Gérer les guillemets simples

Certains filtres acceptent un tableau de valeurs de chaîne, comme la fonction In Query. Lorsque vous spécifiez des valeurs à comparer dans des filtres qui acceptent un tableau de valeurs de chaîne, qui contiennent des guillemets simples (apostrophe), tels que O'Brian ou alors Men's clothes, vous devez utiliser des guillemets doubles autour des valeurs.

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

Si vous ne le faites pas, vous verrez l’erreur suivante :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.

Si le filtre est pour une valeur unique, remplacez le guillemet simple par deux guillemets simples consécutifs, par exemple :

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

Si vous ne le faites pas, vous verrez l’erreur suivante :There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Filtrer sur la base de valeurs de données connexes

Vous pouvez filtrer les lignes renvoyées en fonction des valeurs des tables connexes. La manière dont vous filtrez dépend du type de relation.

Filtrer sur la propriété recherchée

Pour une relation un-à-plusieurs Relations, une collection filtrée renvoie les mêmes résultats que l’utilisation d’un eq $filter sur la propriété Lookup pour la relation. Par exemple, cette collection filtrée :

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

C’est le même que ce filtre sur une propriété de recherche.

GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name

Filtrer à l’aide des valeurs des propriétés des colonnes de recherche

Vous pouvez filtrer en fonction des valeurs des propriétés de navigation à valeur unique qui représentent les colonnes de recherche. Utilisez ce modèle :

<single-valued navigation property>/<property name>

L’exemple suivant renvoie les enregistrements de compte en fonction de la valeur de la colonne primarycontactid/fullname :

Demande :

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"

Réponse :

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

Vous pouvez également comparer des valeurs plus haut dans la hiérarchie des propriétés de navigation à valeur unique.

L’exemple suivant renvoie le premier compte où l’enregistrement de contact représente le primarycontactid, où l’« administrateur système » a créé l’enregistrement, en utilisant primarycontactid/createdby/fullname dans le $filter.

Demande :

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"

Réponse :

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

Filtrer en utilisant les valeurs des collections apparentées

Utilisez les opérateurs Lambda any et all pour évaluer les valeurs d’une collection afin de filtrer les résultats.

• any : renvoie la valeur true si l’expression appliquée est vraie pour n’importe quel membre de la collection, sinon elle renvoie la valeur false.

  • L’opérateur any sans argument renvoie la valeur true si la collection n’est pas vide.

• all : renvoie la valeur true si l’expression appliquée est vraie pour tous les membres de la collection, sinon elle renvoie la valeur false.

La syntaxe se présente comme suit :

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

Dans ce cas, o est la variable qui représente les éléments de la collection. La convention consiste à utiliser la première lettre du type. Dans l’expression, utilisez o/<property or collection name> pour faire référence à une propriété ou à une collection d’un élément donné.

Vous pouvez inclure des conditions sur plusieurs propriétés de navigation à valeur de collection et sur des collections imbriquées. Vous ne pouvez pas inclure de conditions sur les propriétés de navigation à valeur de collection qui sont imbriquées dans une propriété de navigation de recherche. Par exemple, $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') n’est pas pris en charge.

Pour plus d’informations : Opérateurs Lambda sur odata.org

Exemples d’opérateurs Lambda

L’exemple suivant récupère tous les enregistrements de compte qui contiennent au moins un e-mail avec "sometext" dans l’objet : ...

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

L’exemple suivant récupère tous les enregistrements de compte dont toutes les tâches associées sont fermées : ...

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

L’exemple suivant récupère tous les enregistrements de compte qui contiennent au moins un e-mail avec "sometext" dans l’objet et dont le code d’état est actif : ...

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

L’exemple suivant crée une requête imbriquée à l’aide des opérateurs any et 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

Limites de condition

Vous ne pouvez pas inclure plus de 500 conditions au total dans une requête. Sinon, vous voyez cette erreur :

Nom: TooManyConditionsInQuery
Code : 0x8004430C
Nombre : -2147204340
Message : Number of conditions in query exceeded maximum limit.

Vous devez réduire le nombre de conditions pour exécuter la requête. Vous pourrez peut-être réduire le nombre de conditions en utilisant les fonctions de requête In ou NotIn qui peuvent être utilisées avec des nombres, des identifiants uniques et des chaînes jusqu’à 850 caractères.

Étapes suivantes

Découvrez comment paginer des résultats.