GraphQL

Eine GraphQL-Anfrage enthält eine Abfrage, ihre Variablen und das Schema, gegen das sie geschrieben ist. Echolot nutzt das Schema, um Felder beim Tippen zu vervollständigen, Fehler vor dem Senden zu markieren und die Typen neben der Antwort zu zeigen.

GraphQL-Anfrage erstellenCopy Anchor Link

Wähle Datei › Neue GraphQL-Anfrage oder Neue GraphQL-Anfrage im Menü + neben Anfragen in der Seitenleiste. Tippe den Endpunkt ins Adressfeld: für den Demo-Shop {{baseURL}}/graphql. Der Alpenglow-Arbeitsbereich hat eine fertige: Catalog › Search products.

Der Editor hat diese Tabs: Doku, Abfrage, Variablen, Header, Parameter, Auth, Variablen (die eigenen Variablen der Anfrage), Tests, Skripte und Einstellungen. Header, Auth, Tests und Skripte funktionieren wie bei HTTP-Anfragen.

Abfrage und VariablenCopy Anchor Link

Schreibe die Abfrage im Tab Abfrage:

query SearchProducts($text: String!, $first: Int = 10) {
  search(text: $text, first: $first) {
    totalCount
    nodes { sku name price { amount currency } rating stock { warehouse available } }
  }
}

und ihre Variablen als JSON im Tab Variablen. {{variables}} funktionieren im JSON:

{
  "text": "{{searchTerm}}"
}

Enthält das Dokument mehrere Operationen, tippe die zu sendende in Operation über der Abfrage. Lass das Feld leer bei einem Dokument mit einer Operation.

Sende mit Senden oder ⌘R.

Wie die Anfrage gesendet wirdCopy Anchor Link

Das Badge GQL vor der Adresse ist ein Menü. Unter Senden als:

Zwei Schalter darunter:

• Persisted Queries (APQ) sendet zuerst den SHA-256-Hash der Abfrage ohne die Abfrage. Antwortet der Server, dass er den Hash nicht kennt, sendet Echolot erneut mit der Abfrage, damit der Server sie behalten kann.
• Alle Operationen bündeln sendet alle benannten Operationen des Dokuments zusammen als ein JSON-Array.

Das SchemaCopy Anchor Link

Das Schemamenü sitzt rechts im Tab Abfrage. Es zeigt die Schemadatei und die Zahl ihrer Typen, etwa shop.graphql · … types, oder Kein Schema.

• Vom Server abrufen führt die Introspection-Abfrage gegen die Adresse der Anfrage aus und behält das Ergebnis als Datei im Ordner specs/ des Arbeitsbereichs. Wähle es erneut, um das Schema zu aktualisieren.
• Schema verwenden listet die Schemadateien auf, die schon im Arbeitsbereich liegen (.graphql, .graphqls und .json), zur Auswahl.
• Schemadatei hinzufügen … nimmt eine SDL-Datei (.graphql) oder ein Introspection-Ergebnis (.json) von deinem Mac.
• Schema-Explorer zeigen öffnet das Schema neben der Antwort.
• Dieses Schema nicht mehr verwenden nimmt das Schema von der Anfrage.

Eine Schemadatei in specs/ kann von jeder GraphQL-Anfrage gegen diesen Server geteilt und mit dem Arbeitsbereich committet werden. Ersetzt ein Abruf eine Schemadatei und hat sich das Schema geändert, listet Das Schema hat sich geändert die Änderungen als Inkompatibel, Riskant und Sicher auf, etwa ein entferntes Feld oder ein neues Pflichtargument. Inkompatible Änderungen sind die, bei denen Abfragen scheitern, die das Entfernte oder Geänderte nutzen. In der Befehlszeile vergleicht echolot graphql diff zwei Schemas auf dieselbe Weise: siehe echolot graphql.

Lässt sich das Schema nicht lesen, zeigt das Menü Schemaproblem, und die Leiste unter der Abfrage sagt warum.

Vervollständigung, Probleme und HoverCopy Anchor Link

Mit einem Schema hilft dir der Abfrageeditor beim Tippen:

