GraphQL-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was

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.

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Einführung in GraphQL
• Abfragen und Mutationen
• Referenz zu Ablaufvariablen

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Nicht alle Nutzer müssen Richtlinien- und Umgebungstypen kennen. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Unter GraphQL verwenden finden Sie ein Beispiel, in dem diese Richtlinie verwendet wird.

Achtung: Die Nutzlast des Schemas zu prüfen, ist in der Regel ein teurer Vorgang. Wir empfehlen Ihnen, dies bei der Entscheidung über eine Schemavalidierung zu berücksichtigen. 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 einschließen müssen, fügen Sie Ihrem Proxy mehrere GraphQL-Richtlinien hinzu.

Element <GraphQL>

Definiert eine <GraphQL>-Richtlinie.

Standardwert	Siehe Standardrichtlinie Tab unten
Erforderlich/Optional?	Erforderlich
Typ	TYP
Übergeordnetes Element	–
Untergeordnete Elemente	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

Syntax

Das <GraphQL>-Element verwendet die folgende Syntax:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

Standardrichtlinie

Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie Ihrem Ablauf in der Apigee-UI eine <GraphQL>-Richtlinie hinzufügen:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut	Standard	Erforderlich?	Beschreibung
name	-	Erforderlich	Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
continueOnError	false	Optional	Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf
enabled	wahr	Optional	Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async	false	Verworfen	Dieses Attribut wurde verworfen.

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <GraphQL>:

Untergeordnetes Element	Erforderlich?	Beschreibung
Häufige Vorgänge
<Action>	Optional	Gibt die Aktion an, die für eine Anfrage ausgeführt werden soll: parse, verify oder parse_verify (beide).
<MaxCount>	Optional	Die maximale Anzahl an Abfragen oder Fragmenten, die eine GraphQL-Anfrage erzeugen kann. Der Standardwert ist 10.
<MaxDepth>	Optional	Die maximale Tiefe des Baums für die Abfrage. Der Standardwert ist 4.
<MaxPayloadSizeInBytes>	Optional	Die maximale Größe einer Nutzlast in Kilobyte.
<OperationType>	Erforderlich	Gibt den Typ der Anfrage an, die geparst werden kann: query, mutation oder query_mutation (entweder).
<ResourceURL>	Optional	BESCHREIBUNG. Der Speicherort der GraphQL-Schemadatei.
<Source>	Erforderlich	request

Jedes dieser untergeordneten Elemente wird in den folgenden Abschnitten beschrieben.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <GraphQL> beschrieben.

<Action>

Die Aktion stellt eine der folgenden GraphQL-Aktionen dar:

• parse: Apigee parst die GraphQL-Nutzlast in Nachrichtenablaufvariablen. Unter Beispiele für Darstellungen von Nachrichtenablaufvariablen finden Sie eine Erläuterung der Variablen, die festgelegt werden, wenn Action auf parse gesetzt ist. Dies kann wertvolle CPU-Zeit im Back-End sparen. Beachten Sie, dass verify auch die Nutzlast parst.
• verify: Apigee prüft, ob die GraphQL-Nutzlast dem auf den Proxy hochgeladenen Schema entspricht.
• parse_verify: Apigee parst und überprüft die GraphQL-Anfrage.

Standardwert	parse
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <Action> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<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.

Standardwert	10
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <MaxCount> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<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. Der Standardwert ist 10.

Hinweis: MaxDepth funktioniert, wenn das Element Action auf parse oder parse-verify gesetzt ist. Es empfiehlt sich, MaxDepth mit diesen Aktionen zu verwenden, um den Detaillierungsgrad zu prüfen und nicht die teurere verify-Aktion zu verwenden.

Standardwert	10
Erforderlich?	Optional
Typ	Integer
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <MaxDepth> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

Die maximale Größe einer Nutzlast in Kilobyte. Damit können Sie die Nutzlastgröße begrenzen, um Leistungsprobleme zu vermeiden.

Hinweis: Wenn MaxPayloadSizeInByte nicht in der Richtlinie angegeben ist, wird keine Größenbeschränkung erzwungen.

