Partager via

Interroger les données à l’aide de l’API web

  • Article

Lorsque vous utilisez l’API web pour créer une requête sur une table Dataverse, vous devez prendre les décisions suivantes :

Décision Description
Sélectionner des colonnes Colonnes de données à renvoyer
Tables de jointure Tables connexes à inclure dans les résultats
Lignes de commande Ordre de renvoi des résultats
Lignes de filtre Lignes de données à renvoyer
Résultats sur la page Nombre de lignes de données à renvoyer
Données agrégées Comment regrouper et agréger les données renvoyées
Compter le nombre de lignes Comment compter le nombre de lignes

Cet article traite de l’interrogation des données contenues dans les tables. Vous pouvez également utiliser l’API web pour interroger des données sur les définitions de tableau ou les métadonnées d’entité. La structure des données étant différente, de nombreuses possibilités décrites ici ne s’appliquent pas. Pour plus d’informations : Requête des définitions de table à l’aide de l’API Web et echercher les définitions de schéma

Collections d’entités

Chaque requête commence par une collection d’entités. Les collections d’entités peuvent être :

Ressources EntitySet

Pour trouver toutes les ressources EntitySet disponibles dans votre environnement, envoyez une requête GET à l’API web document de service :

Demande :

GET [Organization URI]/api/data/v9.2/
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Conseil

Ces valeurs sont généralement le nom pluriel de la table, mais elles peuvent être différentes. Utilisez cette requête pour confirmer que vous utilisez le nom de ressource EntitySet correct.

Pour récupérer les données du type d’entité de compte, vous commencez par la ressource EntitySet accounts.

GET [Organization URI]/api/data/v9.2/accounts?$select=name

Collections filtrées

Vous pouvez interroger n’importe quelle collection d’entités représentée par une propriété de navigation avec une valeur de collection d’un enregistrement donné.

Si vous voulez récupérer des données à partir du type d’entité de compte, où un utilisateur spécifique est OwningUser, vous pouvez utiliser la propriété de navigation à valeur de collection user_accounts à partir de l’enregistrement spécifié systemuser.

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

Pour trouver le nom de la propriété de navigation avec une valeur de collection :

Options de requête OData

La table suivante décrit les options de requête OData prises en charge par l’API web Dataverse.

Option Utilisation Plus d’informations
$select Demandez un ensemble spécifique de propriétés pour chaque entité ou type de complexe. Sélectionner des colonnes
$expand Spécifiez les ressources connexes à inclure dans la liste des ressources extraites. Tables de jointure
$filter Filtrez une collection de ressources. Lignes de filtre
$orderby Demandez des ressources dans un ordre particulier. Lignes de commande
$apply Agrégez et regroupez vos données. Données agrégées
$top Spécifiez le nombre d’éléments de la collection interrogée à inclure dans le résultat. Ne pas utiliser $top lorsque vous récupérez des pages de données. Utiliser l’option de requête $top
$count Demandez un décompte des ressources correspondantes incluses dans les ressources de la réponse. Compter le nombre de lignes

Vous pouvez appliquer plusieurs options à une requête. Séparez les options de requête du chemin de ressource par un point d’interrogation (?). Séparez chaque option après la première par une esperluette (&). Les noms des options respectent la casse.

L’API web Dataverse ne prend pas en charge ces options de requête OData : $skip,$search,$format.

Utiliser des alias de paramètre avec des options de requête

Vous pouvez utiliser des alias de paramètres pour les options de requête $filter et $orderby, mais pas à l’intérieur de l’option $expand. Les alias de paramètre permettent que la même valeur soit utilisée plusieurs fois dans une requête. Si l’alias ne dispose pas d’une valeur, le système suppose qu’il est nul.

Sans alias de paramètre :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Avec alias de paramètre :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Vous pouvez également utiliser des alias de paramètre lorsque vous utilisez des fonctionnalités. Pour plus d’informations, consultez Utiliser les fonctions de l’API Web

Sélectionner des colonnes

Important

Lorsque vous interrogez des données, il est important de limiter la quantité de données renvoyées pour optimiser les performances. Sélectionnez uniquement les colonnes contenant les données dont vous avez besoin.

Utilisez l’option de requête $select pour choisir les colonnes à retourner avec votre requête. Dans OData, chaque colonne est représentée par une propriété. Si vous n’incluez pas d’option de requête $select, toutes les propriétés sont renvoyées.

