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
Weitere Informationen finden Sie in den folgenden Ressourcen:
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.
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 Optional können Sie das Element |
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:
|
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, wennAction
aufparse
gesetzt ist. Dies kann wertvolle CPU-Zeit im Back-End sparen. Beachten Sie, dassverify
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.
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-Abfragemutation
: Eine GraphQL-Mutationquery_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.
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.
![Grafik: GraphQL-Abfragediagramm.](https://cloud.google.com/static/apigee/docs/api-platform/develop/images/graphql-query.png?authuser=19&hl=de)
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 handeltroot-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 Wertesub-indices
: Untergeordnete Indexechild-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 |