• Vervollständigung bietet Felder, Argumente, Eingabefelder, Typen, Enum-Werte, Variablen, Direktiven und Fragmente an, die an die Stelle des Cursors passen, mit ihrer Dokumentation. Veraltete sind markiert.
• Probleme werden beim Tippen unterstrichen: unbekannte Felder, falsche Argumenttypen, fehlende Pflichtargumente und mehr. Die Leiste unter der Abfrage zeigt das erste und zählt die Fehler und Warnungen; zeige darauf, um alle zu lesen.
• Hover: Halte den Zeiger auf ein Feld oder einen Typ, um die Signatur und Dokumentation zu sehen und ob es veraltet ist.
• ⌘-Klick auf ein Feld oder einen Typ öffnet dessen Typ im Schema-Explorer.

Der Schema-Explorer und der BuilderCopy Anchor Link

Der Tab Schema des Antwortbereichs zeigt das Schema der Anfrage, auch vor dem ersten Senden. Hat die Anfrage noch kein Schema, wähle dort Vom Server abrufen.

Erkunden beginnt bei den Einstiegspunkten (Query, Mutation und Subscription). Klicke auf einen Typ, um seine Felder, Eingabefelder, Enum-Werte oder die Typen zu sehen, die ihn implementieren oder zu ihm gehören, veraltete Teile markiert. „Zurück“ führt zum vorherigen Typ. Typen und Felder suchen findet alles im Schema nach Namen.

Erstellen schreibt die Abfrage für dich. Wähle unter Operation Abfrage, mutation oder subscription und hake dann Felder im Baum an: Jedes Häkchen fügt das Feld dem Abfragetext hinzu, und Abhaken nimmt es wieder heraus. Was du drumherum getippt hast, bleibt. Der Builder arbeitet an der in Operation genannten Operation oder an der ersten Operation dieser Art im Dokument; gibt es keine, legt er eine an.

AntwortenCopy Anchor Link

Die Antwort erscheint im Tab Body als JSON, wie jede Antwort. Echolot liest außerdem, was GraphQL neben den Daten sagt:

• N GraphQL-Fehler in der Zusammenfassung der Antwort: Der Server hat ein errors-Array gesendet, auch bei HTTP 200. Klicke darauf, um jede Meldung und den zugehörigen Pfad zu lesen.
• Teildaten: Daten kamen zusammen mit Fehlern zurück, sodass einige Felder null sind, weil sie fehlgeschlagen sind.
• Erweiterungen: die extensions der Antwort, etwa Tracing- oder Kosteninformationen.

Füge im Tab Tests eine Prüfung GraphQL-Fehler mit dem Wert 0 hinzu, damit ein Durchlauf bei ihnen fehlschlägt. Siehe Skripte und Tests.

Subscriptions und inkrementelle AuslieferungCopy Anchor Link

Eine Subscription sendet Ergebnisse, bis sie endet:

• Über HTTP (POST oder GET) fordert Echolot Server-Sent Events an, wenn die Operation eine Subscription ist.
• Über WebSocket (graphql-transport-ws) öffnet Echolot den WebSocket, sendet die Subscription mit den Headern und der Auth der Anfrage und beantwortet die Pings des Servers.

Eine Abfrage mit @defer oder @stream kommt in Teilen zurück (multipart/mixed).

In beiden Fällen bekommt der Antwortbereich einen Tab Ereignisse: jedes Ereignis oder jeder Teil der Reihe nach, nummeriert, mit seiner Art (etwa next oder part), seiner ID und seinen Fehlern. Bei @defer und @stream zeigt Zusammengeführtes Ergebnis oben das erste Ergebnis mit allen späteren Teilen angewendet. Der Tab folgt neuen Ereignissen, solange der Stream läuft, mit Empfang läuft … „Stoppen“ beendet ihn. Wähle Abbrechen (⌘.), um ihn zu beenden. Ein begonnener Stream wird nicht durch die Gesamt-Zeitüberschreitung der Anfrage abgeschnitten.

Datei-UploadsCopy Anchor Link

Für eine Mutation mit einer Upload-Variablen fügst du die Datei im Tab Variablen unter Dateien für Variablen hinzu:

1. Wähle +.
2. Tippe die Variable, etwa file, oder files.0 für das erste Element einer Liste.
3. Tippe den Pfad der Datei, relativ zum Arbeitsbereich.

Der POST folgt dann der GraphQL-Multipart-Request-Spec: Die Variable ist in operations null, und die Datei kommt in einen eigenen Teil.