L’exemple suivant demande les propriétés name et revenue d’une ligne de la ressource EntitySet accounts :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

La clé primaire est toujours renvoyée, vous n’avez donc pas besoin de l’inclure dans votre $select. Dans cet exemple, accountid est la clé primaire.

D’autres valeurs de propriété peuvent également être incluses. Dans ce cas, la _transactioncurrencyid_value propriété de recherche pour la table/entité de référence Référence de table/entité de devise (TransactionCurrency) est incluse parce que revenue est une propriété de devise.

Quelles sont les propriétés disponibles ?

Toutes les propriétés disponibles pour une entité se trouvent dans le document de service $metadata. Informations complémentaires : Propriétés de l’API web

Les types d’entités inclus avec Dataverse sont décrites dans le Web API Entity Type Reference.

Conseil

La façon la plus simple de découvrir rapidement les propriétés disponibles est d’envoyer une requête en utilisant l’option $top avec une valeur de 1 sans utiliser $select.

Valeurs mises en forme

Les valeurs mises en forme sont des chaînes de caractères générées sur le serveur que vous pouvez utiliser dans votre application. Les valeurs mises en forme sont les suivantes :

  • Les étiquettes localisées pour les colonnes choix, choix, oui/non, état et raison du statut
  • Valeur du nom primaire pour les propriétés recherche et propriétaire
  • Valeurs monétaires avec symboles monétaires
  • Date mise en forme dans le fuseau horaire de l’utilisateur

Pour inclure des valeurs mises en forme dans vos résultats, utilisez cet en-tête de requête :

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Les valeurs mises en forme sont l’une des nombreuses annotations que vous pouvez demander. Utilisez Prefer: odata.include-annotations="*" pour inclure toutes les annotations. Pour pus d’informations, voir : Demander des annotations

La valeur mise en forme est renvoyée avec l’enregistrement avec une annotation qui suit cette convention :

<property name>@OData.Community.Display.V1.FormattedValue

Par exemple :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

La table suivante décrit les valeurs et les valeurs formatées qui sont renvoyées pour les propriétés demandées.

Propriété active Valeur mise en forme
name Litware, Inc. (sample) None
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd None

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,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Recherche de données sur les propriétés

Lorsqu’une propriété de recherche représente une relation multitable ou polymorphe, vous devez demander des annotations spécifiques pour déterminer quelle table contient les données associées.

Par exemple, de nombreuses tables contiennent des enregistrements dont les utilisateurs ou les équipes peuvent être propriétaires. Les données de propriété sont stockées dans une colonne de recherche nommée ownerid. Cette colonne est une propriété de navigation à valeur unique dans OData. Vous pouvez utiliser $expand pour créer une jointure afin d’obtenir cette valeur, mais vous ne pouvez pas utiliser $select. Cependant, vous pouvez utiliser la propriété de recherche _ownerid_value correspondante avec $select.

Lorsque vous incluez la propriété de recherche _ownerid_value avec votre $select, elle renvoie une valeur GUID. Cette valeur ne vous indique pas si le propriétaire de l’enregistrement est un utilisateur ou une équipe. Vous devez demander des annotations pour obtenir ces données.

Pour inclure ces annotations dans vos résultats, utilisez cet en-tête de requête :

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Conseil

Ou vous pouvez utiliser Prefer: odata.include-annotations="*" pour inclure toutes les annotations. Pour pus d’informations, voir : Demander des annotations

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

La réponse suivante renvoie deux enregistrements de compte différents. Une team possède le premier, et un systemuser possède le second. L’annotation _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname fournit ces informations.

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname est le nom logique de la table liée.
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty est le nom de la propriété de navigation correspondante à valeur unique. Vous pouvez utiliser $expand avec cette valeur dans une autre requête pour obtenir plus de données de l’enregistrement lié.

Tables de jointure

Pour contrôler quelles données sont renvoyées depuis les enregistrements de la table associée, utilisez l’option de requête $expand avec les propriétés de navigation.

  • Vous pouvez inclure jusqu’à 15 $expand options dans une requête. Chaque option $expand crée une jointure qui peut affecter les performances.
  • Les requêtes qui développent les propriétés de navigation à valeur de collection peuvent renvoyer des données mises en cache pour les propriétés qui ne reflètent pas des modifications récentes. Il est préférable d’utiliser l’en-tête If-None-Match avec la valeur null pour remplacer la mise en cache du navigateur. Pour plus d’informations, consultez En-têtes HTTP.