Standardwert	request
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <MaxPayloadSizeInBytes> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Gibt den Typ der Anfrage an, die geparst werden kann:

• query: Eine GraphQL-Abfrage
• mutation: Eine GraphQL-Mutation
• query_mutation: Eine GraphQL-Abfrage oder eine Mutation

Wenn der Bereich query lautet und eine Mutationsanfrage übergeben wird, schlägt die Anfrage fehl und gibt den Fehler 4xx zurück.

Standardwert	query
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <OperationType> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

Der Pfad zur GraphQL-Schemadatei, anhand derer die GraphQL-Richtlinie Anfragen überprüft. Ein Beispiel für das Hochladen eines GraphQL-Schemas in Apigee finden Sie unter Beispiel.

Wenn der Name der hochgeladenen Schemadatei my-schema.graphql lautet, lautet das Element <ResourceURL>.

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

Standardwert	–
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element ResourceURL verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Quelle, für die diese Richtlinie ausgeführt wird.

Hinweis: Die Quelle sollte der Abfragestring im Roh-GraphQL und nicht eine in JSON verpackte GraphQL-Abfrage sein.

Standardwert	request
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<GraphQL>
Untergeordnete Elemente	–

Das Element <Source> verwendet die folgende Syntax:

Syntax

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

GraphQL-Parser

Der GraphQL-Parser unterstützt alle Features einer GraphQL-Abfrage und stellt ihn als Diagramm in der mit dem Punkt getrennten Notation des Nachrichtenablaufs dar. Eine Abfrage kann aus der Vorgangsdefinition und optional aus als Fragmentdefinition identifizierten Fragmenten bestehen. Weitere Informationen finden Sie in der GraphQL-Spezifikation.

Anatomie einer GraphQL-Anfrage

Das folgende Diagramm zeigt die Anatomie einer GraphQL-Anfrage.

Darstellung der Vorgangsdefinitionen im Nachrichtenablauf

Die Parser-Implementierung deckt alle Aspekte der GraphQL-Syntax ab, einschließlich Unterstützung für Abfragen und Mutationen. Siehe Nachrichtenablaufvariable.

Die Nachrichtenablaufvariablen folgen dieser Konvention:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

wobei

• graphql: Statisches Präfix, das angibt, dass es sich um GraphQL-bezogene Nachrichtenablaufvariablen handelt
• root-Index: Basisindex, der den Abfragedefinitionsindex auf Stammebene angibt (standardmäßig bis zu 4 pro Anfrage)
• root-definition: Nachrichteninhalt für GraphQL-Anfrage auf Stammebene, Argumente, deren Werte
• sub-indices: Untergeordnete Indexe
• child-definitions: Definitionen auf Blattebene, die sich auf bestimmte Felder und ihre Werte beziehen

Darstellung der Nachrichtenablaufvariable der Vorgangsdefinitionen

Felder in Nachricht	Typ	Beschreibung
name	String	Name des GraphQL-Vorgangs. Dieser Name hat keinen Bezug zum Namen im Nachrichtenablauf.
definition	String – Vorgang	Gibt an, dass dies den Hauptnachrichteninhalt der Abfrageanfrage enthält
operationType	Abfrage oder Mutation	Die Art des durchgeführten Vorgangs
variableDefinition	Integer	Sie funktionieren wie die Argumentdefinitionen für eine Funktion in einer typisierten Sprache. Darin werden alle Variablen mit dem Präfix $, gefolgt vom Typ aufgelistet.
directives	Integer	@include und @skip sind die aktuell angebotenen zwei Anweisungen, die auf der Basis dynamisch weitergegebener Werte filtern können.
selectionSet	Integer	Eine logische Gruppierung aller mit einem Objekt verknüpften Attribute.

Darstellung der Fragmentdefinitionen im Nachrichtenablauf

Name der Nachrichtenablaufvariable	Typ	Beschreibung
name	String	Name des Fragments.
definition	String – Fragment	Gibt an, dass der Text der Anfrage ein Fragment der Hauptanfrage ist.
typeCondition	String	Die Bedingung, unter der das Fragment aufgerufen wird.
variableDefinition	Integer	Die Variablendefinition, die als Argumente an das Fragment übergeben wird.

