Limites de l’API de protection des services

Article
04/09/2023

Pour garantir une disponibilité et des performances cohérentes pour tout le monde, nous appliquons certaines limites à la façon dont les API sont utilisées. Ces limites sont conçues pour détecter lorsque les applications clientes font des demandes extraordinaires sur les ressources du serveur.

Ces limites ne doivent pas affecter les utilisateurs normaux de clients interactifs. Seules les applications clientes qui exécutent des demandes d’API extraordinaires doivent être affectées. Ces limites aident à fournir un niveau de protection contre les pics aléatoires et inattendus en matière de demandes qui menacent la disponibilité et les caractéristiques de performance de la plateforme Microsoft Dataverse.

Lorsqu’une application cliente fait des demandes extrêmement exigeantes, Dataverse suit le modèle commun pour les services en ligne. Nous retournons une erreur indiquant que trop de demandes ont été faites.

Avec l’API Web, nous retournons une erreur 429 Trop de demandes.
Avec le kit de développement logiciel (SDK) pour .NET Dataverse, vous obtiendrez une erreur OrganizationServiceFault avec l’un des trois codes d’erreur spécifiques. Plus d’information : Erreurs de limites de l’API de protection des services retournées

Impact sur les applications clientes

Il incombe aux applications clientes de gérer les erreurs de limite de l’API de protection des services. La façon exacte de gérer cette erreur dépend de la nature de l’application.

Applications clientes interactives

Les limites de protection des services sont suffisamment élevées pour qu’il soit rare qu’une personne utilisant une application cliente interactive les rencontre lors d’une utilisation normale. Cependant, c’est possible si l’application cliente autorise des opérations en bloc. Les développeurs d’applications clientes doivent être conscients de la façon dont les limites de l’API de protection des services sont appliquées et concevoir l’interface utilisateur pour réduire le potentiel des utilisateurs à envoyer des demandes extrêmement exigeantes au serveur. Mais ils doivent toujours s’attendre à ce que des erreurs de limite d’API de protection des services puissent se produire et être prêts à les gérer.

Les développeurs d’applications clientes ne doivent pas simplement envoyer l’erreur pour afficher le message à l’utilisateur. Le message d’erreur n’est pas destiné aux utilisateurs finaux. Voir Réessayer les opérations pour des stratégies spécifiques.

Applications d’intégration de données

Les applications conçues pour charger des données dans Dataverse ou effectuer des mises à jour groupées doivent également être en mesure de gérer les erreurs de limite de l’API de protection de service. Ces applications priorisent le débit afin de pouvoir terminer leur travail en un minimum de temps. Ces applications doivent avoir une stratégie pour réessayer les opérations. Il existe plusieurs stratégies qu’elles peuvent appliquer pour obtenir le débit maximal. Plus d’information : Comment optimiser le débit.

Applications du portail

Les applications de portail envoient généralement des demandes d’utilisateurs anonymes via un compte principal de service. Étant donné que les limites de l’API de protection des services sont basées sur chaque utilisateur, les applications de portail peuvent atteindre les limites de l’API de protection des services en fonction de la quantité de trafic rencontrée par le portail. Comme les applications clientes interactives, il n’est pas prévu que les erreurs de limites de l’API de protection des services soient affichées pour l’utilisateur final du portail. Il est prévu que l’interface utilisateur désactive toute demande supplémentaire et affiche un message indiquant que le serveur est occupé. Le message peut inclure l’heure à laquelle l’application peut commencer à accepter de nouvelles demandes.

Impact sur les plug-ins et les activités de workflow personnalisées

Les plug-ins et les activités de workflow personnalisées appliquent la logique métier déclenchée par les demandes entrantes. Les limites de protection des services ne sont pas appliquées aux plug-ins et aux activités de workflow personnalisées. Les plug-ins et les activités de workflow personnalisées sont chargés et exécutés dans le service bac à sable isolé. Les opérations Dataverse appelées sur le service bac à sable n’utilisent pas les points de terminaison d’API publics.