La table suivante décrit les options de requête que vous pouvez postuler dans certaines options $expand :

Option Description
$select Sélectionnez les propriétés à retourner. Pour plus d’informations, consultez Sélectionner les colonnes
$filter Pour les propriétés de navigation à valeur de collection, limitez les enregistrements retournés. Pour plus d’informations, voir : Filtrer les lignes
$orderby Pour les propriétés de navigation à valeur de collection, contrôlez l’ordre des enregistrements retournés. Non pris en charge avec $expand imbriqué. Pour plus d’informations, consultez $expand imbriqué dans les propriétés de navigation à valeur de collection
$top Pour les propriétés de navigation à valeur de collection, limitez le nombre des enregistrements retournés. Non pris en charge avec $expand imbriqué. Pour plus d’informations, consultez $expand imbriqué dans les propriétés de navigation à valeur de collection
$expand Développez les propriétés de navigation dans le jeu d’entités associé. En utilisant $expand dans un $expand s’appelle un $expand imbriqué. Pour plus d’informations, consultez Développement imbriqué des propriétés de navigation à valeur unique et $expand imbriqué dans les propriétés de navigation à valeur de collection

Ces options sont un sous-ensemble des options de requête décrites dans la section 11.2.4.2.1 Développer les options de Partie 1 de la version 4.0 d’OData : Protocol Plus Errata 02. Les options $skip, $count, $search, et $levels ne sont pas prises en charge pour l’API web Dataverse.

Utilisez ces options avec $expand en les ajoutant entre parenthèses après le nom de la propriété de navigation. Séparez chaque option par un point-virgule (;).

Par exemple, dans la requête qui suit :

  • Demande la propriété account.name

  • Rejoint la propriété de navigation AccountTasks de la collection demandant :

    • Propriété task.subject
    • Emplacement où task.subject contient la chaîne de caractères « Task »
    • Trié par date de task.createdon, dans l’ordre décroissant
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)

Limiter les colonnes avec $select

Comme pour toute requête, limitez toujours les colonnes renvoyées à l’aide de $select quand vous utilisez $expand. Par exemple, la requête suivante renvoie les valeurs contact.fullname et task.subject dans les résultats développés du type d’entité account :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=1

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
            },
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80649460\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Différences de type de propriété de navigation

Il est important de garder en tête qu’il existe deux types de propriétés de navigation. Informations complémentaires : Propriétés de navigation de l’API web

  • Les propriétés de navigation à valeur unique correspondent aux attributs de recherche qui prennent en charge les relation plusieurs-à-un et permettent de définir une référence à un autre enregistrement.

  • Les propriétés de navigation avec une valeur de collection correspondent aux relations un-à-plusieurs ou plusieurs-à-plusieurs.

Le développement d’une propriété de navigation à valeur de collection peut augmenter la taille de la réponse d’une manière qu’il est difficile d’anticiper. Il est important que vous incluiez des limites pour contrôler la quantité de données renvoyées. Vous pouvez limiter le nombre d’enregistrements en utilisant la pagination. Pour plus d’informations, voir : Résultats sur la page

Il existe une différence significative dans la manière dont la pagination est appliquée aux options $expand imbriquées appliquées aux propriétés de navigation à valeur de collection. Pour plus d’informations, consultez Développer les propriétés de navigation à valeur de collection

Développer les propriétés de navigation à valeur unique

