Hintergrund
Die GitHub GraphQL-API unterstützt derzeit zwei Typen von globalen Knoten-ID-Formaten. Das ältere Format ist schließen und wird durch ein neues Format ersetzt. In diesem Leitfaden wird gezeigt, wie du bei Bedarf zum neuen Format migrierst.
Durch die Migration zum neuen Format stellst du sicher, dass die Reaktionszeiten deiner Anforderungen konsistent und kurz bleiben. Außerdem stellst du sicher, dass deine Anwendung weiterhin funktioniert, sobald die alten IDs schließen sind.
Für weitere Informationen darüber, warum das bisherige globale Knoten-ID-Format schließen abgelöst wird, vgl. Neues globales ID-Format für GraphQL.
Ermitteln, ob du Maßnahmen ergreifen musst
Du musst nur die Migrationsschritte ausführen, wenn du Verweise auf globale GraphQL-Knoten-IDs speicherst. Diese IDs entsprechen dem id-Feld für jedes Objekt im Schema. Wenn du keine globalen Knoten-IDs speicherst, kannst du weiterhin mit der API ohne Änderung interagieren.
Wenn du die Legacy-IDs derzeit decodierst, um Typ-Informationen zu extrahieren (zum Beispiel, wenn du die ersten beiden Zeichen von PR_kwDOAHz1OX4uYAah verwendest, um festzustellen, ob es sich bei dem Objekt um eine Pull Request handelt), wird ihr Dienst abgebrochen, da sich das Format der IDs geändert hat. Du solltest deinen Dienst migrieren, um diese IDs als undurchsichtige Zeichenfolgen zu behandeln. Diese IDs sind eindeutig, daher kannst du dich direkt als Verweise darauf verlassen.
Migrieren zu den neuen globalen IDs
Um die Migration zum neuen ID-Format zu erleichtern, können Sie den Header X-Github-Next-Global-ID in Ihren GraphQL-API-Anforderungen verwenden. Der Wert des Headers X-Github-Next-Global-ID kann 1 oder 0 sein. Wenn du den Wert auf 1 festlegst, wird die Antwortnutzlast immer das neue ID-Format verwenden, für jedes Objekt, für das du das id-Feld angefordert hast. Wenn du den Wert auf 0 setzt, wird das Standardverhalten wiederhergestellt, bei dem abhängig vom Erstellungsdatum des Objekts entweder die Legacy-ID oder die neue ID angezeigt wird.
Es folgt eine Beispielanforderung unter Verwendung eines curl-Befehls:
$ curl \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "X-Github-Next-Global-ID: 1" \
https://api.github.com/graphql \
-d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'
Obwohl die Legacy-ID MDQ6VXNlcjM0MDczMDM= in der Abfrage verwendet wurde, enthält die Antwort das neue ID-Format:
{"data":{"node":{"id":"U_kgDOADP9xw"}}}
Mit dem Header X-Github-Next-Global-ID finden Sie das neue ID-Format für Legacy-IDs, auf die Sie in Ihrer Anwendung verweisen. Anschließend kannst du diese Verweise mit der in der Antwort empfangenen ID aktualisieren. Du solltest alle Verweise auf ältere IDs aktualisieren und das neue ID-Format für alle nachfolgenden Anforderungen an die API verwenden.
Zum Ausführen von Massenvorgängen kannst du Aliase verwenden, um mehrere Knotenabfragen in einem API-Aufruf zu übermitteln. Weitere Informationen findest du in der GraphQL-Dokumentation.
Sie können auch die neue ID für eine Sammlung von Elementen erhalten. Wenn du beispielsweise die neue ID für die letzten 10 Repositorys in deiner Organisation abrufen möchtest, kannst du eine Abfrage wie folgt verwenden:
{
organization(login: "github") {
repositories(last: 10) {
edges {
cursor
node {
name
id
}
}
}
}
}
Beachten Sie, dass sich das Festlegen X-Github-Next-Global-ID auf 1 auf den Rückgabewert jedes felds id in Ihrer Abfrage auswirkt. Dies bedeutet, dass du auch dann, wenn du eine Nicht-node-Abfrage übermittelst, die neue Format-ID zurückerhältst, wenn du das id-Feld angefordert hast.
Feedback teilen
Wenn Sie Bedenken beim Rollout dieser Änderung haben, die sich auf Ihre App auswirken, wenden Sie sich bitte an uns über das GitHub-Support-Portal und fügen Informationen wie Ihren App-Namen hinzu, damit wir Sie besser unterstützen können.