Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
Utilisez l’$filter pour filtrer une collection de ressources.
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. |
Les 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 les 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.
Nonte
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 de service (Microsoft.Dynamics.CRM) au nom de la fonction.
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,startswithetendswith. 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é spécial |
|---|---|
$ |
%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
Caractères génériques de début non pris en charge
Il est important de ne pas utiliser de caractères génériques de premier plan, 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 des exemples de caractères génériques de début :
startswith(name,'%value')
endswith(name,'value%')
En savoir plus sur les erreurs renvoyées lors de l’utilisation de caractères génériques de début
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''.
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 la propriété de recherche
Pour les relations un à plusieurs, une collection filtrée renvoie les mêmes résultats que l’utilisation de eq$filter sur la propriété de recherche pour la relation. Par exemple, cette collection filtrée :
GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name
Est identique à 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 sur la base des valeurs des propriétés de navigation à valeur unique qui représentent des 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 Lambdaany et all pour évaluer les valeurs d’une collection afin de filtrer les résultats.
any: renvoie la valeurtruesi l’expression appliquée est vraie pour n’importe quel membre de la collection, sinon elle renvoie la valeur false.- L’opérateur
anysans argument renvoie la valeurtruesi la collection n’est pas vide.
- L’opérateur
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 ont au moins un courrier électronique 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 pour lesquels 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 ont au moins un courrier électronique 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 identificateurs uniques et des chaînes pouvant aller jusqu’à 850 caractères.
Étapes suivantes
Découvrez comment paginer des résultats.