L’exemple suivant montre comment récupérer des enregistrements de contact, y compris le contact principal et l’utilisateur qui a créé les enregistrements.

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)  
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Susanna Stubberod (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Nancy Anderson (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

La propriété de navigation à valeur unique createdby renvoie une instance de l’EntityType systemuser. Les propriétés systemuserid et ownerid sont renvoyées. En effet, systemuser hérite de EntityType principal et partage la clé primaire ownerid avec l’équipe EntityType par cet héritage.

Cependant, la Table utilisateur (SystemUser) possède la clé primaire SystemUserId. Les propriétés systemuserid et ownerid ont la même valeur. Pour plus d’informations, voir : Héritage de type d’entité

Références de retour

Au lieu de retourner les données, vous pouvez également retourner des références (liens) aux enregistrements associés en développant la propriété de navigation à valeur unique avec l’option /$ref. L’exemple suivant renvoie des objets JSON avec une propriété @odata.id qui a une URL pour chaque contact principal.

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Vous pouvez uniquement utiliser l’option /$ref avec les propriétés de navigation à valeur unique. Si vous l’utilisez pour une propriété de navigation avec une valeur de collection, l’erreur suivante est retournée :

{
    "error": {
        "code": "0x80060888",
        "message": "Expand with $ref is only supported on lookup type navigation property."
    }
}

Développement imbriqué des propriétés de navigation à valeur unique

Vous pouvez étendre les propriétés de navigation à valeur unique sur plusieurs niveaux en imbriquant une option $expand dans un autre option $expand.

La requête suivante renvoie des enregistrements task et étend le contact associé, le account associé au contact, et enfin le systemuser qui a créé l’enregistrement account.

Demande :

GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
 $expand=parentcustomerid_account($select=name;
  $expand=createdby($select=fullname)))  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
    "value": [
        {
            "@odata.etag": "W/\"80730855\"",
            "subject": "Task 1 for Susanna Stubberod",
            "activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        },
        {
            "@odata.etag": "W/\"80730861\"",
            "subject": "Task 2 for Susanna Stubberod",
            "activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Développer les propriétés de navigation à valeur de collection

Il existe des différences importantes dans la réponse selon que vous utilisez $expand imbriqué avec une propriété de navigation à valeur de collection n’importe où dans votre requête.

$expand imbriqué $expand unique
Paging Pagination sur lignes développées. Pagination uniquement sur Ressource EntitySet. URL <property name>@odata.nextLink des lignes développées n’incluent pas les informations de pagination.
$top ou $orderby pris en charge Non Oui

Développez $expand sur les propriétés de navigation avec une valeur de collection

Si vous n’utilisez qu’un seul niveau $expand, aucune pagination n’est appliquée aux lignes développées. Si vous incluez l’en-tête de requête Prefer: odata.maxpagesize, la pagination n’est appliquée qu’à la ressource EntitySet de la requête.

Chaque propriété de navigation développée à valeur de collection renvoie une <property>@odata.nextLink URL qui n’inclut aucune information de pagination. Il s’agit d’une URL qui représente la collection filtrée pour la relation avec vos options de requête ajoutées. Vous pouvez utiliser cette URL pour envoyer une requête distincte GET et elle renvoie les mêmes lignes que celles qui ont été renvoyées dans votre requête d’origine. Vous pouvez appliquer la pagination à cette demande.

Comme aucune pagination n’est appliquée aux enregistrements développés, il est possible de renvoyer jusqu’à 5 000 enregistrements connexes pour chaque propriété de navigation à valeur de collection développée. En fonction de vos données et de la requête, il peut s’agir d’un grand nombre de données. Le renvoi d’une telle quantité de données peut affecter les performances et éventuellement entraîner l’expiration de votre requête. Soyez prudent avec les requêtes que vous composez. Vous pouvez utiliser les options $top, $filter et $orderby pour contrôler le nombre total d’enregistrements renvoyés.

L’exemple suivant inclut un seul développement de Account_Tasks et contact_customer_accounts lors de la récupération des enregistrements de compte. L’en-tête de requête Prefer: odata.maxpagesize=1 garantit qu’un seul enregistrement de compte est renvoyé dans la première page.

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80730894\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730903\"",
                    "subject": "Task 2 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730909\"",
                    "subject": "Task 3 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
            "contact_customer_accounts": [
                {
                    "@odata.etag": "W/\"80648695\"",
                    "fullname": "Susanna Stubberod (sample)",
                    "_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Comparez cette réponse avec l’exemple suivant, qui inclut un $expand imbriqué. Faites défiler l’exemple de réponse horizontalement pour voir que seule l’URL @odata.nextLink du résultat du compte contient des informations de pagination.

$expand imbriqué dans les propriétés de navigation avec une valeur de collection

Si vous utilisez un $expand imbriqué n’importe où dans votre requête et que vous avez inclus l’en-tête de requête Prefer: odata.maxpagesize, la pagination est appliquée à chacune des collections étendues.

Chaque propriété de navigation développée à valeur de collection renvoie une <property>@odata.nextLink URL qui inclut des informations de pagination. Vous pouvez utiliser cette URL pour envoyer une requête distincte GET et elle renverra l’ensemble d’enregistrements qui n’était pas inclus dans votre requête d’origine.

Vous ne pouvez pas utiliser les options $top ou $orderby pour limiter le nombre total d’enregistrements renvoyés avec un $expand imbriqué. L’erreur suivante est renvoyée si vous utilisez ces options :

{
    "error": {
        "code": "0x80060888",
        "message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
    }
}

L’exemple suivant est basé sur l’exemple précédent et utilise les mêmes données. La seule différence est l’ajout dans l’URL de ce $expand imbriqué sur une propriété de navigation à valeur unique pour renvoyer le utilisateur propriétaire du contact : ;$expand=owninguser($select=fullname).

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname))
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "subject": "Task 1 for Litware",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
            "contact_customer_accounts": [
                {
                    "fullname": "Susanna Stubberod (sample)",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                    "owninguser": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Comparez cette réponse avec l’exemple précédent, qui n’utilise pas de $expand imbriqué. Dans cette réponse, l’en-tête de requête Prefer: odata.maxpagesize=1 est appliqué aux enregistrements task retournés avec Account_Tasks. Une seule tâche est renvoyée au lieu de trois. L’ URL Account_Tasks@odata.nextLink renvoie les deux tâches suivantes. Faites défiler l’exemple de réponse horizontalement pour voir que les URL Account_Tasks@odata.nextLink, contact_customer_accounts@odata.nextLink et@odata.nextLink contiennent des informations de pagination.

Lignes de commande

Utilisez $orderby l’option de requête pour spécifier l’ordre dans lequel les éléments sont renvoyés. Utilisez le suffixe asc ou desc pour spécifier l’ordre croissant ou décroissant respectivement. L’ordre par défaut est croissant. L’exemple suivant présente la récupération des propriétés name et revenue des comptes contrôlées par le revenue croissant et par le name décroissant.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Tri et pagination

La façon dont une page est triée fait une grande différence lors de la pagination des données. Si les informations de tri des résultats sont ambiguës, Dataverse ne peut pas renvoyer de manière cohérente ou efficace les données paginées.

Spécifiez un ordre pour votre requête. Avec FetchXml, si vous n’ajoutez aucun élément de commande à votre requête, Dataverse ajoute une commande basée sur la clé primaire de la table. Cependant QueryExpression ne le fait pas, et lorsque votre requête spécifie distinct des résultats, aucune valeur de clé primaire n’est renvoyée, donc Dataverse peut pas ajouter cet ordre par défaut. Vous devez spécifier un ordre de pagination. Sans aucun ordre spécifié, les résultats de la requête distinct peuvent être renvoyés dans un ordre aléatoire. OData ne propose aucune option pour renvoyer des résultats distincts, mais vous devez toujours appliquer un ordre lors de la récupération des résultats paginés.

La pagination est dynamique. Chaque requête est évaluée de manière indépendante au fur et à mesure qu’elle est reçue. Un cookie de pagination indique à Dataverse la page précédente. Avec ces données de cookie de pagination, Dataverse peut commencer par l’enregistrement suivant après le dernier de la page précédente.

La pagination fonctionnera mieux à l’avenir. Si vous revenez en arrière et récupérez une page que vous avez précédemment récupérée, les résultats peuvent être différents car des enregistrements peuvent être ajoutés, supprimés ou modifiés depuis la dernière récupération de la page. En d’autres termes, si la taille de votre page est de 50 et que vous revenez en arrière, vous obtenez 50 enregistrements, mais ce ne sont peut-être pas les mêmes 50 enregistrements. Si vous continuez à avancer dans les pages d’un jeu de données, vous pouvez vous attendre à ce que tous les enregistrements soient renvoyés dans un ordre cohérent.

Le tri déterministe est important

Le tri déterministe signifie qu’il existe un moyen de calculer un ordre de manière cohérente. Avec un ensemble d’enregistrements donné, les enregistrements sont toujours renvoyés dans le même ordre. Si vous avez besoin d’ordres et de pagination cohérents, vous devez inclure des valeurs uniques ou une combinaison de valeurs de colonne et spécifier un ordre pour qu’elles soient évaluées.

Exemple non déterministe

Examinons un exemple qui est non déterministe. Ce jeu de données contient uniquement des informations sur l’État et le Statut et est filtré pour renvoyer uniquement les enregistrements dans un État ouvert. Les résultats sont classés par Statut. Les trois premières pages sont demandées. Les résultats ressemblent à ce qui suit :

État Statut Page
Ouvert Actif 1. Début
Ouvert Actif 1
Ouvert Actif 1 Fin
Ouvert Actif
Ouvert Actif
Ouvert Inactif
Ouvert Inactif

Le cookie de pagination enregistre les informations sur le dernier enregistrement de la page. Lorsque la page suivante est demandée, le dernier enregistrement de la première page n’est pas inclus. Cependant, compte tenu des données non déterministes, rien ne garantit que les deux autres enregistrements de la première page ne soient pas inclus dans la deuxième page.

Pour obtenir un tri déterministe, ajoutez des ordres aux colonnes contenant des valeurs uniques ou des valeurs semi-uniques.

Exemple déterministe

Cette requête est similaire à la requête non déterministe, mais elle inclut la colonne ID de cas qui inclut des valeurs uniques. Il est également trié par Statut, mais également par ID de cas. Les résultats ressemblent à ce qui suit :

État Statut ID d’incident Page
Ouvert Actif Incident-0010 1. Début
Ouvert Actif Incident-0021 1
Ouvert Actif Incident-0032 1 Fin
Ouvert Actif Incident-0034
Ouvert Actif Incident-0070
Ouvert Inactif Incident-0015
Ouvert Inactif Incident-0047

Dans la page suivante, le cookie aura Case-0032 stocké comme dernier enregistrement de la première page ; par conséquent, la page deux commencera avec l’enregistrement suivant après cet enregistrement. Les résultats ressemblent à ce qui suit :

État Statut ID d’incident Page
Ouvert Actif Incident-0010 1. Début
Ouvert Actif Incident-0021 1
Ouvert Actif Incident-0032 1 Fin
Ouvert Actif Incident-0034 2. Début
Ouvert Actif Incident-0070 2
Ouvert Inactif Incident-0015 2 Fin
Ouvert Inactif Incident-0047

Étant donné que cette requête tri les valeurs de colonne uniques, l’ordre est cohérent.

Pratiques recommandées pour les tris lors de la pagination des données

Notes

Lorsque cela est possible, les requêtes doivent être triées en fonction de la clé primaire de la table, car Dataverse est optimisé par défaut pour le tri sur la clé primaire. Le tri en fonction de champs non uniques ou complexes entraîne une surcharge excessive et des requêtes plus lentes.

Lorsque vous récupérez un ensemble limité de données à afficher dans une application, ou si vous devez renvoyer plus de 5 000 lignes de données, vous devez paginer les résultats. Les choix effectués pour déterminer l’ordre des résultats peuvent déterminer si les lignes de chaque page de données que vous récupérez chevauchent d’autres pages. Sans un tri approprié, le même enregistrement peut apparaître sur plusieurs pages.

Pour éviter que le même enregistrement apparaisse sur plusieurs pages, appliquez les pratiques recommandées suivantes :

Il est préférable d’inclure une colonne possédant un identificateur unique. Par exemple :

  • Colonnes de clé primaire de la table
  • Colonnes de numérotation automatique
  • ID utilisateur/contact

Si vous ne pouvez pas inclure une colonne avec un identificateur unique, incluez plusieurs champs qui généreront très probablement des combinaisons uniques. Par exemple :

  • Prénom + nom + adresse e-mail
  • Nom complet + adresse e-mail
  • Adresse e-mail + nom de l’entreprise

Anti-modèles pour les tris lors de la pagination des données

Les choix de tri suivants doivent être évités :

  • Les tris qui n’incluent pas d’identificateurs uniques

  • Les tris sur des champs calculés

  • Tris avec un ou plusieurs champs qui ne fournissent probablement pas un caractère unique, tels que :

    • Statut et état
    • Choix ou Oui/Non
    • Nommez les valeurs par elles-mêmes. Par exemple name, firstname, lastname
    • Champs de texte comme les titres, les descriptions et le texte sur plusieurs lignes
    • Champs de nombres non uniques

Lignes de filtre

Utilisez l’option de requête $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. 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é d’évaluation d’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

Si vous utilisez une propriété de recherche dans un $filter, vous pouvez également utiliser une collection filtrée avec la propriété de navigation à valeur de collection correspondante. Par exemple, ces deux requêtes renvoient les mêmes résultats :

accounts?$filter=_owninguser_value eq '<systemuserid value>'&$select=name

systemusers(<systemuserid value>)/user_accounts?$select=name

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é d’évaluation d’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
Informations complémentaires : Rechercher les données hiérarchiques
Colonnes de choix ContainValues, DoesNotContainValues
Pour plus d’informations, consultez Interroger des données à partir de 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 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 les caractères génériques de fin. 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 fin ne sont pas pris en charge

Il est important de ne pas utiliser de caractères génériques de fin, 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 fin :

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

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 à 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 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 l’entité de compte qui possèdent 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 l’entité de compte disposant de toutes les tâches associées 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 l’entité de compte qui possèdent 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

Résultats sur la page

Utilisez l’en-tête de requête Prefer: odata.maxpagesize pour contrôler le nombre d’enregistrements renvoyés. Si vous ne spécifiez pas de nombre, jusqu’à 5 000 enregistrements peuvent être renvoyés pour chaque demande. Vous ne pouvez pas demander une taille de page supérieure à 5 000.

Notes

Dataverse ne prend pas en charge l’option de requête $skip ; par conséquent, vous ne pouvez pas utiliser la combinaison de $top et $skip pour la pagination. Pour plus d’informations : Utiliser l’option de requête $top

L’exemple suivant renvoie uniquement les deux premiers enregistrements de contact :

Demande :

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"72201545\"",
            "fullname": "Yvonne McKay (sample)",
            "contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
        },
        {
            "@odata.etag": "W/\"80648695\"",
            "fullname": "Susanna Stubberod (sample)",
            "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Lorsqu’il y a plus d’enregistrements que ceux demandés, l’annotation @odata.nextLink fournit une URL que vous pouvez utiliser avec GET pour renvoyer la page suivante de données, comme le montre l’exemple suivant :

Demande :

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"80648710\"",
            "fullname": "Nancy Anderson (sample)",
            "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
        },
        {
            "@odata.etag": "W/\"80648724\"",
            "fullname": "Maria Campbell (sample)",
            "contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Vous devez mettre en cache les résultats renvoyés ou la valeur de l’URL @odata.nextLink et l’utiliser pour revenir aux pages précédentes.

Ne modifiez pas la valeur de l’URL @odata.nextLink ou n’y ajoutez pas des options de requête. Pour chaque demande ultérieure de pages supplémentaires, vous devez utiliser la même valeur de préférence odata.maxpagesize que celle utilisée dans la demande initiale. Vous pouvez continuer à parcourir les données jusqu’à ce qu’il n’y ait plus d’annotation @odata.nextLink dans les résultats.

Dans les exemples précédents, les informations codées étaient définies comme la valeur du paramètre $skiptoken dans la valeur de l’URL @odata.nextLink. Le serveur définit cette information codée pour contrôler la pagination. Vous ne devez pas modifier les informations codées ou les encoder davantage. Utilisez la valeur URL fournie pour récupérer la page suivante.

Utiliser l’option de requête $top

Utilisez l’option de requête $top pour limiter le nombre de résultats renvoyés. N’utilisez pas $top avec l’en-tête de demande Prefer: odata.maxpagesize. Si vous incluez les deux, $top est ignoré.

L’exemple suivant renvoie seulement les trois premières lignes de compte :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3

Données agrégées

Utilisez l’option $apply pour agréger et grouper vos données de façon dynamique.

Les fonctions agrégées sont limitées à un ensemble de 50 000 enregistrements. De plus amples informations sur l’utilisation de la fonctionnalité d’agrégation avec Dataverse se trouvent ici : Agréger des données à l’aide de FetchXml.

Vous pouvez trouver davantage d’informations sur l’agrégation de données OData se trouvent ici : Extension OData pour la version 4.0 de l’agrégation de données. Dataverse ne prend en charge qu’un sous-ensemble de ces méthodes d’agrégation.

Notes

  • groupby avec des valeurs datetime n’est pas pris en charge.

  • $orderby avec des valeurs agrégées n’est pas pris en charge. Cela renvoie l’erreur : The query node SingleValueOpenPropertyAccess is not supported.

Voici quelques exemples :

Par souci de concision, ces exemples n’indiquent pas la demande et la réponse complètes.

Liste de statuts uniques dans la requête

GET accounts?$apply=groupby((statuscode))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2
        }
    ]
}

Valeurs Nombre par statut

GET accounts?$apply=groupby((statuscode),aggregate($count as count))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "count@OData.Community.Display.V1.FormattedValue": "8",
            "count": 8
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "count@OData.Community.Display.V1.FormattedValue": "1",
            "count": 1
        }
    ]
}

