Validieren von Parametern

GILT FÜR: Alle API Management-Ebenen

Die validate-parameters-Richtlinie überprüft die Parameter für Header, Abfrage oder Pfad in Anforderungen anhand des API-Schemas.

Richtlinienanweisung

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Attribute

Elemente

Aktionen

Die Inhaltsvalidierungsrichtlinien enthalten mindestens ein Attribut, das eine Aktion angibt, die API Management beim Validieren einer Entität in einer API-Anforderung oder -Antwort anhand des API-Schemas ausführt.

• Eine Aktion kann für Elemente angegeben werden, die im API-Schema repräsentiert werden, und je nach Richtlinie auch für Elemente, die im API-Schema nicht repräsentiert werden.

• Eine Aktion, die in einem untergeordneten Element einer Richtlinie angegeben ist, setzt eine für das übergeordnete Element angegebene Aktion außer Kraft.

Verfügbare Aktionen:

Verwendung

• Richtlinienabschnitte: inbound
• Richtlinienbereiche: global, Arbeitsbereich, Produkt, API, Vorgang
• Gateways: klassisch, v2, Verbrauch, selbstgehostet, Arbeitsbereich

Hinweise zur Verwendung

• Diese Richtlinie kann nur einmal in einem Richtlinienabschnitt verwendet werden.

Protokolle

Details zu den Validierungsfehlern während der Richtlinienausführung werden in die Variable in context.Variables protokolliert, die im Attribut errors-variable-name im Stammelement der Richtlinie angegeben ist. Ein Validierungsfehler blockiert die weitere Verarbeitung von Anforderung oder Antwort und wird auch an die Eigenschaft prevent weitergegeben, sofern dies in einer context.LastError-Aktion konfiguriert ist.

Verwenden Sie zum Untersuchen von Fehlern eine Richtlinie zur Ablaufverfolgung, um die Fehler aus Kontextvariablen in Application Insights zu protokollieren.

Folgen für die Leistung

Das Hinzufügen einer Validierungsrichtlinie kann sich auf den API-Durchsatz auswirken. Es gelten die folgenden allgemeinen Prinzipien:

• Je größer das API-Schema ist, desto niedriger ist der Durchsatz.
• Je größer die Payload in einer Anforderung oder Antwort ist, desto niedriger ist der Durchsatz.
• Die Größe des API-Schemas hat größere Auswirkungen auf die Leistung als die Größe der Payload.
• Die Validierung anhand eines API-Schemas mit einer Größe von mehreren Megabyte kann unter bestimmten Bedingungen Anforderungs- oder Antworttimeouts verursachen. Dieser Effekt ist auf den Dienstebenen Verbrauch und Entwickler deutlicher ausgeprägt.

Es empfiehlt sich, Auslastungstests mit den erwarteten Produktionsworkloads durchzuführen, um die Auswirkungen von Validierungsrichtlinien auf den API-Durchsatz zu bewerten.

Beispiel

In diesem Beispiel werden alle Abfrage- und Pfadparameter im Präventionsmodus überprüft, die Header im Erkennungsmodus. Die Validierung wird für verschiedene Headerparameter außer Kraft gesetzt:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

Überprüfungsfehler

API Management generiert Inhaltsvalidierungsfehler im folgenden Format:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

In der folgenden Tabelle werden alle möglichen Fehler der Validierungsrichtlinien aufgeführt.

• Details: Können zum Untersuchen von Fehlern verwendet werden. Nicht für die öffentliche Freigabe vorgesehen.
• Öffentliche Antwort: An den Client zurückgegebener Fehler. Gibt keine Implementierungsdetails preis.

Wenn eine Validierungsrichtlinie die Aktion prevent angibt und einen Fehler erzeugt, enthält die Antwort von API Management einen HTTP-Statuscode 400, wenn die Richtlinie im eingehenden Abschnitt angewendet wird, und 502, wenn die Richtlinie im ausgehenden Abschnitt angewendet wird.

In der folgenden Tabelle sind alle möglichen Werte für den Grund eines Validierungsfehlers sowie mögliche Werte für die Meldung aufgeführt:

Verwandte Richtlinien

• Validierung von Inhalten

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
• Azure API Management-Richtlinientoolkit
• Erstellen von Richtlinien mit Microsoft Copilot in Azure