GraphQL verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Die GraphQL-Richtlinie kann die Nutzlasten von GraphQL-Anfragen in Variablen für den Nachrichtenablauf parsen, die Anfrage mit einem GraphQL-Schema vergleichen oder beides.

Die GraphQL-Richtlinie kann GraphQL-Nutzlasten in Nachrichtenablaufvariablen parsen, GraphQL-Anfragen anhand eines Schemas prüfen oder beides.

Sie können die GraphQL-Richtlinie für Folgendes verwenden:

• Achten Sie darauf, dass Ihre APIs nur Anfragen verarbeiten, die dem von Ihnen bereitgestellten Schema entsprechen.
• Sie können Einschränkungen für die Nutzlast festlegen, indem Sie eine maximal zulässige Anzahl für Fragmente festlegen.
• Verknüpfen Sie GraphQL mit API-Produkten.
• Nutzen Sie die Features der Oauth2-, VerifyAPIKey- und Kontingentrichtlinien wie bei REST.

GraphQL unterstützt die folgenden Nutzlasttypen:

• POST von graphQL-Nutzlasten mit Content-Type : application/graphql
• POST von graphQL-Nutzlasten mit Content-Type: applcation/json
• GET von graphQL-Nutzlasten, bei denen die Nutzlast ein Abfrageparameter ist

Hinweis: Für application/json-Nutzlasten der Form

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee ignoriert derzeit die optionalen Felder operationName und variables.

Eine kurze Zusammenfassung der Optionen für die GraphQL-Richtlinie finden Sie unten im Abschnitt GraphQL-Optionen.

Weitere Informationen zu GraphQL finden Sie auf GraphQL.org.

Beispiel

Das folgende Beispiel zeigt, wie Sie ein GraphQL-Schema in Apigee hochladen und es zur Überprüfung von Anfragen mit GraphQL-Inhalten verwenden.

Achtung: Das Prüfen der Nutzlast im Schema ist in der Regel ein teurer Vorgang. Wir empfehlen daher eine sorgfältige Schemavalidierung. Schemavalidierungsvorgänge können CPU-intensiv sein, insbesondere wenn die Nutzlast und das Schema komplex sind und zu erheblichen Latenzen führen.

Hinweis: Sie können nur ein Schema pro Richtlinie angeben. Wenn Sie mehrere Schemas einbeziehen müssen, fügen Sie Ihrem Proxy mehrere GraphQL-Richtlinien hinzu.

Hinweise: Nur für den klassischen Proxy-Editor:

• Sie können eine GraphQL-Schemadatei nur hochladen, wenn Sie eine GraphQL-Richtlinie hinzufügen. Sie können sie nicht im Bereich Ressourcen im Proxy-Editor hochladen.
• Nachdem Sie eine GraphQL-Schemadatei hochgeladen haben, können Sie sie nicht im Proxy-Editor aufrufen oder bearbeiten.

Diese Einschränkungen gelten nicht für den neuen Proxy-Editor.

Schemadatei erstellen

Erstellen Sie zum Ausführen des Beispiels zuerst eine GraphQL-Schemadatei mit folgendem Inhalt:

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

Speichern Sie die Datei mit dem gewünschten Namen, gefolgt von der Erweiterung .graphql.

GraphQL-Richtlinie in der Apigee-Benutzeroberfläche hinzufügen

Hinweis: Apigee wird zukünftig eine neue Version des Proxy-Editors bereitstellen, die die Verwaltung von Proxys vereinfachen wird.

In den Anleitungen auf den ersten beiden Tabs unten wird erläutert, wie Sie entweder den neuen Proxy-Editor oder den klassischen Proxy-Editor verwenden.

Neuer Proxy-Editor

Erstellen Sie zuerst die GraphQL-Richtlinie:

1. Melden Sie sich bei der Apigee-UI an.
2. Wählen Sie in der Navigationsleiste Entwickeln > API Proxies aus.
3. Wählen Sie in der Liste der Proxys den API-Proxy aus, für den Sie die GraphQL-Richtlinie verwenden möchten.
4. Klicken Sie auf den Tab ENTWICKELN.
5. Klicken Sie im linken Bereich neben dem Ordner Richtlinien auf die Schaltfläche +.

6. Klicken Sie im Dialogfeld Richtlinie erstellen in das Feld Richtlinientyp wählen, scrollen Sie nach unten zu Mediation und wählen Sie GraphQL.

   

   Geben Sie einen Anzeigenamen und einen Namen ein.

   Wählen Sie als Nächstes eine GraphQL-Schemadatei:

   1. Klicken Sie auf das Feld Schemadatei. Folgende Optionen sind verfügbar:
      • Kein Schema. Wenn Sie diese Option auswählen, verwendet Apigee kein Schema, um Anfragen zu validieren.
      • GraphQL-Schema importieren (.graphql)

   2. Wählen Sie GraphQL-Schema importieren (.graphql) aus. Dadurch wird Folgendes angezeigt:

      

   3. Klicken Sie auf Datei auswählen und wählen Sie die zuvor erstellte Schemadatei aus (die die Erweiterung .graphql haben muss). Die Datei wird im Feld Schemaname angezeigt.

      
7. Klicken Sie auf Erstellen, um die Richtlinie zu erstellen.

Nachdem Sie die Richtlinie GraphQL erstellt haben, können Sie sie an einen Schritt im PreFlow anhängen:

1. Wählen Sie im linken Bereich Proxy-Endpunkte > Standard > PreFlow:

   

2. Klicken Sie auf die Schaltfläche + neben PreFlow im Antwortbereich unten rechts im visuellen Editor:

   

