Limites de l’API de protection des services

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

Ces limites ne doivent pas affecter les utilisateurs normaux des clients interactifs. Seules les applications clientes qui effectuent un volume extraordinaire de demandes d’API doivent être affectées. Ces limites offrent un niveau de protection contre les augmentations aléatoires et inattendues des volumes de demandes qui menacent la disponibilité et les caractéristiques de performances de la plateforme Microsoft Dataverse.

Lorsqu’une application cliente effectue des demandes extraordinairement exigeantes, Dataverse suit le modèle commun pour les services en ligne. Nous renvoyons une erreur indiquant que trop de demandes ont été reçues.

• Avec l’API web, nous renvoyons une erreur 429 Trop de requêtes .
• Avec le Kit de développement logiciel (SDK) Dataverse pour .NET, vous obtenez une erreur OrganizationServiceFault avec l’un des trois codes d’erreur spécifiques.

En savoir plus sur les erreurs de limite d’API de protection du service retournées

Impact sur les applications clientes

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

Applications clientes interactives

Les limites de protection du service sont suffisamment élevées pour qu'il soit rare qu'une personne utilisant une application cliente interactive les rencontre au cours d'une utilisation normale. Toutefois, il est possible lorsque l’application cliente autorise les opérations en bloc. Les développeurs d’applications clientes doivent savoir comment les limites des API de protection des services sont appliquées et concevoir l’interface utilisateur afin de réduire le risque pour les utilisateurs d’envoyer des demandes extrêmement exigeantes au serveur. Même lorsqu’ils le font, ils doivent toujours s’attendre à ce que les erreurs de limite d’API de protection de service puissent se produire et être prêtes à les gérer.

Les développeurs d’applications clientes ne doivent pas simplement lever l’erreur pour afficher le message à l’utilisateur. Le message d’erreur n’est pas destiné aux utilisateurs finaux. En savoir plus sur des stratégies spécifiques pour réessayer des opérations

Applications d’intégration de données

Les applications conçues pour charger des données dans Dataverse ou effectuer des mises à jour en bloc doivent gérer les erreurs de limite d’API de protection des services. Ces applications hiérarchisent le débit afin qu’elles puissent effectuer leur travail dans la durée minimale. Ces applications doivent avoir une stratégie pour réessayer les opérations. Il existe plusieurs stratégies qu’ils peuvent appliquer pour obtenir le débit maximal. Découvrez comment optimiser le débit

Applications de 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 du service sont basées sur une base utilisateur, les applications portail peuvent atteindre les limites de l’API de protection du service en fonction de la quantité de trafic que le portail rencontre. Comme les applications clientes interactives, n'affichez pas à l'utilisateur final du portail les erreurs liées aux limites d'API de protection de services. L’interface utilisateur du portail doit désactiver d’autres demandes et afficher un message indiquant que le serveur est occupé. Le message peut inclure l'heure à laquelle l'application peut commencer à accepter de nouvelles demandes, calculées à l'aide de la durée de « Retry-After » retournée avec l'erreur.

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

Les plug-ins et les activités de flux de travail personnalisées appliquent la logique métier déclenchée par les requêtes entrantes. Les limites de protection des services ne sont pas appliquées aux opérations de données provenant de plug-ins et d’activités de flux de travail personnalisées. Les plug-ins et les activités de workflow personnalisées sont téléchargés et exécutés dans le service isolé de sandbox. Les opérations Dataverse appelées sur le service de 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 flux de travail personnalisées ne sera pas comptabilisé dans les limites de l’API de protection du service. Toutefois, le temps de calcul supplémentaire que ces opérations contribuent est ajouté à la requête initiale qui les a déclenchées. Cette durée de calcul fait partie des limites de l’API de protection des services. Découvrez comment les limites des API de protection des services sont appliquées

Réessayer les opérations

Lorsqu’une erreur de limite d’API de protection de service se produit, elle fournit une valeur indiquant la durée avant que les nouvelles demandes de l’utilisateur puissent être traitées.

• Lorsqu’une erreur 429 est retournée à partir de l’API web, la réponse inclut un en-tête Retry-After avec le nombre de secondes.
• Avec le Kit de développement logiciel (SDK) pour .NET, une valeur TimeSpan est retournée dans la OrganizationServiceFaultcollection .ErrorDetails avec la clé Retry-After.

La durée de la nouvelle tentative

La Retry-After durée dépend de la nature des opérations envoyées au cours de la période précédente de 5 minutes. Plus les demandes sont exigeantes, plus il faut 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 limites de temps d’exécution pendant une période de 5 minutes avant que les limites de l’API de protection du service prennent effet. Toutefois, le dépassement du nombre de requêtes simultanées retourne immédiatement une erreur. Si l’application continue d’envoyer de telles demandes exigeantes, la durée est étendue pour réduire 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.

