Einführung in GraphQL

GraphQL-Terminologie

Die GitHub GraphQL-API stellt eine architektonische und konzeptionelle Umstellung 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 die vollständige Menge möglicher Daten (Objekte, Felder, Beziehungen, alles), auf die ein Client zugreifen kann. Aufrufe vom Client werden überprüft und gegen 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

Ein Feld ist eine Dateneinheit, die du aus einem 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 Auswahlen bis hin zu den Feldern spezifizieren, die skalare Werte zurückgeben, um eine eindeutig strukturierte 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 ist eine Menge von Schlüssel-Wert-Paaren, die einem bestimmten Feld zugeordnet sind. Einige Felder erfordern ein Argument. Mutations erfordern ein Eingabeobjekt als Argument.

Implementierung

Im GraphQL-Schema kann der Begriff implements verwendet werden, 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 können Sie mit nur einem einzelnen GraphQL-Aufruf dasselbe erreichen, wofür in der REST-API mehrere Aufrufe benötigt werden. Weitere Informationen finden Sie unter Migrieren von REST zu GraphQL.

Es ist hilfreich, sich ein Diagramm vorzustellen: Punkte, die durch Linien verbunden sind. Die Punkte sind Knoten, die Linien sind Kanten. Eine Verbindung definiert eine Beziehung zwischen Knoten.

Edge

Kanten stellen Verbindungen zwischen Knoten dar. Wenn eine Verbindung abgefragt wird, durchläuft man ihre Kanten, um die Knoten zu erreichen. Jedes edges-Feld verfügt über ein node-Feld und ein cursor-Feld. Cursor werden für die Pagination verwendet. Weitere Informationen finden Sie unter Verwenden der Paginierung in der GraphQL-API.

Knoten

          _Knoten_ ist ein allgemeiner Begriff für ein Objekt. Sie können entweder direkt einen Knoten nachschlagen oder auf verwandte Knoten über eine Verbindung zugreifen. Wenn du einen `node` angibst, dass keinen [Skalar](/graphql/reference/scalars) zurückgibt, musst du Unterfelder einschließen, bis alle Felder Skalare zurückgeben. Informationen zum Zugriff auf Knoten-IDs über die REST-API und deren Verwendung in GraphQL-Abfragen finden Sie unter [AUTOTITLE](/graphql/guides/using-global-node-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
      }
    }
  }
}

Führen Sie eine Abfrage von __type durch, 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" oder 401 Unauthorized erhältst, solltest du überprüfen, ob du ein gültiges Token verwendest. Wenn der 403-Fehler mit der Meldung Resource not accessible by personal access token angezeigt, stelle sicher, dass fine-grained personal access token auf den richtigen Ressourcenbesitzer abzielt. Sie muss sich beispielsweise an die Organisation richten, die das Repository besitzt, auf das Sie zugreifen möchten.

Es wird empfohlen, die Ergebnisse, die in JSON vorliegen, für einfacheres Lesen und Suchen schön zu formatieren. Sie können ein Befehlszeilentool wie jq verwenden oder die Ergebnisse zu diesem Zweck in python -m json.tool umstellen.

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 Inhalt übergibst, ist die GraphQL-Anforderungsmethode POST, unabhängig davon, ob es sich um eine Abfrage oder eine Mutation handelt.

Weitere Informationen zum Ausführen von Abfragen finden Sie unter Erstellen von Aufrufen mit GraphQL.

In diesem Artikel