3. Wählen Sie im Dialogfeld Richtlinienschritt hinzufügen die Richtlinie GQL.
   Hinweis: In diesem Beispiel wird der Standardname GQL für die GraphQL-Richtlinie verwendet. Sie können den Namen im Element DisplayName im XML für die Richtlinie durch Hinzufügen einer beschreibenden Wortgruppe nach GQL ändern. Siehe Richtliniennamen ändern.
4. Klicken Sie auf Hinzufügen, um die Richtlinie anzuhängen.
5. Klicken Sie auf Speichern, um die aktuelle Überarbeitung mit Ihren Änderungen zu speichern.
6. Klicken Sie zum Bereitstellen der Änderungen auf den Tab Übersicht und wählen Sie Bereitstellen.

Unter GraphQL-Optionen unten finden Sie die Optionen, die Sie für die GraphQL-Richtlinie festlegen können.

Klassischer Proxy-Editor

1. Melden Sie sich bei der Apigee-UI an.
2. Wählen Sie in der Navigationsleiste Entwickeln > API Proxies aus.
3. Wählen Sie in der Liste der Proxys den API-Proxy aus, für den Sie die GraphQL-Richtlinie verwenden möchten.
4. Klicken Sie auf den Tab ENTWICKELN.

5. Klicken Sie im Bereich Ablauf: PreFlow auf + Schritt.

   

6. Scrollen Sie im Bereich Schritt hinzufügen nach unten zum Abschnitt Vermittlung und wählen Sie GraphQL aus.

   

   Im Bereich Schritt hinzufügen werden die folgenden Optionen angezeigt:

   • Anzeigename: Anzeigename der Richtlinie.
   • Name: Interner Name der Richtlinie.
   • Schemadatei: Option zum Hochladen einer Datei mit einem GraphQL-Schema, das Apigee zur Validierung von Anfragen mit GraphQL-Inhalten verwendet.

   So verwenden Sie ein Schema:

   1. Klicken Sie auf das Feld Schemadatei. Folgende Optionen sind verfügbar:
      • Kein Schema. Wenn Sie diese Option auswählen, verwendet Apigee kein Schema, um Anfragen zu validieren.
      • GraphQL-Schema importieren (.graphql)

   2. Wählen Sie GraphQL-Schema importieren (.graphql) aus. Dadurch wird Folgendes angezeigt:

      

   3. Klicken Sie auf Datei wählen und wählen Sie die zuvor erstellte Schemadatei aus (die die Erweiterung .graphql haben muss). Die Datei wird im Feld Schemaname angezeigt.

      

7. Klicken Sie auf Hinzufügen. Der Bereich Ablauf: PreFlow wird jetzt so angezeigt:

   

   Unter GraphQL-Optionen unten finden Sie die Optionen, die Sie für die GraphQL-Richtlinie festlegen können. Lassen Sie sie in diesem Beispiel unverändert.

8. Klicken Sie zum Bereitstellen des Proxys auf den Tab Übersicht und wählen Sie Bereitstellen.

   

Jetzt können Sie die GraphQL-Richtlinie mit dem folgenden curl-Befehl testen:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

Dabei ist PROXY_BASEPATH der Proxy-Basispfad und HOST_NAME der Name Ihres Proxys, einschließlich der aktuellen Überarbeitungsnummer. Wenn Sie den Befehl ausführen, validiert Apigee die Anfrage anhand des Schemas und gibt die folgende Ausgabe zurück.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

Ein weiteres Beispiel für eine Anfrage:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

Dieses Mal schlägt die Anfragevalidierung mit der folgenden Fehlermeldung fehl.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

GraphQL-Optionen

Die GraphQL-Richtlinie bietet folgende Optionen:

• OperationType: Der Vorgangstyp. Folgende Optionen sind verfügbar:
  • query: Das GraphQL-Äquivalent des REST-GET-Vorgangs.
  • mutation: Das GraphQL-Äquivalent des REST-PUT-Vorgangs.
  • query_mutation: Sowohl query als auch mutation.
• MaxDepth: Die maximale Tiefe der Abfrage, wenn sie als Baum dargestellt wird. Mit MaxDepth können Sie tiefe Abfragen in der Nutzlast blockieren, sodass Apigee keine sehr großen Ablaufvariablen zum Speichern der Werte erstellen muss. Die Nutzlast wird jedoch unverändert gesendet, unabhängig vom Wert von MaxDepth.
• MaxCount: Maximale Anzahl der Fragmente, die in der Nutzlast enthalten sein können. Damit lässt sich verhindern, dass der GraphQL-Back-End-Server des Kunden hochkomplexe Abfragen ausführt. Dadurch werden Clients gezwungen, ihre Logik in kleinere Nutzlasten aufzuteilen.
• Action: Eine der folgenden GraphQL-Aktionen:
  • parseApigee parst die GraphQL-Nutzlast in die Ablaufvariablen. Sie können dann den Inhalt der Ablaufvariablen in Richtlinien wie JavaCallout verwenden. Beachten Sie, dass parse auch die Nutzlast überprüft.
  • verify: Apigee prüft, ob die GraphQL-Nutzlast dem auf den Proxy hochgeladenen Schema entspricht. Sie können verify verwenden, um sicherzustellen, dass Sie keine Anfragen erhalten, die nicht Ihrem Schema entsprechen. Dies kann wertvolle CPU-Zeit im Back-End sparen.
  • parse_verify: Parst und prüft die Nutzlast.
• ResourceURL: Der Pfad zur GraphQL-Schemadatei, mit der Apigee die GraphQL-Anfrage prüft.

Weitere Informationen zu diesen Optionen finden Sie auf der Referenzseite der GraphQL-Richtlinie.