Skip to main content

Ratenbegrenzungen und Knotengrenzwerte für die GraphQL-API

Die Graph-API von GitHub hat einige Einschränkungen zum Schutz vor übermäßigen oder missbräuchlichen Aufrufen von GitHub-Servern.

Knotenlimit

Um die Schemaüberprüfung zu bestehen, müssen alle GraphQL-API-Aufrufe folgende Standards erfüllen:

  • Clients müssen ein Argument first oder last für eine beliebige Verbindung angeben.
  • Werte von first und last müssen innerhalb von 1-100 liegen.
  • Einzelne Aufrufe können nicht mehr als 500.000 Knoten insgesamt anfordern.

Berechnen von Knoten in einem Aufruf

In diesen beiden Beispielen wird gezeigt, wie die Knoten insgesamt in einem Aufruf berechnet werden.

  1. Einfache Abfrage:

    query {
      viewer {
        repositories(first: 50) {
          edges {
            repository:node {
              name
    
              issues(first: 10) {
                totalCount
                edges {
                  node {
                    title
                    bodyHTML
                  }
                }
              }
            }
          }
        }
      }
    }

    Berechnung:

    50         = 50 repositories
     +
    50 x 10  = 500 repository issues
    
                = 550 total nodes
  2. Komplexe Abfrage:

    query {
      viewer {
        repositories(first: 50) {
          edges {
            repository:node {
              name
    
              pullRequests(first: 20) {
                edges {
                  pullRequest:node {
                    title
    
                    comments(first: 10) {
                      edges {
                        comment:node {
                          bodyHTML
                        }
                      }
                    }
                  }
                }
              }
    
              issues(first: 20) {
                totalCount
                edges {
                  issue:node {
                    title
                    bodyHTML
    
                    comments(first: 10) {
                      edges {
                        comment:node {
                          bodyHTML
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
    
        followers(first: 10) {
          edges {
            follower:node {
              login
            }
          }
        }
      }
    }

    Berechnung:

    50              = 50 repositories
     +
    50 x 20       = 1,000 pullRequests
     +
    50 x 20 x 10 = 10,000 pullRequest comments
     +
    50 x 20       = 1,000 issues
     +
    50 x 20 x 10 = 10,000 issue comments
     +
    10              = 10 followers
    
                     = 22,060 total nodes

Primäre Ratenbegrenzung

Die GraphQL-API weist jeder Abfrage Punkte zu und begrenzt die Punkte, die Sie innerhalb eines bestimmten Zeitraums verwenden können. Dieses Limit trägt dazu bei, Missbrauch und Denial-of-Service-Angriffe zu verhindern, und stellt sicher, dass die API für alle Benutzer*innen verfügbar bleibt.

Die REST-API verfügt auch über eine separate primäre Ratenbegrenzung. Weitere Informationen findest du unter Ratenbegrenzungen für die REST-API.

Im Allgemeinen können Sie Ihre primäre Ratenbegrenzung für die GraphQL-API basierend auf Ihrer Authentifizierungsmethode berechnen.

  • Für Benutzer: 5.000 Punkte pro Stunde und Benutzer. Dazu gehören Anforderungen, die mit einer personal access token getätigt wurden, sowie Anforderungen von einer GitHub App oder OAuth app im Namen eines Benutzers, der die App autorisiert hat. Anforderungen, die im Namen eines Benutzers von einer GitHub App im Besitz einer GitHub App-Organisation gestellt werden, weisen eine höhere Ratenbegrenzung von 10.000 Punkten pro Stunde auf. Ebenso haben Anforderungen, die in Ihrem Auftrag von einer OAuth app durchgeführt werden, die im Besitz einer GitHub Enterprise Cloud-Organisation sind, eine höhere Rate von 10.000 Punkten pro Stunde, wenn Sie Mitglied der GitHub Enterprise Cloud-Organisation sind.
  • Für GitHub App-Installationen, die sich nicht in einer GitHub Enterprise Cloud-Organisation befinden: 5.000 Punkte pro Stunde und Installation. Installationen mit mehr als 20 Repositorys erhalten weitere 50 Punkte pro Stunde für jedes Repository. Installationen in einer Organisation mit mehr als 20 Benutzern erhalten weitere 50 Punkte pro Stunde für jeden Benutzer. Die Ratenbegrenzung darf nicht mehr als 12.500 Punkte pro Stunde betragen. Die Ratenbegrenzung für Benutzerzugriffstoken (im Gegensatz zu Installationszugriffstoken) wird durch die primäre Ratenbegrenzung für Benutzer bestimmt.
  • Für GitHub App-Installationen, die sich in einer GitHub Enterprise Cloud-Organisation befinden: 10.000 Punkte pro Stunde und Installation. Die Ratenbegrenzung für Benutzerzugriffstoken (im Gegensatz zu Installationszugriffstoken) wird durch die primäre Ratenbegrenzung für Benutzer bestimmt.
  • Für OAuth apps: 5.000 Punkte pro Stunde oder 10.000 Punkte pro Stunde, wenn die App im Besitz einer GitHub Enterprise Cloud-Organisation ist. Dies gilt nur, wenn die App ihre Client-ID und den geheimen Clientschlüssel verwendet, um öffentliche Daten anzufordern. Die Ratenbegrenzung für OAuth-Zugriffstoken, die von einer OAuth app generiert wird, wird von der primären Ratenbegrenzung für Benutzer bestimmt.
  • Für GITHUB_TOKEN in GitHub Actions-Workflows: 1.000 Punkte pro Stunde und Repository. Für Anforderungen an Ressourcen, die zu einem Enterprise-Konto auf GitHub.com gehören, beträgt der Grenzwert 15.000 Punkte pro Stunde und Repository.

Sie können den Punktwert einer Abfrage überprüfen oder den erwarteten Punktwert berechnen, wie in den folgenden Abschnitten beschrieben. Die Formel für die Berechnung von Punkten und die Ratenbegrenzung können geändert werden.

Überprüfen des Status Ihrer primären Ratenbegrenzung

Sie können die Kopfzeilen verwenden, die mit jeder Antwort gesendet werden, um den aktuellen Status Ihrer primären Ratenbegrenzung zu ermitteln.

HeadernameBeschreibung
x-ratelimit-limitDie maximale Anzahl von Punkten, die Sie pro Stunde nutzen dürfen.
x-ratelimit-remainingDie Anzahl der Punkte, die im aktuellen Ratenbegrenzungsfenster verbleiben.
x-ratelimit-usedDie Anzahl der Punkte, die Sie im aktuellen Ratenbegrenzungsfenster verwendet haben.
x-ratelimit-resetDie Zeit in Sekunden seit der UTC-Epoche, zu der das aktuelle Ratenbegrenzungsfenster zurückgesetzt wird.
x-ratelimit-resourceDie Ratenbegrenzungsressource, auf die die Anforderung angerechnet wird. Bei GraphQL-Anforderungen ist dies immer graphql.

Sie können auch das rateLimit-Objekt abfragen, um Ihre Ratenbegrenzung zu überprüfen. Wenn möglich, sollten Sie die Antwortheader für die Ratenbegrenzung verwenden, anstatt die API abzurufen, um Ihre Ratenbegrenzung zu überprüfen.

query {
  viewer {
    login
  }
  rateLimit {
    limit
    remaining
    used
    resetAt
  }
}
FeldBeschreibung
limitDie maximale Anzahl von Punkten, die Sie pro Stunde nutzen dürfen.
remainingDie Anzahl der Punkte, die im aktuellen Ratenbegrenzungsfenster verbleiben.
usedDie Anzahl der Punkte, die Sie im aktuellen Ratenbegrenzungsfenster verwendet haben.
resetAtDie Zeit in Sekunden seit der UTC-Epoche, zu der das aktuelle Ratenbegrenzungsfenster zurückgesetzt wird.

Zurückgeben des Punktwerts einer Abfrage

Sie können den Punktwert einer Abfrage zurückgeben, indem Sie das Feld cost auf dem rateLimit-Objekt abfragen:

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

Vorhersagen des Punktwerts einer Abfrage

Sie können auch den Punktwert einer Abfrage grob berechnen, bevor Sie die Abfrage erstellen.

  1. Füge die Anzahl der Anforderungen hinzu, die erforderlich sind, um jede eindeutige Verbindung im Aufruf zu erfüllen. Angenommen, jede Anforderung erreicht die Grenzwerte der Argumente first oder last.
  2. Teilen Sie die Zahl durch 100 und runden Sie das Ergebnis auf die nächste ganze Zahl, um den endgültigen Punktwert zu erhalten. In diesem Schritt werden große Zahlen normalisiert.

Note

Der Mindestpunktwert eines Aufrufs der GraphQL-API lautet 1.

Hier ist eine Beispielabfrage und Bewertungsberechnung:

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Für diese Abfrage sind 5.101 Anforderungen erforderlich:

  • Obwohl 100 Repositorys zurückgeben werden, muss die API einmal eine Verbindung mit dem Konto des Viewers herstellen, um die Liste der Repositorys abzurufen. Daher, Anforderungen für Repositorys = 1
  • Obwohl 50 Issues zurückgegeben werden, muss die API eine Verbindung mit jedem der 100 Repositorys herstellen, um die Liste der Issues abzurufen. Daher, Anforderungen für Issues = 100
  • Obwohl 60 Bezeichnungen zurückgegeben werden, muss die API eine Verbindung mit jedem der insgesamt möglichen 5.000 potenziellen Issues herstellen, um die Liste der Bezeichnungen abzurufen. Daher, Anforderungen für Bezeichnungen = 5.000
  • Gesamt = 5.101

Dividiert durch 100 und gerundet ergibt sich die endgültige Bewertung der Abfrage: 51

Sekundäre Ratenbegrenzungen

Zusätzlich zu den Primärratenbegrenzungen erzwingt GitHub sekundäre Ratenbeschränkungen, um Missbrauch zu verhindern und die API für alle Benutzer verfügbar zu halten.

Wenn Sie folgende Aktionen ausführen, kann es zu einer sekundären Ratenbegrenzung gehen:

  • Zu hohe Anzahl gleichzeitiger Anforderungen. Es sind nicht mehr als 100 gleichzeitige Anforderungen zulässig. Dieser Grenzwert wird für die REST-API und die GraphQL-API freigegeben.
  • Nehmen Sie zu viele Anforderungen an einen einzelnen Endpunkt pro Minute vor. Für REST-API-Endpunkte sind maximal 900 Punkte pro Minute zulässig und für den GraphQL-API-Endpunkt sind maximal 2 000 Punkte pro Minute zulässig. Weitere Informationen zu Punkten finden Sie unter „Berechnen von Punkten für das sekundäre Ratenbegrenzungen“.
  • Nehmen Sie zu viele Anforderungen pro Minute vor. Maximal 90 Sekunden CPU-Zeit pro 60 Sekunden Echtzeit ist zulässig. Es kann nicht mehr als 60 Sekunden dieser CPU-Zeit für die GraphQL-API sein. Sie können die CPU-Zeit grob schätzen, indem Sie die Gesamtantwortzeit für Ihre API-Anforderungen messen.
  • Nehmen Sie zu viele Anforderungen vor, die in kurzer Zeit zu viele Computeressourcen verbrauchen.
  • Erstellen Sie in kurzer Zeit zu viele Inhalte für GitHub. Im Allgemeinen sind nicht mehr als 80 Anforderungen zum Generieren von Inhalten pro Minute und maximal 500 Anforderungen zur Inhaltsgenerierung pro Stunde zulässig. Einige Endpunkte weisen niedrigere Grenzwerte für die Inhaltserstellung auf. Zu den Grenzwerten für die Inhaltserstellung gehören Aktionen, die auf der GitHub-Webschnittstelle sowie über die REST-API und die GraphQL-API ausgeführt werden.

Diese Sekundärratenbegrenzungen können ohne Vorherige Ankündigung geändert werden. Es kann auch sein, dass Sie aus unbekannten Gründen auf eine sekundäre Ratenbegrenzung stoßen.

Berechnen von Punkten für die sekundäre Ratenbegrenzung

Einige sekundäre Ratenbegrenzungen werden durch die Punktwerte der Anforderungen bestimmt. Bei GraphQL-Anforderungen sind diese Punktwerte getrennt von den Punktwertberechnungen für die primäre Ratenbegrenzung.

AnfordernPunkte
GraphQL-Anforderungen ohne Mutationen1
GraphQL-Anforderungen mit Mutationen5
Die meisten REST-API GET-, HEAD- und OPTIONS-Anforderungen1
Die meisten POST-, PATCH-, PUT- oder DELETE-Anforderungen über die REST-API5

Einige REST-API-Endpunkte haben einen anderen Kostenpunkt, der nicht öffentlich freigegeben wird.

Überschreiten der Ratenbegrenzung

Wenn Sie die primäre Ratenbegrenzung überschreiten, lautet der Antwortstatus weiterhin 200, aber Sie erhalten eine Fehlermeldung, und der Wert der x-ratelimit-remaining-Kopfzeile lautet 0. Sie sollten die Anforderung erst nach Ablauf der im x-ratelimit-reset-Header angegebenen Zeit wiederholen.

Wenn Sie eine sekundäre Ratenbegrenzung überschreiten, lautet der Antwortstatus 200 oder 403, und Sie erhalten eine Fehlermeldung, die angibt, dass Sie die sekundäre Ratenbegrenzung überschritten haben. Wenn der Antwortheader retry-after vorhanden ist, solltest du deine Anforderung erst nach Ablauf dieser Sekundenzahl erneut übermitteln. Wenn der x-ratelimit-remaining-Header 0 lautet, solltest du die Anforderung erst nach Ablauf der im x-ratelimit-reset-Header angegebenen UTC-Epochensekunden erneut senden. Warte andernfalls mindestens eine Minute, bevor du den Vorgang wiederholst. Wenn Ihre Anforderung aufgrund einer sekundären Ratenbegrenzung weiterhin fehlschlägt, warten Sie auf eine exponentiell steigende Zeitspanne zwischen Wiederholungen, und lösen Sie nach einer bestimmten Anzahl von Wiederholungen einen Fehler aus.

Wenn Sie weiterhin Anfragen stellen, während die Ratenbegrenzung eingeschränkt ist, kann dies zu einer Sperrung Ihrer Integration führen.

Unterhalb der Ratenbegrenzung bleiben

Um die Überschreitung einer Ratenbegrenzung zu vermeiden, sollten Sie mindestens 1 Sekunde zwischen mutativen Anforderungen pausieren und gleichzeitige Anforderungen vermeiden.

Abonnieren Sie auch Webhookereignisse, anstatt die API nach Daten abzufragen. Weitere Informationen findest du unter Webhooks-Dokumentation.

Sie können das Überwachungsprotokoll auch streamen, um API-Anforderungen anzuzeigen. Dies kann Ihnen bei der Problembehandlung bei Integrationen helfen, die die Ratenbegrenzung überschreiten. Weitere Informationen findest du unter Streamen des Überwachungsprotokolls für ein Unternehmen.