Utiliser FetchXML pour créer une requête

Article
09/21/2023

FetchXML est un langage de requête XML propriétaire de Microsoft Dataverse utilisé pour interroger des données en utilisant l’API Web ou le SDK pour .NET. Il est basé sur un schéma qui décrit les fonctionnalités du langage. Le langage FetchXML prend en charge des fonctionnalités similaires de requête, telles que des expressions de requête. En outre, il est utilisé comme une série de requêtes, utilisée pour enregistrer une requête comme une vue appartenant à l’utilisateur enregistrée dans la table UserQuery et comme une vue appartenant à l’organisation enregistrée dans la table SavedQuery.

Créer la chaîne de requête FetchXML

Pour exécuter une requête FetchXML, vous devez d’abord créer la chaîne de requête XML. Après avoir créé la chaîne de requête, utilisez la méthode IOrganizationService.RetrieveMultiple pour exécuter la chaîne de requête. Les privilèges de l’utilisateur connecté attribue l’ensemble des enregistrements renvoyés. Seuls les enregistrements pour lesquels l’utilisateur connecté dispose d’un accès en lecture sont renvoyés.

La chaîne recherchée FetchXML doit se conformer à la définition de schéma du langage FetchXML. Pour plus d’informations, voir Schéma FetchXML.

Vous pouvez enregistrer une requête en créant un enregistrement SavedQuery. Définissez visible sur le nœud link-entity à false pour masquer la table associée dans l’interface utilisateur Recherche avancée. Elle participera toujours à la requête et renverra toujours les résultats appropriés.

Avertissement

Ne récupérez pas toutes les colonnes d’une requête du fait de l’impact négatif sur les performances. Cela est particulièrement vrai si la requête est utilisée comme un paramètre à une demande de mise à jour. Dans une mise à jour, si toutes les colonnes sont incluses, cela définit les valeurs de champ, même si elles sont inchangées, et engendre souvent des mises à jour en cascade vers les enregistrements enfants.

Exemple de chaînes de requête FetchXML

Dans l’exemple suivant, l’instruction FetchXML récupère tous les comptes :

  
<fetch mapping='logical'>   
   <entity name='account'>  
      <attribute name='accountid'/>   
      <attribute name='name'/>   
   </entity>  
</fetch>

Dans l’exemple suivant, l’instruction FetchXML récupère tous les comptes où le nom de l’utilisateur détenteur ne correspond pas à Cannon :

  
<fetch mapping='logical'>  
   <entity name='account'>   
      <attribute name='accountid'/>   
      <attribute name='name'/>   
      <link-entity name='systemuser' to='owninguser'>   
         <filter type='and'>   
            <condition attribute='lastname' operator='ne' value='Cannon' />   
          </filter>   
      </link-entity>   
   </entity>   
</fetch>

Dans l’exemple suivant, l’instruction FetchXML utilise un nombre pour définir le nombre maximal d’enregistrements renvoyés de la requête. Dans ce cas, les 3 premiers comptes sont renvoyés de la requête,

<fetch mapping='logical' count='3'>  
  <entity name='account'>  
   <attribute name='name' alias='name'/>  
  </entity>
</fetch>

Cet exemple illustre une jointure interne entre EntityMap et AttributeMap où EntityMapID correspond.

<fetch version='1.0' mapping='logical' distinct='false'>  
   <entity name='entitymap'>  
      <attribute name='sourceentityname'/>  
      <attribute name='targetentityname'/>  
      <link-entity name='attributemap' alias='attributemap' to='entitymapid' from='entitymapid' link-type='inner'>  
         <attribute name='sourceattributename'/>  
         <attribute name='targetattributename'/>  
      </link-entity>  
   </entity>  
 </fetch>

Important

Une requête FetchXML a une limite de 15 tables de lien au maximum autorisées.

Exécuter la requête FetchXML

Vous pouvez exécuter une requête FetchXML à l’aide de l’API Web ou du SDK pour .NET.

Utilisation de l’API Web

Vous pouvez transmettre une chaîne FetchXml codée à l’entityset approprié à l’aide du paramètre de chaîne de requête fetchXml. Plus d′informations : Utiliser FetchXml avec l′API web.

Utilisation du SDK pour .NET

Utilisez la méthode IOrganizationService.RetrieveMultiple en transmettant une FetchExpression où la propriété Query contient la requête FetchXml.

Le code suivant montre comment exécuter une requête FetchXML à l’aide du service d’organisation :

  
// Retrieve all accounts owned by the user with read access rights to the accounts and   
// where the last name of the user is not Cannon.   
string fetch2 = @"  
   <fetch mapping='logical'>  
     <entity name='account'>   
        <attribute name='accountid'/>   
        <attribute name='name'/>   
        <link-entity name='systemuser' to='owninguser'>   
           <filter type='and'>   
              <condition attribute='lastname' operator='ne' value='Cannon' />   
           </filter>   
        </link-entity>   
     </entity>   
   </fetch> ";   
  
EntityCollection result = _serviceProxy.RetrieveMultiple(new FetchExpression(fetch2));
foreach (var c in result.Entities)
{
   System.Console.WriteLine(c.Attributes["name"]);
}

Important

Lorsque vous utilisez du code tel que l’exemple ci-dessus, veillez toujours à ce que votre chaîne soit une chaîne XML encodée valide. Cela est particulièrement vrai concernant la possibilité de contenir des caractères spéciaux dans les valeurs de condition telles que &<> étant encodées comme &<>.

Vous pouvez convertir une requête FetchXML en une expression de requête avec le message FetchXmlToQueryExpressionRequest.

Résultats de la requête FetchXML

Lorsque vous exécutez une requête FetchXML à l’aide de la méthode OrganizationServiceProxy.RetrieveMultiple(QueryBase) la valeur renvoyée contient est une EntityCollection contenant les résultats de la requête. Vous pouvez ensuite itérer via la collection de tables. L’exemple précédent utilise une boucle foreach pour itérer via la collection de résultats de la requête FetchXML.

Utilisez des caractères génériques dans les conditions à l’aide de valeurs de chaîne

Vous pouvez utiliser des caractères génériques lorsque vous construisez des requêtes à l’aide de conditions sur des valeurs de chaîne. Plus d’informations : Utilisez des caractères génériques dans les conditions pour les valeurs de chaîne

Notes

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

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

Partager via