Si votre application effectue des opérations qui déclenchent une logique personnalisée, le nombre de demandes envoyées par des plug-ins ou des activités de workflow personnalisées ne sera pas pris en compte dans les limites de l’API de protection des services. Cependant, le temps de calcul supplémentaire que ces opérations entraînent sera ajouté à la requête initiale qui les a déclenchées. Ce temps de calcul fait partie des limites de l’API de protection du service. Plus d’information : Comment les limites de l’API de protection des services sont appliquées

Réessayer les opérations

Lorsqu’une erreur de limite d’API de protection des services se produit, elle fournit une valeur indiquant la durée avant que toute nouvelle demande de l’utilisateur puisse être traitée.

Lorsqu’une erreur 429 est renvoyée par l’API Web, la réponse inclut un Retry-After avec nombre de secondes.
Avec le kit de développement logiciel (SDK) pour .NET, une valeur TimeSpan est renvoyée dans la collection OrganizationServiceFault.ErrorDetails avec la clé Retry-After.

La durée de la nouvelle tentative

La durée de Retry-After dépendra de la nature des opérations envoyées au cours des 5 minutes précédentes. Plus les demandes sont exigeantes, plus il faudra de temps au serveur pour récupérer.

Aujourd’hui, en raison de la façon dont les limites sont évaluées, vous pouvez vous attendre à dépasser le nombre de demandes et les délais d’exécution pendant une période de 5 minutes avant que les limites de l’API de protection des services ne prennent effet. Cependant, le dépassement du nombre de demandes simultanées renvoie immédiatement une erreur. Si l’application continue d’envoyer de telles demandes exigeantes, la durée sera prolongée pour minimiser l’impact sur les ressources partagées. Cela entraînera une prolongation de la période de nouvelle tentative individuelle, ce qui signifie que votre application verra des périodes d’inactivité plus longues pendant qu’elle attend. Ce comportement peut changer à l’avenir.

Si possible, nous vous recommandons d’essayer d’atteindre un taux cohérent en commençant par un nombre inférieur de demandes et en augmentant progressivement jusqu’à ce que vous commenciez à atteindre les limites de l’API de protection des services. Après cela, laissez le serveur vous indiquer le nombre de demandes qu’il peut gérer dans un délai de 5 minutes. Garder votre nombre maximal de demandes limité pendant cette période de 5 minutes et augmenter progressivement maintiendra la durée de nouvelle tentative faible, optimisant votre débit total et minimisant les pics de ressources du serveur.

Nouvelle tentative de l’application interactive

Si le client est une application interactive, vous devez afficher un message indiquant que le serveur est occupé pendant que vous réessayez la demande de l’utilisateur. Vous souhaiterez peut-être proposer à l’utilisateur d’annuler l’opération. N’autorisez pas les utilisateurs à soumettre d’autres demandes tant que la précédente demande que vous avez envoyée n’est pas terminée.

Nouvelle tentative de l’application non interactive

Si le client n’est pas interactif, la pratique courante consiste simplement à attendre la fin de la durée avant d’envoyer à nouveau la demande. Cela se fait généralement en suspendant l’exécution de la tâche actuelle avec Task.Delay ou des méthodes équivalentes.

Comment réessayer

La section suivante décrit comment réessayer des applications .NET à l’aide du kit de développement logiciel (SDK) pour .NET Dataverse ou de l’API web :

SDK pour .NET
API web

Si vous utilisez le kit de développement logiciel (SDK) pour .NET, il est recommandé d’utiliser Microsoft.Xrm.Tooling.Connector.CrmServiceClient ou les classes ServiceClient. Ces classes implémentent les méthodes IOrganizationService et peuvent gérer toutes les erreurs de limite d’API de protection de service qui sont renvoyées.

