Utiliser FetchXML pour construire une requête

Article
06/10/2024

FetchXML est un langage de requête propriétaire basé sur XML Microsoft Dataverse utilisé pour interroger des données à l’aide de l’ API Web ou du SDK pour . NET. Il est basé sur un schéma qui décrit les fonctionnalités du langage. Le FetchXML langage prend en charge des fonctionnalités de requête similaires à celles 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 FetchXML chaîne de requête

Pour exécuter une FetchXML requête, 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 FetchXML chaîne de requête doit être conforme à la définition du schéma du FetchXML langage. 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.

Exemples FetchXML de chaînes de requête

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 pour lesquels le nom du utilisateur propriétaire n’est pas égal à 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 count pour définir le nombre maximum d’enregistrements renvoyés par 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 FetchXML requête est limitée à 15 tables de liens autorisées au maximum.

Exécuter la FetchXML requête

Vous pouvez exécuter une FetchXML requête à 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 FetchXML requête à l’aide du service Organisations :

  
// 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 FetchXML requête en expression de requête avec le FetchXmlToQueryExpressionRequest message.

FetchXML résultats de la requête

Lorsque vous exécutez une FetchXML requête à l’aide de 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 la foreach boucle pour parcourir la collection de résultats de la FetchXML requête.

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