Somme agrégée des revenus

GET accounts?$apply=aggregate(revenue with sum as total)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$440,000.00",
            "total": 440000.000000000
        }
    ]
}

Revenu moyen en fonction du statut

GET accounts?$apply=groupby((statuscode),aggregate(revenue with average as averagevalue))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$53,750.00",
            "averagevalue": 53750.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "averagevalue": 10000.000000000
        }
    ]
}

Somme des revenus en fonction du statut

GET accounts?$apply=groupby((statuscode),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "total@OData.Community.Display.V1.FormattedValue": "$430,000.00",
            "total": 430000.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000
        }
    ]
}

Total des revenus du compte par nom de contact principal

GET accounts?$apply=groupby((primarycontactid/fullname),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000,
            "contact_fullname": "Jim Glynn (sample)"
        },
        {
            "total@OData.Community.Display.V1.FormattedValue": "$80,000.00",
            "total": 80000.000000000,
            "contact_fullname": "Maria Campbell (sample)"
        },
      ... <truncated for brevity>
      
    ]
}

Noms du contact principal pour les comptes dans « WA »

GET accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "contact_fullname": "Rene Valdes (sample)"
        },
        {
            "contact_fullname": "Robert Lyon (sample)"
        },
        {
            "contact_fullname": "Scott Konersmann (sample)"
        }
    ]
}