Depuis la version 9.0.2.16 de Xrm.Tooling.Connector, il suspendra et renverra automatiquement la demande après la période de réessai.

Si votre application utilise actuellement les classes Microsoft.Xrm.Sdk.Client.OrganizationServiceProxy ou Microsoft.Xrm.Sdk.WebServiceClient.OrganizationWebProxyClient de niveau inférieur. Vous devriez pouvoir les remplacer par la classe CrmServiceClient ou ServiceClient. OrganizationServiceProxy est déconseillé.

Pour plus d′informations :

Si vous utilisez l’API Web avec une bibliothèque cliente, vous pouvez constater qu’elle prend en charge le comportement de nouvelle tentative attendu pour les erreurs 429. Vérifiez auprès de l’éditeur de la bibliothèque cliente.

Si vous avez écrit votre propre bibliothèque, vous pouvez inclure des comportements similaires à celui inclus dans cet exemple de code pour un assistant Bibliothèque de classe WebAPIService (C#).

/// <summary>
/// Specifies the Retry policies
/// </summary>
/// <param name="config">Configuration data for the service</param>
/// <returns></returns>
static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy(Config config)
{
    return HttpPolicyExtensions
      .HandleTransientHttpError()
      .OrResult(httpResponseMessage => httpResponseMessage.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
      .WaitAndRetryAsync(
         retryCount: config.MaxRetries,
         sleepDurationProvider: (count, response, context) =>
         {
            int seconds;
            HttpResponseHeaders headers = response.Result.Headers;

            if (headers.Contains("Retry-After"))
            {
               seconds = int.Parse(headers.GetValues("Retry-After").FirstOrDefault());
            }
            else
            {
               seconds = (int)Math.Pow(2, count);
            }
            return TimeSpan.FromSeconds(seconds);
         },
         onRetryAsync: (_, _, _, _) => { return Task.CompletedTask; }
      );
}

Cet exemple utilise Polly, une bibliothèque de résilience .NET et de gestion des erreurs transitoires qui permet aux développeurs d’exprimer des stratégies telles que Réessayer, Disjoncteur, Délai d’expiration, Isolement de cloison et Secours d’une manière fluide et sans thread.

En-têtes de réponse HTTP

Si vous utilisez des demandes HTTP avec l’API web, vous pouvez suivre les valeurs limites restantes avec les en-têtes de réponse HTTP suivants :

En-tête	Description de la valeur
`x-ms-ratelimit-burst-remaining-xrm-requests`	Le nombre restant de demandes pour cette connexion
`x-ms-ratelimit-time-remaining-xrm-requests`	La durée combinée restante pour toutes les connexions utilisant le même compte d’utilisateur

Vous ne devez pas dépendre de ces valeurs pour contrôler le nombre de demandes que vous envoyez. Elles sont destinées à des fins de débogage. Si vous supprimez le cookie d’affinité, ces valeurs sont réinitialisées lorsque vous vous connectez à un autre serveur.

Comment les limites de l’API de protection des services sont appliquées

Deux des limites de l’API de protection de service sont évaluées dans une période glissante de 5 minutes (300 secondes). Si l’une ou l’autre des limites est dépassée dans les 300 secondes précédentes, une erreur de limite d’API de protection de service sera renvoyée sur les demandes suivantes pour protéger le service jusqu’à la fin de la durée de nouvelle tentative.

Les limites de l’API de protection des services sont évaluées par utilisateur. Chaque utilisateur authentifié est limité de manière individuelle. Seuls les comptes d’utilisateurs qui font des demandes extraordinaires seront limités. Les autres utilisateurs ne seront pas concernés.

Les limites de l’API de protection des services sont appliquées en fonction de trois facettes :

Le nombre de requêtes envoyées par un utilisateur.
Le temps d’exécution combiné nécessaire pour traiter les requêtes envoyées par un utilisateur.
Le nombre de requêtes simultanées envoyées par un utilisateur.

Si la seule limite était le nombre de requêtes envoyées par un utilisateur, il serait possible de la contourner. Les autres facettes ont été ajoutées pour contrer ces tentatives. Par exemple :

Vous pouvez envoyer moins de demandes en les regroupant en opérations par lots.
- Le délai d’exécution combiné va contrer cela.
Plutôt que d’envoyer des demandes individuellement les unes après les autres, vous pouvez envoyer un grand nombre de demandes simultanées avant que les limites de l’API de protection de service ne soient appliquées.
- La limite de demandes simultanées va contrer cela.

Chaque serveur Web disponible pour votre environnement appliquera ces limites indépendamment. La plupart des environnements auront plus d’un serveur Web. Les environnements d’évaluation ne sont affectés qu’à un seul serveur Web. Le nombre réel de serveurs Web disponibles pour votre environnement dépend de plusieurs facteurs qui font partie du service géré que nous fournissons. L’un des facteurs est le nombre de licences utilisateur que vous avez achetées.

Le tableau suivant décrit les limites de l’API de protection de service par défaut appliquées par serveur Web :

Mesure	Description	Limite par serveur web
Nombre de demandes	Nombre cumulé de demandes effectuées par l’utilisateur.	6000 dans la période glissante de 5 minutes
Délai d’exécution	Temps d’exécution combiné de toutes les demandes faites par l’utilisateur.	20 minutes (1200 secondes) dans la période glissante de 5 minutes
Nombre de demandes simultanées	Nombre de demandes simultanées effectuées par l’utilisateur	52 ou version ultérieure

Important

Ces limites sont sujettes à changement et peuvent varier entre différents environnements. Ces chiffres représentent des valeurs par défaut et sont fournis pour vous donner une idée des valeurs auxquelles vous pouvez vous attendre.

Erreurs de limites de l’API de protection des services retournées

Cette section décrit les trois types d’erreurs limites de l’API de protection des services qui peuvent être renvoyées ainsi que les facteurs qui provoquent ces erreurs et les stratégies d’atténuation possibles.

Le Code d’erreur est la valeur d’erreur numérique renvoyée par le kit de développement logiciel (SDK) pour .NET OrganizationServiceFault.ErrorDetails.
Le Code hexadécimal est la valeur d’erreur hexadécimale renvoyée par l’API Web.

Nombre de demandes

Cette limite compte le nombre total de demandes au cours des 300 secondes précédentes.

Code d’erreur	Code hexadécimal	Message
`-2147015902`	`0x80072322`	`Number of requests exceeded the limit of 6000 over time window of 300 seconds.`

Il n’est pas prévu qu’un utilisateur type d’une application interactive puisse envoyer 1 200 demandes par minute pour dépasser cette limite, à moins que l’application ne permette aux utilisateurs d’effectuer des opérations en masse.

Par exemple, si une vue de liste permet la sélection de 250 enregistrements à la fois et permet à un utilisateur d’effectuer une opération sur tous ces enregistrements, l’utilisateur devra effectuer cette opération 24 fois sur une période de 300 secondes. L’utilisateur devra terminer l’opération sur chaque liste dans les 12,5 secondes.

Si votre application fournit cette fonctionnalité, vous devez envisager certaines des stratégies suivantes :

Diminuer le nombre total d’enregistrements pouvant être sélectionnés dans une liste. Si le nombre d’éléments affichés dans une liste est réduit à 50, l’utilisateur devra effectuer cette opération 120 fois en 300 secondes. L’utilisateur devra terminer l’opération sur chaque liste dans les 2,5 secondes.
Combinez les opérations sélectionnées dans un lot. Un lot peut contenir jusqu’à 1000 opérations et évitera la limite du nombre de demandes. Cependant, vous devrez vous préparer au délai d’exécution.

Délai d’exécution

Cette limite suit le temps d’exécution combiné des demandes entrantes au cours des 300 secondes précédentes.

Code d’erreur	Code hexadécimal	Message
`-2147015903`	`0x80072321`	`Combined execution time of incoming requests exceeded limit of 1,200,000 milliseconds over time window of 300 seconds. Decrease number of concurrent requests or reduce the duration of requests and try again later.`

Certaines opérations nécessitent plus de ressources que d’autres. Les opérations par lots, l’importation de solutions et les requêtes très complexes peuvent être très exigeantes. Ces opérations peuvent également être effectuées simultanément dans des requêtes simultanées. Par conséquent, dans la fenêtre de 5 minutes, il est possible de demander des opérations qui nécessiteront plus de 20 minutes de temps de calcul combiné.

Cette limite peut être rencontrée lorsque des stratégies utilisant des opérations par lots et des demandes simultanées sont utilisées pour éviter la limite du nombre de demandes.

Demandes simultanées

Cette limite fait le suivi du nombre de demandes simultanées.

Code d’erreur	Code hexadécimal	Message
`-2147015898`	`0x80072326`	`Number of concurrent requests exceeded the limit of 52.`

Les demandes des clients ne se limitent pas à l’envoi de demandes individuelles successivement. Le client peut appliquer des modèles de programmation parallèles ou diverses méthodes pour envoyer plusieurs demandes simultanément. Le serveur peut détecter quand il répond simultanément à plusieurs demandes du même utilisateur. Si ce nombre de demandes simultanées est dépassé, cette erreur sera levée. La limite peut être supérieure à 52 dans certains cas.

L’envoi de demandes simultanées peut être un élément clé d’une stratégie pour maximiser le débit, mais il est important de le garder sous contrôle. Lors de l’utilisation de la Programmation parallèle dans .NET, le degré de parallélisme par défaut dépend du nombre de cœurs de processeur sur le serveur exécutant le code. Il ne doit pas dépasser la limite. La propriété ParallelOptions.MaxDegreeOfParallelism peut être définie pour définir un nombre maximum de tâches simultanées.

Plus d’informations : Envoyer des demandes parallèles

Comment maximiser le débit

Lorsque vous avez une application qui doit prioriser le débit pour déplacer le plus de données dans la période la plus courte, vous pouvez appliquer certaines stratégies.

Laissez le serveur vous dire combien il peut gérer

N’essayez pas de calculer le nombre de demandes à envoyer à la fois. Chaque environnement peut être différent. Augmentez progressivement le taux d’envoi des demandes jusqu’à ce que vous commenciez à atteindre les limites, puis dépendez de la valeur de limite de l’API de protection des services Retry-After pour vous dire quand envoyer plus. Cette valeur maintiendra votre débit total au plus haut niveau possible.

Utiliser plusieurs threads

La limite supérieure du nombre de threads simultanés est quelque chose que votre application peut utiliser pour améliorer considérablement les performances. Cela est vrai si vos opérations individuelles sont relativement rapides. Selon la nature des données que vous traitez, vous devrez peut-être ajuster le nombre de threads pour obtenir un débit optimal. Plus d’informations : Envoyer des demandes parallèles

Éviter les gros lots

Le Traitement par lots fait référence à l’envoi de plusieurs opérations dans une seule requête.

La plupart des scénarios envoient le plus rapidement des requêtes uniques avec un degré élevé de parallélisme. Si vous pensez que la taille du lot peut améliorer les performances, il est préférable de commencer avec une petite taille de lot de 10 et d’augmenter la concurrence jusqu’à ce que vous commenciez à obtenir des erreurs de limite d’API de protection des services que vous réessayerez.

Avec le SDK pour .NET, cela signifie utiliser ExecuteMultipleRequest, qui permet généralement d’envoyer jusqu’à 1000 opérations dans une requête. Principal avantage : réduire la quantité totale de charge utile XML qui doit être envoyée via le câble. Cela offre des avantages en termes de performances lorsque la latence du réseau est un problème. Pour les limites de protection de service, cela augmente le temps d’exécution total par requête. Les lots de plus grande taille augmentent le risque de rencontrer des limites de temps d’exécution plutôt que des limites sur le nombre de demandes.

Avant, les opérations ExecuteMultiple étaient limitées à seulement 2 à la fois en raison de l’impact sur les performances que cela pourrait avoir. Ce n’est plus le cas, car les limites du temps d’exécution de la protection du service API ont rendu cette limite redondante.

Lorsque vous utilisez l’API Web, la plus petite charge utile JSON envoyée sur le câble pour les demandes individuelles signifie que la latence du réseau n’est pas un problème. Pour plus d’informations : Exécuter des opérations par lots à l’aide de l’API Web

Notes

Les opérations par lots ne sont pas une stratégie valide pour contourner les limites de droits. Les limites des droits et les limites de l’API de protection des services sont évaluées séparément. Les limites de droits sont basées sur les opérations CRUD et s’accumulent, qu’elles soient incluses ou non dans une opération par lots. Plus d’informations : Limites des droits

Stratégies pour gérer les limites de l’API de protection des services

Cette section décrit les façons dont vous pouvez concevoir vos clients et systèmes pour éviter les erreurs de limite de l’API de protection des services. Vous voudrez peut-être également réfléchir à la façon dont vous gérez vos licences pour réduire l’impact.

Mettre à jour votre application cliente

Les limites de l’API de protection des services sont appliquées à Dataverse depuis 2018, mais de nombreuses applications clientes ont été écrites avant que ces limites n’existent. Ces clients ne s’attendaient pas à ces erreurs et ne peuvent pas gérer les erreurs correctement. Vous devez mettre à jour ces applications et appliquer les modèles aux opérations de nouvelle tentative décrites ci-dessus.

Vers une intégration en temps réel

N’oubliez pas que les principales limites de l’API de protection des points de service consistent à atténuer l’impact des demandes très exigeantes se produisant sur une courte période. Si vos processus métier actuels dépendent de gros travaux périodiques nocturnes, hebdomadaires ou mensuels qui tentent de traiter de grandes quantités de données dans un court laps de temps, réfléchissez à la manière d’activer une stratégie d’intégration de données en temps réel. Si vous pouvez vous éloigner des processus qui nécessitent des opérations très exigeantes, vous pouvez réduire l’impact des limites de protection des services.

Questions fréquentes

Cette section comprend les questions fréquemment posées. Si vous avez des questions sans réponse, publiez-les en utilisant le bouton Commentaires en bas de cette page pour envoyer des commentaires sur cette page.

J’utilise une application ETL sous licence. Comment obtenir un débit optimal ?

Travaillez avec le fournisseur d’application ETL pour savoir quels paramètres appliquer. Assurez-vous que vous utilisez une version du produit qui prend en charge le comportement Réessayer après.

Ces limites s’appliquent-elles à la recherche Dataverse ?

Non La recherche native Dataverse est une API différente (api/search plutôt que api/data) et a des règles différentes. Lors de l’utilisation de l’API de recherche Dataverse, une seule requête par seconde est possible pour chaque utilisateur.

Plus d’informations : Limites de protection de service de recherche Dataverse

Comment ces limites s’appliquent-elles au nombre de demandes auxquelles un utilisateur a droit chaque jour ?

Ces limites ne sont pas liées aux limites de droits. Plus d’informations : Limites des droits

Les limites sont-elles appliquées différemment pour les utilisateurs de l’application ?

Non. Les limites s’appliquent à tous les utilisateurs de la même manière.

Voir aussi

Administrer Power Platform / Gestion des licences et des licences / Demande de limites et d’allocations
Présentation des limites d’API Dataverse
Utilisation de l’API web Dataverse
Utiliser le SDK Dataverse pour .NET