Dans la mesure du possible, nous vous recommandons d’essayer d’atteindre un taux cohérent en commençant par un nombre inférieur de requêtes et en augmentant progressivement jusqu’à ce que vous commencez à atteindre les limites de l’API de protection du service. Après cela, laissez le serveur vous indiquer le nombre de demandes qu’il peut gérer dans un délai de 5 minutes. Limiter votre nombre maximal de demandes au cours de cette période de 5 minutes, puis l'augmenter progressivement, permet de maintenir la durée de nouvelle tentative à un niveau bas, optimisant ainsi votre débit total et minimisant les pics de ressources du serveur.

Nouvelle tentative d’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 effectuée par l’utilisateur. Vous pouvez fournir une option permettant à l’utilisateur d’annuler l’opération. N’autorisez pas les utilisateurs à envoyer plus de demandes tant que la demande précédente que vous avez envoyée n’est pas terminée.

Nouvelle tentative d’application non interactive

Si le client n’est pas interactif, la pratique courante consiste simplement à attendre que la durée soit passée avant d’envoyer à nouveau la demande. Cela est généralement effectué en interrompant l’exécution de la tâche actuelle à l’aide de Task.Delay ou de méthodes équivalentes.

Comment réessayer

Voici comment réessayer des applications .NET à l’aide du Kit de développement logiciel (SDK) Dataverse pour .NET ou l’API web :

/// <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; }
      );
}

Mise en œuvre des limites de l’API de protection de service

Deux des limites de l’API de protection du service sont évaluées dans une fenêtre 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 du service sont évaluées par utilisateur. Chaque utilisateur authentifié est limité indépendamment. Seuls les comptes d’utilisateurs qui font des demandes extraordinaires sont limités. Les autres utilisateurs ne seront pas affectés.

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

• Nombre de demandes envoyées par un utilisateur.
• Temps d’exécution combiné nécessaire pour traiter les demandes envoyées par un utilisateur.
• Nombre de demandes simultanées envoyées par un utilisateur.

Si la seule limite était le nombre de demandes 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 dans les opérations de traitement par lots.
  • La limite combinée du temps d'exécution contrebalance cela.
• Au lieu d’envoyer des demandes individuellement par succession, vous pouvez envoyer un grand nombre de demandes simultanées avant que les limites de l’API de protection du service soient appliquées.
  • La limite de demandes simultanées va contrer cela.

Chaque serveur web disponible pour votre environnement applique ces limites indépendamment. La plupart des environnements ont plusieurs serveurs web. Les environnements d’évaluation ne sont alloué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 managé Fourni par Dataverse. L’un des facteurs est le nombre de licences utilisateur que vous avez achetées.

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

Erreurs de dépassement de limite de l’API de protection des services retournées

Cette section décrit les trois types d’erreurs de limite d’API de protection des services qui peuvent être retourné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 retournée par le Kit de développement logiciel (SDK) pour .NETOrganizationServiceFault.ErrorDetails.
• Le code hexadécimal est la valeur d’erreur hexadécimale retournée par l’API web.

Nombre de demandes

Cette limite compte le nombre total de requêtes au cours de la période précédente de 300 secondes.

Il n’est pas prévu qu’un utilisateur classique d’une application interactive puisse envoyer 1 200 requêtes par minute pour dépasser cette limite, sauf si l’application permet aux utilisateurs d’effectuer des opérations en bloc.

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

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

• Réduction du 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 doit effectuer cette opération 120 fois dans les 300 secondes. L’utilisateur doit effectuer l’opération sur chaque liste dans un délai de 2,5 secondes.
• Combinez les opérations sélectionnées dans un lot. Un lot peut contenir jusqu’à 1 000 opérations et éviter le nombre de demandes limitées. Toutefois, vous devez être préparé pour la limite de temps d’exécution.

Temps d’exécution

Cette limite suit le temps d’exécution combiné des requêtes entrantes pendant la période précédente de 300 secondes.

Certaines opérations nécessitent plus de ressources que d’autres. Les opérations batch, l’importation de solutions et les requêtes hautement complexes peuvent être très exigeantes. Ces opérations peuvent également être effectuées simultanément dans les requêtes simultanées. Par conséquent, dans la fenêtre de 5 minutes, il est possible de demander des opérations nécessitant 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 requêtes simultanées sont utilisées pour éviter le nombre de demandes limitées.

Demandes simultanées

Cette limite suit le nombre de requêtes simultanées.

