Options de requête système OData à l’aide du point de terminaison OData
Date de publication : novembre 2016
S’applique à : Dynamics CRM 2015
Vous pouvez affiner les résultats de votre requête en utilisant les options de requête système. Le tableau suivant répertorie les options de chaîne de requête définies dans le protocole OData qui sont implémentées dans le point de terminaison OData pour Mise à jour de Microsoft Dynamics CRM 2015 et de Microsoft Dynamics CRM Online 2015.
Option |
Description |
|---|---|
$expand |
Indique que les enregistrements associés doivent être récupérés dans l’enregistrement ou dans la collection en cours de récupération. |
$filter |
Spécifie qu’une expression ou une fonction doit avoir la valeur true pour qu’un enregistrement soit renvoyé dans la collection. |
$orderby |
Détermine les valeurs qui sont utilisées pour trier un ensemble d’enregistrements. |
$select |
Spécifie un sous-ensemble de propriétés à retourner. |
$skip |
Définit le nombre d’enregistrements à ignorer avant de récupérer les enregistrements dans un ensemble. |
$top |
Détermine le nombre maximal d’enregistrements à retourner. |
$expand
Indique que les enregistrements associés doivent être récupérés dans l’enregistrement ou dans la collection en cours de récupération.
Si vous souhaitez récupérer des enregistrements associés, recherchez le nom de la relation d’entité qui définit cette relation. Vous devrez peut-être afficher les informations de relation d’entité dans l’application pour identifier correctement les relations ou le langage CSDL (Conceptual Schema Definition Language) pour le service de données d’organisation.
Par exemple, pour récupérer les enregistrements d’opportunité relatifs aux comptes, utilisez les relations d’entité opportunity_customer_accounts. La requête /AccountSet?$expand=opportunity_customer_accounts retourne les enregistrements d’opportunité et les enregistrements de compte.
Si vous limitez les colonnes retournées, vous devez également inclure le nom de la propriété de navigation dans la requête. Par exemple, la requête /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts retourne uniquement le nom du compte et les enregistrements d’opportunité développés.
Mise à jour de Microsoft Dynamics CRM 2015 et de Microsoft Dynamics CRM Online 2015 ne prend pas en charge l’interrogation d’une propriété à plusieurs niveaux de relation. Par exemple cette requête, conçue pour récupérer des informations sur l’utilisateur propriétaire des opportunités associées aux comptes, ne fonctionne pas : /AccountSet?$expand=opportunity_customer_accounts/opportunity_owning_user.
Par défaut, vous pouvez définir jusqu’à six relations à développer. Cette requête, qui développe les opportunités et l’utilisateur système qui possède le compte, fonctionne, /AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts.
Notes
Le nombre d’enregistrements associés renvoyé fait l’objet de la même limitation en termes de nombre d’enregistrements retournés. Pour plus d'informations, voir Limitations sur le nombre d’enregistrements retournés. Vous pouvez augmenter le nombre de relations à développer en modifiant la valeur du paramètre ServerSettingsMaxExpandCount.
Pour plus d'informations :OData : option de requête système de filtre ($expand)
$filter
Spécifie qu’une expression ou une fonction doit avoir la valeur true pour qu’un enregistrement soit renvoyé dans la collection.
Si vous récupérez d’autres ensembles de données à l’aide du lien next, vous ne devez pas modifier la valeur d’option de requête $filter, car cela provoquerait des résultats imprévisibles.
La spécification OData pour l'option de requête système de filtre décrit les opérateurs utilisés pour créer une expression à évaluer dans le filtre.Microsoft Dynamics 365 utilise tous les opérateurs logiques et un sous-ensemble des fonctions disponibles, mais ne prend pas en charge l'utilisation des opérateurs arithmétiques. Les filtres peuvent utiliser des conditions regroupées indiquées par des parenthèses. Les comparaisons des valeurs horaires doivent utiliser le format suivant : datetime’<time value>’, par exemple datetime'2010-07-15' ou datetime'2010-07-15T16:19:54Z'.
Le tableau suivant répertorie les opérateurs pris en charge par Microsoft Dynamics 365.
Opérateur |
Description |
Exemple |
|---|---|---|
eq |
Égal à |
/AccountSet?$filter=Address1_City eq 'Redmond' |
ne |
Différent de |
/AccountSet?$filter=Address1_City ne null |
gt |
Supérieur à |
/AccountSet?$filter=CreditLimit/Value gt 1000 |
ge |
Supérieur ou égal à |
/AccountSet?&$filter=CreditLimit/Value ge 1000 |
Lt |
Inférieur à |
/AccountSet?$filter=CreditLimit/Value lt 1000 |
le |
Inférieur ou égal à |
/AccountSet?$filter=CreditLimit/Value le 1000 |
and |
ET logique |
/AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX' |
or |
OU logique |
/AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1 |
not |
Négation logique |
/AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1) |
Vous pouvez utiliser l’option de requête $filter pour filtrer sur la valeur d’un attribut EntityReference. Par exemple, si vous avez la valeur Id pour un enregistrement SystemUser, vous pouvez récupérer une liste de tous les enregistrements de compte auxquels un utilisateur est affecté à l’aide du filtre suivant :
/AccountSet?$filter=OwnerId/Id eq (guid'" + SystemUserId + "')
Le tableau suivant répertorie les fonctions prises en charge par Microsoft Dynamics 365.
Fonction |
Exemple |
|---|---|
startswith |
/AccountSet?$filter=startswith(Name, 'a') |
substringof |
/AccountSet?$filter=substringof('store',Name) |
endswith |
/AccountSet?$filter=endswith(Name, '(sample)') |
Pour plus d'informations :OData : option de requête système de filtre ($filter)
$orderby
Détermine les valeurs qui sont utilisées pour trier un ensemble d’enregistrements. Par défaut, le tri est croissant. Utilisez desc pour inverser l’ordre de tri ou asc pour définir explicitement la valeur par défaut.
Si vous récupérez d’autres ensembles de données à l’aide du lien next, vous ne devez pas modifier la valeur d’option de requête $orderby, car cela provoquerait des résultats imprévisibles.
Notes
Vous pouvez sélectionner jusqu’à 12 colonnes en utilisant $orderby.
Lorsque vous triez par types complexes, EntityReference ou OptionSetValue par exemple, seul le nom de l’attribut doit être spécifié. Par exemple, pour tri par contact principal d’un compte, utilisez la requête $orderby=PrimaryContactId. Si vous spécifiez $orderby=PrimaryContactId/Name, vous obtenez une erreur de demande incorrecte HTTP (Code d’erreur 400 HTTP).
L’exemple suivant répertorie les enregistrements de comptes par pays/région par ordre croissant, puis par ville par ordre décroissant :
/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)
Pour plus d'informations :OData : option de requête système de filtre ($orderby)
$select
Spécifie un sous-ensemble de propriétés à retourner et l’ordre dans lequel les colonnes de données seront organisées. Par défaut, toutes les colonnes qui correspondent à $select=* sont retournées.
Si vous utilisez $expand pour inclure des données associées et si vous utilisez $select pour limiter les colonnes retournées, vous devez également inclure le nom de la propriété de navigation dans la requête. Par exemple, la requête suivante, /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts, retourne uniquement le nom du compte et les enregistrements d’opportunité développés.
Notes
La longueur de chemin maximum est de 2 048 caractères pour les requêtes POST et GET dans Internet Explorer. Vous pouvez facilement atteindre cette limite si vous devez inclure chaque attribut de l’entité de compte dans l’option $select. Pour plus d’informations, voir l’Article 208427 de la Base de connaissances
Pour plus d'informations :OData : option de requête système de filtre ($select)
$skip
Définit le nombre d’enregistrements à ignorer avant de récupérer les enregistrements dans un ensemble.
Si vous récupérez d’autres ensembles de données à l’aide du lien next, vous ne devez pas modifier la valeur d’option de requête $skip, car cela provoquerait des résultats imprévisibles.
Pour plus d'informations :OData : option de requête système de filtre ($skip)
$top
Détermine le nombre maximal d’enregistrements à retourner.
Si vous récupérez d’autres ensembles de données à l’aide du lien next, vous ne devez pas modifier la valeur d’option de requête $top, car cela provoquerait des résultats imprévisibles.
Pour plus d'informations :OData : option de requête système de filtre ($top)
Options de requête système non prises en charge
Mise à jour de Microsoft Dynamics CRM 2015 et de Microsoft Dynamics CRM Online 2015 ne prend pas en charge l’utilisation des options de requête système suivantes :
$inlinecount
$count
$format
Voir aussi
Interrogation des données Microsoft Dynamics CRM 2015 à l'aide du point de terminaison OData
OData : Conventions URI
© 2017 Microsoft. Tous droits réservés. Copyright