Date et heure de l’enregistrement créé en dernier

GET accounts?$apply=aggregate(createdon with max as lastCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "lastCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "lastCreate": "2023-03-25T17:42:47Z"
        }
    ]
}

Date et heure de l’enregistrement créé en premier

GET accounts?$apply=aggregate(createdon with min as firstCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Corps de réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "firstCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "firstCreate": "2023-03-25T17:42:46Z"
        }
    ]
}

Compter le nombre de lignes

Utilisez l’option de requête $count=true pour inclure un nombre d’entités correspondant aux critères de filtre jusqu’à 5 000.

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=accountid&$count=true
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid)",
    "@odata.count": 9,
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        },
        ... <Truncated for brevity>
    ]
}

L’annotation @odata.count de la réponse contient le nombre de lignes, jusqu’à 5 000, qui correspondent aux critères de filtrage, quelle que soit la taille de la page demandée.

Notes

Si vous souhaitez obtenir un instantané du nombre total de lignes d’une table au-delà de 5 000 au cours des dernières 24 heures, utilisez la fonction RetrieveTotalRecordCount.

Si la valeur de comptage est 5 000 et que vous voulez savoir si le comptage est exactement de 5 000 ou supérieure à 5 000, vous pouvez ajouter l’en-tête suivant :

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.totalrecordcount,Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded"

