Extraire et exécuter des requêtes prédéfinies

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 permet aux administrateurs de créer des vues système qui sont accessibles à tous les utilisateurs. Les utilisateurs individuels peuvent enregistrer les requêtes de recherche avancée pour une réutilisation dans l'application. Elles représentent toutes deux des requêtes prédéfinies que vous pouvez récupérer et exécuter à l'aide de l'API Web. Vous pouvez aussi composer une requête à l'aide de FetchXml et l'utiliser pour récupérer des données.

Contenu de la rubrique

Requêtes prédéfinies

Utiliser la requête FetchXML personnalisée

Requêtes prédéfinies

Microsoft Dynamics 365 vous permet de définir, d'enregistrer, puis d'exécuter deux types de requêtes comme répertoriées ici.

Type de requête	Description
Requête enregistrée	Vues définies par le système d'une entité. Ces vues sont stockées dans savedquery EntityType.Pour plus d'informations :Personnaliser les vues d’entité
Requête utilisateur	Recherches avancées enregistrées par les utilisateurs pour une entité. Ces vues sont stockées dans userquery EntityType.Pour plus d'informations :Entité UserQuery (vue enregistrée)

Les enregistrements des deux types d'entités contiennent la définition FetchXML pour les données à retourner. Vous pouvez interroger le type d'entité respectif pour récupérer la valeur de clé primaire. Avec la valeur de clé primaire, vous pouvez exécuter la requête en passant la valeur de clé primaire. Par exemple, pour exécuter la requête Comptes actifs enregistrée, vous devez d'abord obtenir la clé primaire à l'aide d'une requête de ce type.

GET cc_WebAPI_ServiceURI/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

Vous pouvez ensuite utiliser la valeur savedqueryid et la transférer en tant que valeur au paramètre savedQuery à l'ensemble d'entités accounts.

GET cc_WebAPI_ServiceURI/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

Utilisez la même méthode pour obtenir userqueryid et la transmettre comme valeur au paramètre userQuery à l'ensemble d'entités qui correspond avec le returnedtypecode de la requête enregistrée.

GET cc_WebAPI_ServiceURI/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

Appliquer une requête à une collection de type approprié

En plus d'appliquer simplement la requête enregistrée à la collection d'entités principales, vous pouvez aussi utiliser une requête enregistrée ou requête utilisateur pour appliquer le même filtre sur une collection du type d'entités approprié. Par exemple, si vous souhaitez appliquer une requête uniquement aux entités associées à une entité spécifique, vous pouvez appliquer le même modèle. Par exemple, URL appliquera la requête Opportunités ouvertes aux opportunités associées à un compte spécifique via la propriété de navigation avec une valeur de collection opportunity_parent_account.

GET cc_WebAPI_ServiceURI/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

Utiliser la requête FetchXML personnalisée

FetchXML est une langue de requête exclusive qui fournit des fonctionnalités de regroupement. Les requêtes enregistrées et les requêtes utilisateur enregistrées dans savedquery EntityType et userquery EntityType respectivement contiennent une propriété fetchxml qui définit la requête. Vous pouvez utiliser FetchXML directement avec IOrganizationService. La méthode RetrieveMultiple ou avec RetrieveMultipleRequest.Pour plus d'informations :Générer des requêtes avec FetchXML

Vous pouvez transmettre la valeur FetchXML encodée au format URL comme requête à l'ensemble d'entités correspondant à l'entité racine de la requête à l'aide du paramètre FetchXML pour retourner les résultats de l'API Web. Par exemple, la valeur FetchXML suivante a le compte comme entité.

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

La valeur encodée au format URL de ce FetchXML est comme indiquée ici.

%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E

La plupart des langages de programmation proposent une fonction pour encoder une chaîne au format URL. Par exemple, dans JavaScript vous utilisez la fonctionnalité encodeURI. Vous devez encoder au format URL toute requête que vous envoyez à un service Web RESTful. Si vous collez une URL dans la barre d'adresse de votre navigateur, il doit encoder automatiquement l'adresse au format URL. Cet exemple illustre une requête GET utilisant la valeur FetchXML illustrée précédemment à l'aide du chemin d'accès de l'ensemble d'entités pour les comptes.

Demande

GET cc_WebAPI_ServiceURI/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,name)","value":[
    {
      "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)"
    },{
      "@odata.etag":"W/\"502172\"","accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1","name":"Litware, Inc. (sample)"
    },{
      "@odata.etag":"W/\"502174\"","accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1","name":"Adventure Works (sample)"
    },{
      "@odata.etag":"W/\"506705\"","accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1","name":"Fabrikam, Inc. (sample)"
    },{
      "@odata.etag":"W/\"506701\"","accountid":"91390c24-9c72-e511-80d4-00155d2a68d1","name":"Blue Yonder Airlines (sample)"
    },{
      "@odata.etag":"W/\"502180\"","accountid":"93390c24-9c72-e511-80d4-00155d2a68d1","name":"City Power & Light (sample)"
    },{
      "@odata.etag":"W/\"502182\"","accountid":"95390c24-9c72-e511-80d4-00155d2a68d1","name":"Contoso Pharmaceuticals (sample)"
    },{
      "@odata.etag":"W/\"506704\"","accountid":"97390c24-9c72-e511-80d4-00155d2a68d1","name":"Alpine Ski House (sample)"
    },{
      "@odata.etag":"W/\"502186\"","accountid":"99390c24-9c72-e511-80d4-00155d2a68d1","name":"A. Datum Corporation (sample)"
    },{
      "@odata.etag":"W/\"502188\"","accountid":"9b390c24-9c72-e511-80d4-00155d2a68d1","name":"Coho Winery (sample)"
    },{
      "@odata.etag":"W/\"504177\"","accountid":"0a3238d4-f973-e511-80d4-00155d2a68d1","name":"Litware, Inc."
    }
  ]
}

Notes

La réponse des requêtes FetchXML contenant des entités-liens et leurs attributs contient des caractères spéciaux Unicode telles que « . » devient « _x002e_ » et « @ » devient « _x0040_ ».

Pagination avec FetchXML

Avec fetchXML, vous pouvez appliquer la pagination en définissant les attributs page et count de l'élément fetch. Par exemple, pour définir une requête pour les comptes et limiter le nombre d'entités à 2 et pour retourner uniquement la première page, utilisez la valeur fetchXML suivante :

<fetch mapping="logical" page="1" count="2">
 <entity name="account">
  <attribute name="accountid" />
  <attribute name="name" />
  <attribute name="industrycode" />
 <order attribute="name" />
 </entity>
</fetch>

Avec une requête utilisant fetchXML, vous pouvez également demander un cookie de pagination et l'ajouter à votre requête.Pour plus d'informations :Mettre en page d’importants ensembles de résultats avec FetchXML

Un cookie de pagination doit être demandé comme annotation. Définissez la préférence odata.include-annotations pour utiliser (ou inclure) Microsoft.Dynamics.CRM.fetchxmlpagingcookie et une propriété @Microsoft.Dynamics.CRM.fetchxmlpagingcookie est retournée avec le résultat.

Voir aussi

Microsoft Dynamics 365

Partager via

Extraire et exécuter des requêtes prédéfinies

Contenu de la rubrique

Requêtes prédéfinies

Appliquer une requête à une collection de type approprié

Utiliser la requête FetchXML personnalisée

Voir aussi

Ressources supplémentaires