Filtrer les lignes à l’aide d’OData

Article
08/05/2024

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.

	Description	Plus d’informations
Les opérateurs de comparaison	Utilisez les opérateurs `eq`,`ne`,`gt`,`ge`,`lt` et `le` pour comparer une propriété et une valeur.	Opérateurs de comparaison
Opérateurs logiques	Utilisez `and`, `or` et `not` pour créer des expressions plus complexes.	Opérateurs logiques
Opérateurs de groupement	Utilisez des parenthèses : `()`, pour spécifier la priorité pour évaluer une expression complexe.	Opérateurs de groupement
Fonctions de requête OData	Évaluez les valeurs des chaînes de caractères à l’aide des fonctions `contains`, `endswith` et `startswith`.	Utiliser les fonctions de requête OData
Fonctions de requête Dataverse	Utilisez plus de 60 fonctions spécialisées conçues pour les applications professionnelles.	Fonctions de requête Dataverse
Expressions Lambda	Créez des expressions basées sur les valeurs de collections apparentées.	Filtrer en utilisant les valeurs des collections apparentées

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.

Opérateur	Description	Exemple
`eq`	Égal à	`$filter=revenue eq 100000`
`ne`	Différent de	`$filter=revenue ne 100000`
`gt`	Supérieur(e) à	`$filter=revenue gt 100000`
`ge`	Supérieur ou égal à	`$filter=revenue ge 100000`
`lt`	Inférieur(e) à	`$filter=revenue lt 100000`
`le`	Inférieur ou égal à	`$filter=revenue le 100000`

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érateur	Description	Exemple
`and`	ET logique	`$filter=revenue lt 100000 and revenue gt 2000`
`or`	OU logique	`$filter=contains(name,'(sample)') or contains(name,'test')`
`not`	Négation logique	`$filter=not contains(name,'sample')`

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.

Grouper	Fonctions
Dates	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
Valeurs d’ID	EqualBusinessId, EqualUserId, NotEqualBusinessId, NotEqualUserId
Hiérarchie	Above, AboveOrEqual, EqualUserOrUserHierarchy, EqualUserOrUserHierarchyAndTeams, EqualUserOrUserTeams, EqualUserTeams, NotUnder, Under, UnderOrEqual Plus d’informations : Interroger les données hiérarchiques
Colonnes de choix	ContainValues, DoesNotContainValues Plus d’informations : Interroger les données à partir des choix
Entre	Between, NotBetween
Dans	In, NotIn
Langage	EqualUserLanguage

Notes

La fonction Contient peut être utilisée avec des colonnes indexées en texte intégral. Seule la table Dynamics 365 KBArticle (article) possède des colonnes indexées en texte intégral. Utilisez la fonction OData contains à la place.

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.

Caractère spécial	Caractère codé dans l’URL
`$`	`%24`
`&`	`%26`
`+`	`%2B`
`,`	`%2C`
`/`	`%2F`
`:`	`%3A`
`;`	`%3B`
`=`	`%3D`
`?`	`%3F`
`@`	`%40`

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 :

Caractères	Description	Documentation T-SQL et exemples
`%`	Correspond à n’importe quelle chaîne de zéro ou plusieurs caractères. Ce caractère générique peut être utilisé comme préfixe ou comme suffixe.	Caractère de pourcentage (caractère générique – Caractère(s) à faire correspondre) (Transact-SQL)
`_`	Utilisez le caractère de soulignement pour faire correspondre n’importe quel caractère unique dans une opération de comparaison de chaînes qui implique une correspondance de modèle.	_ (Caractère générique – Correspond à un caractère) (Transact-SQL)
`[]`	Correspond à n’importe quel caractère unique dans la plage ou l’ensemble spécifié qui est spécifié entre crochets.	[ ] (Caractère générique – Caractère(s) à faire correspondre) (Transact-SQL)
`[^]`	Correspond à n’importe quel caractère unique hors de la plage ou l’ensemble spécifié qui est spécifié entre crochets.	[^] (Caractère générique – Caractère(s) à ne pas faire correspondre) (Transact-SQL)

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 :

Function	Exemple
`contains`	`$filter=contains(name,'(sample)')`
`endswith`	`$filter=endswith(name,'Inc.')`
`startswith`	`$filter=startswith(name,'a')`

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''.

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

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.

Résultats sur la page

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Partager via

Filtrer les lignes à l’aide d’OData

Les opérateurs de comparaison

Comparaison de colonnes

Opérateurs logiques

Opérateurs de groupement

Fonctions de requête Dataverse

Filtrer en utilisant des valeurs de chaîne

Encoder l’URL des caractères spéciaux

Utiliser les caractères génériques

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

Utiliser les fonctions de requête OData

Gérer les guillemets simples

Filtrer sur la propriété recherchée

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

Exemples d’opérateurs Lambda

Limites de condition

Étapes suivantes

Ressources supplémentaires

Partager via

Filtrer les lignes à l’aide d’OData

Les opérateurs de comparaison

Comparaison de colonnes

Opérateurs logiques

Opérateurs de groupement

Fonctions de requête Dataverse

Filtrer en utilisant des valeurs de chaîne

Encoder l’URL des caractères spéciaux

Utiliser les caractères génériques

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

Utiliser les fonctions de requête OData

Gérer les guillemets simples

Filtrer sur la base de valeurs de données connexes

Filtrer sur la propriété recherchée

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

Filtrer en utilisant les valeurs des collections apparentées

Exemples d’opérateurs Lambda

Limites de condition

Étapes suivantes

Ressources supplémentaires