Beispiele für Darstellungen von Nachrichtenablaufvariablen

Die folgenden Beispiele zeigen die Darstellungen der Nachrichtenablaufvariablen für die Beispielnutzlasten der Anfrage.

Beispielabfrage 1

Dieses Beispiel zeigt eine Abfrage mit Argumenten, die als Eingabe übergeben werden. Dabei werden drei Attribute für Mitarbeiter abgefragt.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

Die Tabelle zeigt die Darstellungen der entsprechenden Nachrichtenblaufvariablen.

Variable für den Nachrichtenablauf	Wert
graphql.operation.operationType	QUERY
graphql.fragment.count	1
graphql.operation.selectionSet.count	1
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.name	employee
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	id
graphql.operation.selectionSet.1.argument.1.value	IntValue{value=123}
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.selectionSet.count	3
graphql.operation.selectionSet.1.selectionSet.1.name	id
graphql.operation.selectionSet.1.selectionSet.2.name	firstName
graphql.operation.selectionSet.1.selectionSet.3.name	lastName

Beispielabfrage 2

Dieses Beispiel zeigt eine Abfrage mit Argumenten, die als Eingabe übergeben werden. Dabei werden die Namen von Freunden abgefragt.

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

Die folgende Tabelle zeigt die Darstellungen der entsprechenden Nachrichtenablaufvariablen.

Variable für den Nachrichtenablauf	Wert
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	1
graphql.operation.name	Characters
graphql.fragment.count	0
graphql.operation.selectionSet.1.name	friends
graphql.operation.variableDefinitions.count	2
graphql.operation.variableDefinitions.1.name	episode
graphql.operation.variableDefinitions.1.type	TypeName{name='Episode'}
graphql.operation.variableDefinitions.2.name	withFriends
graphql.operation.variableDefinitions.2.type	NonNullType{type=TypeName{name='Boolean'}}
graphql.operation.selectionSet.1.argument.count	0
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	friendsName
graphql.operation.selectionSet.1.directive.count	1
graphql.operation.selectionSet.1.directive.1.argument.1.name	if
graphql.operation.selectionSet.1.directive.1.argument.1.value	VariableReference{name='withFriends'}

Beispielabfrage 3

Dieses Beispiel enthält eine Variablendefinition mit Alias.

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

Die folgende Tabelle zeigt die Darstellungen der entsprechenden Nachrichtenablaufvariablen.

Variable für den Nachrichtenablauf	Wert
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	2
graphql.operation.selectionSet.1.name	users
graphql.operation.selectionSet.1.alias	admins
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	role
graphql.operation.selectionSet.1.argument.1.value	EnumValue{name='ADMIN'}
graphql.operation.selectionSet.1.argument.2.name	null
graphql.operation.selectionSet.1.argument.2.value	null
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	lastName
graphql.operation.selectionSet.1.selectionSet.1.alias	null
graphql.operation.selectionSet.1.selectionSet.2.name	null
graphql.operation.selectionSet.1.selectionSet.2.alias	null
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.directive.1.argument.1.name	null
graphql.operation.selectionSet.1.directive.1.argument.1.value	null
graphql.operation.selectionSet.2.name	users
graphql.operation.selectionSet.2.alias	accountants
graphql.operation.selectionSet.2.argument.count	1
graphql.operation.selectionSet.2.argument.1.name	role
graphql.operation.selectionSet.2.argument.1.value	EnumValue{name='ACCOUNTANT'}
graphql.operation.selectionSet.2.selectionSet.count	1
graphql.operation.selectionSet.2.selectionSet.1.name	firstName
graphql.operation.selectionSet.2.directive.count	0
graphql.operation.selectionSet.2.selectionSet.1.alias	null
graphql.operation.selectionSet.2.selectionSet.2.name	null
graphql.operation.selectionSet.2.selectionSet.2.alias	null
graphql.operation.selectionSet.2.directive.count	0

Weitere Informationen

GraphQL verwenden