GraphQL-Terminologie
Die GitHub GraphQL-API stellt eine architektonische und konzeptionelle Abkehr von der GitHub-REST-API dar. Du wirst wahrscheinlich einige neue Begriffe in den Referenzdokumenten zur GraphQL-API vorfinden.
Schema
Ein Schema definiert das Typsystem einer GraphQL-API. Es beschreibt den vollständigen Satz möglicher Daten (Objekte, Felder, Beziehungen, alles), auf die ein Client zugreifen kann. Aufrufe vom Client werden überprüft und für das Schema ausgeführt. Ein Client kann über eine Introspektion Informationen zum Schema abrufen. Das Schema befindet sich auf dem GraphQL-API-Server. Weitere Informationen findest du unter Ermitteln der GraphQL-API.
Feld
In Feld ist dies eine Dateneinheit, die du über ein Objekt abrufen kannst. Wie in der offiziellen GraphQL-Dokumentation angegeben ist „die GraphQL-Abfragesprache grundsätzlich für das Auswählen von Feldern in Objekten konzipiert“.
Die offizielle Spezifikation enthält Folgendes über Felder:
Alle GraphQL-Vorgänge müssen ihre Auswahl bis hin zu den Feldern angeben, die Skalare zurückgeben, um eine eindeutig gestaltete Antwort sicherzustellen.
Dies bedeutet, wenn du versuchst, ein Feld zurückzugeben, das kein Skalar ist, wird bei der Schemaüberprüfung ein Fehler ausgelöst. Du musst geschachtelte Unterfelder hinzufügen, bis alle Felder Skalare zurückgeben.
Argument
Ein Argument ein Satz von an ein bestimmtes Feld angefügten Schlüssel-Wert-Paaren. Einige Felder erfordern ein Argument. Mutationen erfordern ein Eingabeobjekt als Argument.
Implementierung
Im GraphQL-Schema wird eventuell der Begriff _ implementiert_ verwendet, um zu definieren, wie ein Objekt von einer Schnittstelle erbt.
Nachfolgend findest du ein Beispiel für ein Schema, das die X
-Schnittstelle und das Y
-Objekt definiert:
interface X {
some_field: String!
other_field: String!
}
type Y implements X {
some_field: String!
other_field: String!
new_field: String!
}
Das bedeutet, dass das Y
-Objekt dieselben Felder/Argumente/Rückgabetypen wie die X
-Schnittstelle erfordert und gleichzeitig neue Felder hinzufügt, die spezifisch für das Y
-Objekt sind. (Das !
bedeutet, dass das Feld erforderlich ist.)
In den Referenzdokumenten findest du Folgendes:
-
Für jedes Objekt sind unter Implementiert die Schnittstellen aufgeführt, von denen es erbt.
-
Für jede Schnittstelle sind unter Implementierungen die Objekte aufgeführt, von denen sie erbt.
Verbindung
Verbindungen stellen eine Möglichkeit dar, zugehörige Objekte als Teil desselben Aufrufs abzufragen. Mit Verbindungen kannst du mit nur einem einzelnen GraphQL-Aufruf dasselbe erreichen, wofür in der REST-API mehrere Aufrufe benötigst. Weitere Informationen findest du unter Migrieren von REST zu GraphQL.
Im einem Diagramm werden Punkte durch Linien miteinander verbunden, um dies zu veranschaulichen. Die Punkte sind Knoten, die Linien sind Kanten. Eine Verbindung definiert eine Beziehung zwischen Knoten.
Edge
Kanten stellen Verbindungen zwischen Knoten dar. Wenn du eine Verbindung abfragst, werden ihre Kanten durchlaufen, um zu den Knoten zu gelangen. Jedes edges
-Feld verfügt über ein node
-Feld und ein cursor
-Feld. Cursor werden für die Pagination verwendet. Weitere Informationen findest du unter Verwenden der Paginierung in der GraphQL-API.
Node
Knoten ist ein allgemeiner Begriff für ein Objekt. Du kannst einen Knoten direkt suchen oder über eine Verbindung auf verwandte Knoten zugreifen. Wenn du einen node
angibst, dass keinen Skalar zurückgibt, musst du Unterfelder einschließen, bis alle Felder Skalare zurückgeben. Informationen zum Zugreifen auf Knoten-IDs über die REST-API und ihre Verwendung in GraphQL-Abfragen findest du unter Verwenden globaler Knoten-IDs.
Entdecken der GraphQL-API
GraphQL ist introspektiv. Dies bedeutet, dass du ein GraphQL-Schema für Details zu sich selbst abfragen kannst.
-
Frage
__schema
ab, um alle Typen aufzulisten, die im Schema definiert sind, und Details zu jedem zu erhalten:query { __schema { types { name kind description fields { name } } } }
-
Frage
__type
ab, um Details zu einem beliebigen Typ abzurufen:query { __type(name: "Repository") { name kind description fields { name } } }
-
Du kannst auch eine Introspektionsabfrage für das Schema über eine
GET
-Anforderung ausführen:curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
Hinweis: Wenn du die Antwort
"message": "Bad credentials"
oder401 Unauthorized
erhältst, solltest du überprüfen, ob du ein gültiges Token verwendest. Wenn der403
-Fehler mit der MeldungResource not accessible by personal access token
angezeigt, stelle sicher, dass fine-grained personal access token auf den richtigen Ressourcenbesitzer abzielt. Es muss beispielsweise auf die Organisation abzielen, die das Repository besitzt, auf das du zugreifen möchtest.Die Ergebnisse werden in JSON angegeben. Es wird daher empfohlen, zum einfacheren Lesen und Suchen eine Quelltextformatierung durchzuführen. Du kannst ein Befehlszeilentool wie jq verwenden oder die Ergebnisse zu diesem Zweck per Pipe an
python -m json.tool
weiterleiten.Alternativ kannst du den Medientyp
idl
übergeben, um die Ergebnisse im IDL-Format zurückzugeben, das eine komprimierte Version des Schemas darstellt:$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \ http(s)://HOSTNAME/api/graphql
Hinweis: Die Introspektionsabfrage ist wahrscheinlich die einzige
GET
-Anforderung, die du in GraphQL ausführst. Wenn du einen Methodenkörper übergibst, ist die GraphQL-AnforderungsmethodePOST
, und zwar unabhängig davon, ob es sich um eine Abfrage oder eine Mutation handelt.Weitere Informationen zum Ausführen von Abfragen findest du unter Erstellen von Aufrufen mit GraphQL.