Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
L’objectif principal de l’exécution de plusieurs requêtes est d’améliorer les performances dans les environnements à latence élevée en réduisant le volume total de données transmises sur le réseau.
Vous pouvez utiliser le message ExecuteMultipleRequest pour prendre en charge des scénarios d’envoi en masse de messages à haut débit dans Microsoft Dataverse. ExecuteMultipleRequest accepte une collection d’entrée de messages Requests, exécute chacune des demandes de message dans l’ordre dans lequel elles apparaissent dans la collection d’entrée et renvoie en option un ensemble de Responses contenant la réponse de chaque message ou l’erreur qui s’est produite. Chaque demande de message dans la collection d’entrée est traitée dans une transaction de base de données distincte. Utilisez la méthode IOrganizationService.Execute pour exécuter ExecuteMultipleRequest.
En général, ExecuteMultipleRequest se comporte comme si vous exécutiez séparément chaque demande de message de la collection de demandes en entrée, si ce n’est avec des performances optimisées. Le proxy de service respecte l’utilisation du CallerId paramètre et l’applique à l’exécution de chaque message dans la collection de demandes d’entrée. Les plug-ins et les activités de flux de travail s’exécutent comme prévu pour chaque message traité.
Les plug-ins et les activités de workflow personnalisées peuvent utiliser ExecuteMultipleRequest. Toutefois, cette approche n’est pas recommandée. Toute défaillance de l’étape synchrone doit annuler toutes les opérations de données pour maintenir l’intégrité des données. Chaque opération effectuée dans ExecuteMultiple doit être annulée.
ExecuteMultiple provoque également des problèmes lorsque les opérations dépassent la durée maximale du délai d’expiration du plug-in.
En savoir plus : Ne pas utiliser les types de demandes par lots dans les plug-ins et les activités de workflow
Exemple
L’exemple de code suivant illustre un simple ExecuteMultipleRequest qui effectue plusieurs opérations de création. Options d’exécution au moment de l’exécution appelées Paramètres contrôlent le traitement des demandes et renvoient les résultats. La section suivante décrit ces options d’exécution.
// Create an ExecuteMultipleRequest object.
ExecuteMultipleRequest requestWithResults = new ExecuteMultipleRequest()
{
// Assign settings that define execution behavior: continue on error, return responses.
Settings = new ExecuteMultipleSettings()
{
ContinueOnError = false,
ReturnResponses = true
},
// Create an empty organization request collection.
Requests = new OrganizationRequestCollection()
};
// Create several (local, in memory) entities in a collection.
EntityCollection input = GetCollectionOfEntitiesToCreate();
// Add a CreateRequest for each entity to the request collection.
foreach (var entity in input.Entities)
{
CreateRequest createRequest = new CreateRequest { Target = entity };
requestWithResults.Requests.Add(createRequest);
}
// Execute all the requests in the request collection using a single web method call.
ExecuteMultipleResponse responseWithResults =
(ExecuteMultipleResponse)service.Execute(requestWithResults);
// Display the results returned in the responses.
foreach (var responseItem in responseWithResults.Responses)
{
// A valid response.
if (responseItem.Response != null)
DisplayResponse(requestWithResults.Requests[responseItem.RequestIndex], responseItem.Response);
// An error has occurred.
else if (responseItem.Fault != null)
DisplayFault(requestWithResults.Requests[responseItem.RequestIndex],
responseItem.RequestIndex, responseItem.Fault);
}
Pour plus d’informations, voir Exemple : Exécuter plusieurs demandes
Spécifier les options d’exécution du runtime
Le Settings paramètre de ExecuteMultipleRequest s’applique à toutes les requêtes de la collection de requêtes et contrôle le comportement d’exécution et les résultats retournés.
| Membre ExecuteMultipleSettings | Description |
|---|---|
| ContinueOnError | Lorsque la valeur est true, continuez à traiter la demande suivante de la collection même si une erreur est renvoyée lors du traitement de la demande en cours dans la collection. Lorsque la valeur est false, ne poursuivez pas le traitement de la demande suivante. |
| ReturnResponses | Lorsque la valeur est true, les réponses de retour de chaque demande de message sont traitées. Lorsque la valeur est false, ne renvoyez pas de réponses.Si la valeur est true et qu’une demande ne renvoie pas de réponse, parce qu’elle est ainsi conçue, l’élément ExecuteMultipleResponseItem de cette requête a la valeur null.Cependant, même si la valeur est false, la collection Responses ne sera pas vide si des erreurs sont retournées. Lorsque des erreurs sont renvoyées, la collection contient un élément de réponse pour chaque requête traitée qui renvoie une erreur, et Fault est défini sur l’erreur réelle qui s’est produite. |
Par exemple, dans un ensemble contenant six demandes où les erreurs retournées concernent la troisième et la cinquième demande, le tableau suivant indique ce que la collection Responses doit contenir.
| Paramètres | Contenu de la collection de réponses |
|---|---|
| ContinueOnError=true, ReturnResponses=true | 6 éléments de réponse : 2 avec la propriété Fault définie sur une valeur. |
| ContinueOnError=false (continuer en cas d'erreur=false), ReturnResponses=true (retourner les réponses=true) | 3 éléments de réponse : 1 avec la propriété Fault définie sur une valeur. |
| ContinueOnError=true, ReturnResponses=false | 2 éléments de réponse : 2 avec la propriété Fault définie sur une valeur. |
| ContinueOnError=false, ReturnResponses=false | 1 élément de réponse : 1 avec Fault défini sur une valeur. |
Un paramètre RequestIndex de l’élément de réponse indique le numéro de séquence, à partir de zéro, de la demande à laquelle la réponse est associée. Dans l’exemple précédent, la troisième demande a un index de demande égal à 2.
Limitations d’exécution
La liste suivante décrit les contraintes liées à l’utilisation du ExecuteMultipleRequest.
- Aucune récursivité Impossible ExecuteMultipleRequest d’appeler un autre ExecuteMultipleRequest. Si la collection de requêtes contient un ExecuteMultipleRequest, elle génère une erreur pour cet élément de requête.
- Taille maximale du lot Vous ne pouvez ajouter qu’un nombre limité de requêtes à une collection de demandes. Si vous dépassez cette limite, le système lève une erreur avant d’exécuter la première requête. Une limite de 1 000 requêtes est classique, mais vous pouvez définir ce montant maximal pour votre déploiement Dataverse.
Remarque
Il y avait une fois une limite au nombre de requêtes ExecuteMultiple simultanées. La limite était de 2. Microsoft supprimé cette limite, car les limites de protection des services l’ont rendu inutile. Pour plus d’informations, consultez Limites de l’API Protection des services.
Gérer une erreur de taille de lot
Que devez-vous faire si votre collection de demandes d’entrée dépasse la taille maximale du lot ? Votre code ne peut pas interroger directement la taille de lot maximale via le service web de déploiement, sauf s’il s’exécute sous un compte disposant du rôle d’administrateur de déploiement.
Heureusement, il existe une autre méthode que vous pouvez utiliser. Lorsque le nombre de requêtes dans la collection d’entrée Requests dépasse la taille de lot maximale autorisée pour une organisation, l’appel ExecuteMultipleRequest retourne une erreur. L’erreur inclut la taille maximale du lot. Votre code peut contrôler cette valeur, redimensionner la collection de demandes en entrée dans la limite indiquée et renvoyer ExecuteMultipleRequest. L’extrait de code suivant illustre une partie de cette logique.
catch (FaultException<OrganizationServiceFault> fault)
{
// Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if
// the input request collection count exceeds the maximum batch size.
if (fault.Detail.ErrorDetails.Contains("MaxBatchSize"))
{
int maxBatchSize = Convert.ToInt32(fault.Detail.ErrorDetails["MaxBatchSize"]);
if (maxBatchSize < requestWithResults.Requests.Count)
{
// Here you could reduce the size of your request collection and re-submit the ExecuteMultiple request.
// For this sample, that only issues a few requests per batch, we will just print out some info. However,
// this code will never be executed because the default max batch size is 1000.
Console.WriteLine("The input request collection contains %0 requests, which exceeds the maximum allowed (%1)",
requestWithResults.Requests.Count, maxBatchSize);
}
}
// Re-throw so Main() can process the fault.
throw;
}
Voir aussi
Utilisez les messages avec le SDK pour .NET
Utiliser ExecuteAsync
Utiliser ExecuteTransaction