Testez la façon dont votre application gère les limites de débit d’API GitHub

Tip

Vous découvrez la limitation du débit ? Découvrez ce qu’est la limitation du débit et comment la gérer.

En un clin d’œil
Objectif : Testez la façon dont votre application gère les limites de débit d’API REST GitHub
Heure : 15 minutes
Plugins :RateLimitingPlugin, GenericRandomErrorPlugin, RetryAfterPlugin
Prérequis :configurer le proxy de développement

Votre application appelle l’API GitHub. Il fonctionne sur votre ordinateur, puis un travail CI, une grande organisation ou une journée chargée le fait dépasser la limite de débit, et il commence à échouer. Pour le tester sur l’API réelle, vous devrez épuiser votre limite de requêtes, puis attendre jusqu’à une heure avant de pouvoir réessayer. Le proxy de développement simule les limites de débit de GitHub localement, avec une limite et une fenêtre de temps que vous choisissez.

Savoir ce que GitHub retourne

GitHub comporte 2 types de limites de débit pour l’API REST.

Les limites de débit primaires limitent le nombre de demandes que vous effectuez par heure. Par exemple, 60 pour les requêtes non authentifiées et 5 000 pour les requêtes avec un jeton d’accès personnel. Chaque réponse inclut des en-têtes qui indiquent où vous êtes :

Header Meaning
x-ratelimit-limit Nombre maximal de requêtes par heure
x-ratelimit-remaining Nombre de requêtes laissées dans la fenêtre en cours
x-ratelimit-reset Heure à laquelle la fenêtre est réinitialisée, en secondes d’époque UTC

Lorsque vous dépassez la limite principale, GitHub retourne 403 ou 429 avec x-ratelimit-remaining défini sur 0. Ne réessayez pas tant que l’heure indiquée dans x-ratelimit-reset n’est pas atteinte.

Les limites de taux secondaires protègent GitHub contre les pics d’activité, comme un trop grand nombre de requêtes simultanées ou la création de trop de contenu trop rapidement. Lorsque vous en dépassez un, GitHub retourne 403 ou 429 avec un message sur une limite de débit secondaire. Si la réponse a un en-tête retry-after, attendez ce nombre de secondes. Sinon, attendez au moins une minute et augmentez le temps d’attente si la requête échoue.

GitHub pouvez interdire les intégrations qui continuent d'envoyer des demandes pendant qu'elles sont limitées. Pour plus d’informations, consultez Les limites de débit pour l’API REST dans la documentation GitHub.

Simuler la limite de débit primaire

Utilisez RateLimitingPlugin pour compter les requêtes et retourner les en-têtes de limite de débit de GitHub. Pour tester sans attendre une heure, utilisez une petite limite et une courte fenêtre.

Fichier : devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "RateLimitingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.schema.json",
    "headerLimit": "x-ratelimit-limit",
    "headerRemaining": "x-ratelimit-remaining",
    "headerReset": "x-ratelimit-reset",
    "resetFormat": "UtcEpochSeconds",
    "costPerRequest": 1,
    "rateLimit": 5,
    "resetTimeWindowSeconds": 60,
    "warningThresholdPercent": 0,
    "whenLimitExceeded": "Custom",
    "customResponseFile": "github-rate-limit-exceeded.json"
  }
}

Caution

Ajoutez le RetryAfterPlugin avant le RateLimitingPlugin dans votre fichier de configuration. Si vous l’ajoutez après, les RateLimitingPlugin handles de la demande avant de pouvoir la RetryAfterPlugin vérifier.

Dans le fichier de réponse personnalisé, définissez la réponse que GitHub retourne lorsque vous dépassez la limite de débit primaire.

Fichier : github-rate-limit-exceeded.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.customresponsefile.schema.json",
  "statusCode": 429,
  "headers": [
    {
      "name": "content-type",
      "value": "application/json; charset=utf-8"
    }
  ],
  "body": {
    "message": "API rate limit exceeded for user ID 1.",
    "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api"
  }
}

Démarrez le proxy de développement et exécutez votre application.

devproxy --config-file devproxyrc.json

Le proxy de développement transfère les 5 premières requêtes de chaque minute à GitHub et définit les en-têtes x-ratelimit-* sur les réponses. À partir de la 6e requête, le proxy de développement retourne la réponse de limite de débit avec x-ratelimit-remaining défini sur 0 et x-ratelimit-reset défini sur la fin de la fenêtre. Si votre application appelle à nouveau l’API avant la réinitialisation de la fenêtre, elle RetryAfterPlugin le signale et limite la requête.

Vérifiez que votre application :

  • Lit x-ratelimit-remaining et ralentit avant d’atteindre 0.
  • Arrête d’appeler l’API après une réponse de limite de débit et attend jusqu’à x-ratelimit-reset.
  • Indique à l'utilisateur ce qui se passe, par exemple « GitHub limite de débit atteinte, réessayer à 14:05 », au lieu d’échouer silencieusement.

Note

GitHub retourne soit 403 ou 429 lorsque vous dépassez une limite de débit. Pour tester que votre application gère 403 également, passez statusCode à 403. Le RetryAfterPlugin suit uniquement les réponses 429, donc il ne signale pas les nouvelles tentatives précoces après un 403.

Tip

Le proxy de développement transfère les requêtes vers GitHub jusqu’à ce que la limite simulée soit atteinte. Ces demandes sont également décomptées de votre limite de débit GitHub réelle.

Simuler des limites de taux secondaires

Les limites de taux secondaires surviennent par rafales et incluent un en-tête retry-after. Utilisez GenericRandomErrorPlugin pour les retourner au hasard.

Fichier : devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "GenericRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubSecondaryRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubSecondaryRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.schema.json",
    "errorsFile": "github-secondary-rate-limit.json",
    "rate": 50,
    "retryAfterInSeconds": 60
  }
}

Fichier : github-secondary-rate-limit.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.errorsfile.schema.json",
  "errors": [
    {
      "request": {
        "url": "https://api.github.com/*"
      },
      "responses": [
        {
          "statusCode": 429,
          "headers": [
            {
              "name": "content-type",
              "value": "application/json; charset=utf-8"
            },
            {
              "name": "retry-after",
              "value": "@dynamic"
            }
          ],
          "body": {
            "message": "You have exceeded a secondary rate limit. Please wait a few minutes before you try again.",
            "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits"
          }
        }
      ]
    }
  ]
}

Démarrez le proxy de développement et exécutez votre application. Vérifiez que votre application attend le nombre de secondes indiqué dans l’en-tête retry-after avant d’appeler à nouveau l’API. Si ce n’est pas le cas, le RetryAfterPlugin le signale.

Si vous utilisez Octokit avec le plugin de limitation du débit, vérifiez que vos gestionnaires onSecondaryRateLimit et onRateLimit s’exécutent et qu’ils renvoient le résultat attendu.

Étape suivante

Découvrez plus en détail l’RateLimitingPlugin.

RateLimitingPlugin

Voir aussi

  • Dernière mise à jour :