Informationen zur Paginierung
Die GraphQL-API von GitHub beschränkt die Anzahl der Elemente, die Sie in einer einzigen Anforderung abrufen können, um vor übermäßigen oder missbräuchlichen Anforderungen an GitHub-Server zu schützen. Wenn Sie die GraphQL-API verwenden, müssen Sie für jede Verbindung ein first- oder ein last-Argument angeben. Der Wert dieser Argumente muss zwischen 1 und 100 liegen. Die GraphQL-API gibt die Anzahl der Verbindungen zurück, die durch das first- oder das last-Argument angegeben wurden.
Wenn die Daten, auf die Sie zugreifen, über mehr Verbindungen als die Anzahl der durch das first- oder last-Argument angegebenen Elemente verfügen, wird die Antwort in kleinere „Seiten“ der angegebenen Größe unterteilt. Diese Seiten können jeweils einzeln abgerufen werden, bis der gesamte Datensatz abgerufen wurde. Jede Seite enthält die Anzahl der durch das first- oder last-Argument angegebenen Elemente, es sei denn, sie ist die letzte Seite, die eine niedrigere Anzahl von Elementen enthalten kann.
In diesem Leitfaden wird veranschaulicht, wie du zusätzliche Ergebnisseiten für paginierte Antworten anforderst, die Anzahl der auf jeder Seite zurückgegebenen Ergebnisse änderst und ein Skript schreibst, um mehrere Ergebnisseiten abzurufen.
Anfordern einer cursor in Ihrer Abfrage
Bei Verwendung der GraphQL-API verwenden Sie Cursor, um ein paginiertes Dataset zu durchlaufen. Der Cursor stellt eine bestimmte Position im Dataset dar. Sie können den ersten und letzten Cursor auf einer Seite abrufen, indem Sie das pageInfo-Objekt abfragen. Zum Beispiel:
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 100, after: null) {
nodes {
createdAt
number
title
}
pageInfo {
endCursor
startCursor
hasNextPage
hasPreviousPage
}
}
}
}
In diesem Beispiel gibt pageInfo.startCursor den Cursor für das erste Element auf der Seite an. pageInfo.endCursor gibt den Cursor für das letzte Element auf der Seite an. pageInfo.hasNextPage und pageInfo.hasPreviousPage geben an, ob vor und nach der zurückgegebenen Seite eine Seite vorhanden ist.
Ändern der Anzahl der Elemente pro Seite
Die Argumente first und last steuern, wie viele Elemente zurückgegeben werden. Die maximale Anzahl von Elementen, die Sie mit dem Argument first oder last abrufen können, beträgt 100. Möglicherweise müssen Sie weniger als 100 Elemente anfordern, wenn Ihre Abfrage viele Daten berührt, um zu vermeiden, dass ein Raten- oder Knotenlimit erreicht wird. Weitere Informationen findest du unter Ratenbegrenzungen und Knotengrenzwerte für die GraphQL-API.
Durchlaufen des Datasets mithilfe der Paginierung
Nachdem Sie einen Cursor aus einer Abfrage zurückgegeben haben, können Sie den Cursor verwenden, um die nächste Ergebnisseite anzufordern. Dazu verwenden Sie das Argument after oder before und den Cursor.
Angenommen, der pageInfo.endCursor-Wert aus dem vorherigen Beispiel lautete Y3Vyc29yOnYyOpHOUH8B7g==. Sie können nun diese Abfrage verwenden, um die nächste Ergebnisseite anzufordern:
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
nodes {
createdAt
number
title
}
pageInfo {
endCursor
hasNextPage
hasPreviousPage
}
}
}
}
Sie können weiterhin Abfragen mit dem neuen pageInfo.endCursor-Wert senden, der in der Antwort zurückgegeben wird, bis keine zu durchlaufenden Seiten mehr vorhanden sind, die durch pageInfo.hasNextPage angegeben sind und false zurückgeben.
Wenn Sie das last-Argument anstelle des first-Arguments angegeben haben, wird die letzte Seite der Ergebnisse zuerst zurückgegeben. In diesem Fall verwenden Sie den pageInfo.startCursor-Wert und das before-Argument, um die vorherige Ergebnisseite abzurufen. Sobald pageInfo.hasPreviousPage false zurückgibt, haben Sie die letzte Seite erreicht. Beispiel:
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
nodes {
createdAt
number
title
}
pageInfo {
startCursor
hasPreviousPage
}
}
}
}
Nächste Schritte
Sie können das Octokit-SDK von GitHub und das octokit/plugin-paginate-graphql-Plug-In verwenden, um die Paginierung in Ihren Skripts zu unterstützen. Weitere Informationen finden Sie unter „plugin-paginate-graphql.js“.