Les applications clientes ne sont pas limitées à l’envoi séquentiel de requêtes individuelles. Le client peut appliquer des modèles de programmation parallèles ou différentes méthodes pour envoyer plusieurs requêtes simultanément. Le serveur peut détecter lorsqu’il répond à plusieurs requêtes du même utilisateur simultanément. Si ce nombre de requêtes simultanées est dépassé, cette erreur est levée. La limite peut être supérieure à 52 dans certains cas.

L’envoi de requêtes simultanées peut être une partie clé d’une stratégie pour optimiser le débit, mais il est important de le garder sous contrôle. Lorsque vous utilisez la programmation parallèle dans .NET , le degré de parallélisme par défaut dépend du nombre de cœurs d’UC 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 maximal de tâches simultanées.

En savoir plus sur l’envoi de requêtes parallèles

Comment optimiser le débit

Lorsque vous avez une application qui doit maximiser le débit pour déplacer le maximum de données dans le plus court laps de temps, il existe certaines stratégies que vous pouvez appliquer.

Laissez le serveur vous indiquer 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 commencez à atteindre des limites, puis dépendez de la valeur limite Retry-After de l’API de protection du service pour vous indiquer quand envoyer plus. Cette valeur conserve votre débit total au niveau le plus élevé 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. En savoir plus sur l’envoi de requêtes en parallèle

Éviter les lots volumineux

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

Dans la plupart des scénarios, l'envoi de requêtes uniques avec un degré élevé de parallélisme est plus rapide. Si vous pensez que la taille du lot peut améliorer les performances, il est préférable de commencer par une petite taille de lot de 10 et d’augmenter la concurrence jusqu’à ce que vous commencez à obtenir des erreurs de limite d’API de protection du service que vous réessayez.

Avec le SDK pour .NET, cela signifie utiliser ExecuteMultipleRequest, ce qui permet généralement d’envoyer jusqu’à 1 000 opérations dans une requête. L’avantage principal est qu’il réduit la quantité totale de charge utile XML qui doit être envoyée sur le câble. Cela offre un avantage en matière de performances lorsque la latence du réseau est un problème. Pour les limites de protection du service, il augmente le temps d’exécution total par requête. Les lots de taille supérieure augmentent la probabilité que vous rencontriez des limites de temps d’exécution plutôt que des limites sur le nombre de requêtes.

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

Lorsque vous utilisez l’API web, la charge utile JSON plus petite envoyée sur le câble pour les requêtes individuelles signifie que la latence réseau n’est pas un problème. En savoir plus sur l’exécution d’opérations par lots à l’aide de l’API web

Stratégies de gestion des limites de l’API Service Protection

Cette section décrit les façons dont vous pouvez concevoir vos clients et systèmes pour éviter les erreurs de limite d’API de protection des services. Vous pouvez également envisager 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 ont été appliquées à Dataverse depuis 2018, mais il existe de nombreuses applications clientes écrites avant que ces limites n’existaient. Ces clients ne s’attendaient pas à ces erreurs et ne peuvent pas gérer correctement les erreurs. Vous devez mettre à jour ces applications et appliquer les modèles aux opérations de nouvelle tentative décrites précédemment.

Passer à l’intégration en temps réel

N’oubliez pas que le point principal des limites de l’API de protection des services consiste à atténuer l’impact des demandes très exigeantes sur une courte période. Si vos processus métier actuels dépendent de travaux périodiques volumineux, hebdomadaires ou mensuels qui tentent de traiter de grandes quantités de données dans une courte période, réfléchissez à la façon dont vous pouvez activer une stratégie d’intégration des données en temps réel. Si vous pouvez vous éloigner des processus nécessitant des opérations très exigeantes, vous pouvez réduire l'impact que les limites de protection des services ont.

Questions fréquemment posées

Cette section comprend des questions fréquemment posées. Si vous avez des questions qui ne sont pas répondues, publiez-les à l’aide du bouton Commentaires en bas de cette page pour envoyer des commentaires sur cette page.

J’utilise une application ETL que j’ai concédée sous licence. Comment obtenir un débit optimal ?

Collaborez avec le fournisseur d’applications ETL pour savoir quels paramètres appliquer. Vérifiez que vous utilisez une version du produit qui prend en charge le comportement Retry-After.

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. Lorsque vous utilisez l’API de recherche Dataverse, il existe une limite de limitation d’une requête par seconde pour chaque utilisateur.

En savoir plus sur les limites de protection du service de recherche de données

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

Ces limites ne sont pas liées aux limites de droits d’utilisation. En savoir plus sur les limites de droits d’utilisation

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

Non. Les limites sont appliquées à tous les utilisateurs de la même façon.

Voir aussi

Administrer Power Platform / Licences et gestion des licences / Limites et répartition des quotas de demandes
Vue d’ensemble des limites de l’API Dataverse
Utiliser l’API web Dataverse
Utiliser le Kit de développement logiciel (SDK) Dataverse pour .NET