Cet en-tête ajoute les annotations suivantes au résultat :

  • @Microsoft.Dynamics.CRM.totalrecordcount
  • @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded

Quand il est utilisé avec l’option de requête $count=true, et qu’il y a plus de 5 000 enregistrements, vous verrez ces valeurs :

"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,

S’il y a moins de 5 000 enregistrements, le nombre réel est renvoyé.

"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,

Si vous n’incluez pas l’option de requête $count=true, la valeur @Microsoft.Dynamics.CRM.totalrecordcount totale est -1.

L’exemple suivant montre qu’il y a dix comptes qui correspondent au $filter, mais que seuls les trois premiers comptes sont renvoyés :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.maxpagesize=3
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
   "value":[  
      {  
         "@odata.etag":"W/\"502482\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502483\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502484\"",
         "name":"Adventure Works (sample)",
         "accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
      }
   ],
   "@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Pour obtenir juste un nombre qui représente le nombre d’une collection, ajoutez /$count, comme dans l’exemple suivant :

Demande :

GET [Organization URI]/api/data/v9.2/accounts/$count  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: text/plain  
OData-Version: 4.0  
  
10

Voir aussi

Rechercher des enregistrements Dataverse
Exemples de données de requête d'API Web (C#)
Exemple de données de requête de l’API web (Javascript côté client)
Effectuer des opérations à l’aide de l’API Web
Composer des demandes HTTP et traiter les erreurs