Überprüfen der GraphQL-Anforderung
GILT FÜR: Alle API Management-Ebenen
Die Richtlinie validate-graphql-request
überprüft die GraphQL-Anforderung und autorisiert den Zugriff auf bestimmte Abfragepfade in einer GraphQL-API. Eine ungültige Abfrage ist ein „Anforderungsfehler“. Die Autorisierung erfolgt nur für gültige Anforderungen.
Hinweis
Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.
Richtlinienanweisung
<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
<authorize>
<rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow | remove | reject | ignore'" />
</authorize>
</validate-graphql-request>
Attribute
Attribut | BESCHREIBUNG | Erforderlich | Standard |
---|---|---|---|
error-variable-name | Name der Variable in context.Variables , in der Validierungsfehler protokolliert werden. Richtlinienausdrücke sind zulässig. |
Nein | – |
max-size | Maximale Größe der Anforderungsnutzlast in Bytes. Maximal zulässiger Wert: 102.400 Byte (100 KB). (Wenden Sie sich an den Support, wenn Sie diesen Grenzwert erhöhen müssen.) Richtlinienausdrücke sind zulässig. | Ja | – |
max-depth | Eine ganze Zahl. Maximale Abfragetiefe. Richtlinienausdrücke sind zulässig. | Nein | 6 |
Elemente
Name | BESCHREIBUNG | Erforderlich |
---|---|---|
Autorisieren | Konfigurieren Sie dieses Element, um eine geeignete Autorisierungsregel für einen oder mehrere Pfade festzulegen. | Nein |
rule | Fügen Sie mindestens eins dieser Elemente hinzu, um bestimmte Abfragepfade zu autorisieren. Jede Regel kann optional eine andere Aktion angeben. Kann mithilfe eines Richtlinienausdrucks bedingt angegeben werden. | Nein |
Rollenattribute
attribute | BESCHREIBUNG | Erforderlich | Standard |
---|---|---|---|
path | Pfad, für den die Autorisierungsvalidierung ausgeführt werden soll. Er muss dem folgenden Muster entsprechen: /type/field . |
Ja | – |
action | Die auszuführende Aktion, wenn die Regel gilt. Kann mithilfe eines Richtlinienausdrucks bedingt angegeben werden. | Nein | allow |
Introspektions-System
Die Richtlinie für path= /__*
ist das Introspektions-System. Sie können damit Introspektionsanforderungen (__schema
, __type
usw.) ablehnen.
Anforderungsaktionen
Verfügbare Lösungen sind in der folgenden Tabelle beschrieben.
Aktion | BESCHREIBUNG |
---|---|
reject | Es tritt ein Anforderungsfehler auf, und die Anforderung wird nicht an das Back-End gesendet. Zusätzliche Regeln, sofern konfiguriert, werden nicht angewendet. |
Entfernen | Ein Feldfehler tritt auf, und das Feld wird aus der Anforderung entfernt. |
allow | Das Feld wird an das Back-End übergeben. |
ignore | Die Regel ist in diesem Fall ungültig, und die nächste Regel wird angewendet. |
Verwendung
- Richtlinienabschnitte: inbound
- Richtlinienbereiche: global, Arbeitsbereich, Produkt, API
- Gateways: klassisch, v2, Verbrauch, selbstgehostet, Arbeitsbereich
Hinweise zur Verwendung
Konfigurieren Sie die Richtlinie für eine Passthrough- oder synthetische GraphQL-API, die in API Management importiert wurde.
Diese Richtlinie kann nur einmal in einem Richtlinienabschnitt verwendet werden.
Da GraphQL-Abfragen ein vereinfachtes Schema verwenden, können Berechtigungen auf jeden Blattknoten eines Ausgabetyps angewendet werden:
- Mutation, Abfrage oder Abonnement
- Einzelnes Feld in einer Typdeklaration.
Berechtigungen werden möglicherweise nicht angewendet auf:
- Eingabetypen
- Fragments
- Unions
- Schnittstellen
- Das Schemaelement
Fehlerbehandlung
Ein Fehler bei der Überprüfung anhand des GraphQL-Schemas oder eines Fehlers für die Größe oder Tiefe der Anforderung ist ein Anforderungsfehler und führt dazu, dass bei der Anforderung ein Fehlerblock (aber kein Datenblock) auftritt.
Ähnlich wie bei der Eigenschaft Context.LastError
werden alle GraphQL-Validierungsfehler automatisch in der Variablen GraphQLErrors
weitergegeben. Wenn die Fehler separat weitergegeben werden müssen, können Sie einen Fehlervariablennamen angeben. Fehler werden in die Variable error
und die Variable GraphQLErrors
gepusht.
Beispiele
Abfragevalidierung
In diesem Beispiel werden die folgenden Validierungs- und Autorisierungsregeln auf eine GraphQL-Abfrage angewendet:
- Anforderungen, die größer als 100 KB sind oder eine größere Abfragetiefe als 4 haben, werden abgelehnt.
- Anforderungen an das Introspektionssystem werden abgelehnt.
- Das
/Missions/name
-Feld wird aus Anforderungen entfernt, die mehr als zwei Header enthalten.
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4">
<authorize>
<rule path="/__*" action="reject" />
<rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
</authorize>
</validate-graphql-request>
Mutationsvalidierung
In diesem Beispiel werden die folgenden Validierungs- und Autorisierungsregeln auf eine GraphQL-Mutation angewendet:
- Anforderungen, die größer als 100 KB sind oder eine größere Abfragetiefe als 4 haben, werden abgelehnt.
- Anforderungen zum Mutieren des
deleteUser
-Felds werden verweigert, es sei denn, die Anforderung stammt von der IP-Adresse198.51.100.1
.
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4">
<authorize>
<rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
</authorize>
</validate-graphql-request>
Verwandte Richtlinien
Zugehöriger Inhalt
Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier:
- Tutorial: Transformieren und Schützen Ihrer API
- Unter Richtlinien für die API-Verwaltung finden Sie eine komplette Liste der Richtlinienanweisungen und der zugehörigen Einstellungen.
- Richtlinienausdrücke
- Festlegen oder Bearbeiten von Richtlinien
- Wiederverwenden von Richtlinienkonfigurationen
- Repository für Richtliniencodeausschnitte
- Erstellen von Richtlinien mit Microsoft Copilot in Azure