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.
Wichtig
Wenn Sie eine API mithilfe einer Verwaltungs-API-Version vor 2021-01-01-preview importiert haben, funktioniert die validate-parameters-Richtlinie möglicherweise nicht. Möglicherweise müssen Sie Ihre API mithilfe der Management-API-Version 2021-01-01-preview oder höher erneut importieren.
Hinweis
Die maximale Größe des API-Schemas, das von dieser Validierungsrichtlinie verwendet werden kann, beträgt 4 MB. Wenn das Schema diesen Grenzwert überschreitet, geben Validierungsrichtlinien zur Laufzeit Fehler zurück. Zum Erhöhen des Grenzwerts wenden Sie sich an den Support.
Hinweis
Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Das Portal unterstützt Sie bei der Konfiguration dieser Richtlinie durch einen formularbasierten, angeleiteten Editor. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.
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
| Attribut | BESCHREIBUNG | Erforderlich | Standard |
|---|---|---|---|
| specified-parameter-action | Aktion, die für im API-Schema angegebene Anforderungsparameter ausgeführt werden soll. Wenn dieser Wert in einem headers-, query- oder path-Element bereitgestellt wird, setzt er den Wert von specified-parameter-action im validate-parameters-Element außer Kraft. Richtlinienausdrücke sind zulässig. |
Ja | – |
| unspecified-parameter-action | Aktion, die für im API-Schema nicht angegebene Anforderungsparameter ausgeführt werden soll. Wenn dieser Wert in einem headers- oder query-Element bereitgestellt wird, setzt er den Wert von unspecified-parameter-action im validate-parameters-Element außer Kraft. Richtlinienausdrücke sind zulässig. |
Ja | – |
| errors-variable-name | Name der Variable in context.Variables, in der Validierungsfehler protokolliert werden. Richtlinienausdrücke sind nicht zulässig. |
Nein | – |
Elemente
| Name | BESCHREIBUNG | Erforderlich |
|---|---|---|
| headers | Fügen Sie dieses Element und mindestens ein parameter-Unterelement hinzu, um Standardüberprüfungsaktionen für bestimmte benannte Parameter in Anforderungen außer Kraft zu setzen. Wenn der Parameter im API-Schema angegeben ist, setzt dieser Wert die Konfiguration von specified-parameter-action auf höherer Ebene außer Kraft. Wenn der Parameter im API-Schema nicht angegeben ist, setzt dieser Wert die Konfiguration von unspecified-parameter-action auf höherer Ebene außer Kraft. |
Nein |
| Abfrage | Fügen Sie dieses Element und mindestens ein parameter-Unterelement hinzu, um Standardüberprüfungsaktionen für bestimmte benannte Abfrageparameter in Anforderungen zu überschreiben. Wenn der Parameter im API-Schema angegeben ist, setzt dieser Wert die Konfiguration von specified-parameter-action auf höherer Ebene außer Kraft. Wenn der Parameter im API-Schema nicht angegeben ist, setzt dieser Wert die Konfiguration von unspecified-parameter-action auf höherer Ebene außer Kraft. |
Nein |
| path | Fügen Sie dieses Element und mindestens ein parameter-Unterelement hinzu, um Standardüberprüfungsaktionen für bestimmte benannte URL Pfadparameter in Anforderungen außer Kraft zu setzen. Wenn der Parameter im API-Schema angegeben ist, setzt dieser Wert die Konfiguration von specified-parameter-action auf höherer Ebene außer Kraft. Wenn der Parameter im API-Schema nicht angegeben ist, setzt dieser Wert die Konfiguration von unspecified-parameter-action auf höherer Ebene außer Kraft. |
Nein |
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:
| Aktion | Description |
|---|---|
| ignore | Die Überprüfung wird übersprungen. |
| prevent | Die Verarbeitung von Anforderung oder Antwort wird blockiert, ein ausführlicher Validierungsfehler wird protokolliert, und ein Fehler wird zurückgegeben. Die Verarbeitung wird unterbrochen, wenn die ersten Fehler erkannt werden. |
| Erkennen | Validierungsfehler werden protokolliert, ohne dass die Verarbeitung von Anforderung oder Antwort unterbrochen wird. |
Verwendung
- Richtlinienabschnitte: inbound
- Richtlinienbereiche: global, Arbeitsbereich, Produkt, API, Vorgang
- Gateways: classic, v2, consumption, self-hosted
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.
| Name | Typ | Überprüfungsregel | Details | Öffentliche Antwort | Aktion |
|---|---|---|---|---|---|
| validate-content | |||||
| RequestBody | SizeLimit | Der Anforderungstext ist {size} Byte lang und überschreitet das konfigurierte Limit von {maxSize} Byte. | Der Anforderungstext ist {size} Byte lang und überschreitet das Limit von {maxSize} Byte. | Erkennen/Verhindern | |
| ResponseBody | SizeLimit | Der Antworttext ist {size} Byte lang und überschreitet das konfigurierte Limit von {maxSize} Byte. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | |
| {messageContentType} | RequestBody | Nicht angegeben. | Der nicht angegebene Inhaltstyp „{messageContentType}“ ist nicht zulässig. | Der nicht angegebene Inhaltstyp „{messageContentType}“ ist nicht zulässig. | Erkennen/Verhindern |
| {messageContentType} | ResponseBody | Nicht angegeben. | Der nicht angegebene Inhaltstyp „{messageContentType}“ ist nicht zulässig. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| ApiSchema | Das API-Schema ist nicht vorhanden oder konnte nicht aufgelöst werden. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | ||
| ApiSchema | Das API-Schema gibt keine Definitionen an. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | ||
| {messageContentType} | RequestBody / ResponseBody | MissingDefinition | Das API-Schema enthält die Definition „{definitionName}“ nicht, die dem Inhaltstyp „{messageContentType}“ zugeordnet ist. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {messageContentType} | RequestBody | IncorrectMessage | Der Text der Anforderung entspricht nicht der Definition „{definitionName}“, die dem Inhaltstyp „{messageContentType}“ zugeordnet ist. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Der Text der Anforderung entspricht nicht der Definition „{definitionName}“, die dem Inhaltstyp „{messageContentType}“ zugeordnet ist. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Erkennen/Verhindern |
| {messageContentType} | ResponseBody | IncorrectMessage | Der Text der Antwort entspricht nicht der Definition „{definitionName}“, die dem Inhaltstyp „{messageContentType}“ zugeordnet ist. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| RequestBody | ValidationException | Der Text der Anforderung kann für den Inhaltstyp „{messageContentType}“ nicht validiert werden. {exception details} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | |
| ResponseBody | ValidationException | Der Text der Antwort kann für den Inhaltstyp „{messageContentType}“ nicht validiert werden. {exception details} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | |
| validate-parameters/validate-headers | |||||
| {paramName} / {headerName} | QueryParameter / PathParameter / RequestHeader | Nicht angegeben. | Ein nicht angegebener {paramName} für {path parameter / query parameter / header} ist nicht zulässig. | Ein nicht angegebener {paramName} für {path parameter / query parameter / header} ist nicht zulässig. | Erkennen/Verhindern |
| {headerName} | ResponseHeader | Nicht angegeben. | Ein nicht angegebener Header „{headerName}“ ist nicht zulässig. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| ApiSchema | Das API-Schema ist nicht vorhanden oder konnte nicht aufgelöst werden. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | ||
| ApiSchema | Das API-Schema gibt keine Definitionen an. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern | ||
| {paramName} | QueryParameter / PathParameter / RequestHeader / ResponseHeader | MissingDefinition | Das API-Schema enthält die Definition „{definitionName}“ nicht, die dem {paramName} für {query parameter / path parameter / header} zugeordnet ist. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {paramName} | QueryParameter / PathParameter / RequestHeader | IncorrectMessage | Die Anforderung darf nicht mehrere Werte für den {paramName} für {query parameter / path parameter / header} enthalten. | Die Anforderung darf nicht mehrere Werte für den {paramName} für {query parameter / path parameter / header} enthalten. | Erkennen/Verhindern |
| {headerName} | ResponseHeader | IncorrectMessage | Die Antwort darf nicht mehrere Werte für den Header „{headerName}“ enthalten. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {paramName} | QueryParameter / PathParameter / RequestHeader | IncorrectMessage | Der Wert des {paramName} für {query parameter / path parameter / header} entspricht der Definition nicht. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Der Wert des {paramName} für {query parameter / path parameter / header} entspricht der Definition nicht. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Erkennen/Verhindern |
| {headerName} | ResponseHeader | IncorrectMessage | Der Wert des Headers „{headerName}“ entspricht der Definition nicht. {valError.Message} Zeile: {valError.LineNumber}, Position: {valError.LinePosition} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {paramName} | QueryParameter / PathParameter / RequestHeader | IncorrectMessage | Der Wert des {paramName} für {query parameter / path parameter / header} kann nicht entsprechend der Definition analysiert werden. {ex.Message} |
Der Wert des {paramName} für {query parameter / path parameter / header} konnte nicht entsprechend der Definition analysiert werden. {ex.Message} |
Erkennen/Verhindern |
| {headerName} | ResponseHeader | IncorrectMessage | Der Wert des Headers „{headerName}“ konnte nicht entsprechend der Definition analysiert werden. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {paramName} | QueryParameter / PathParameter / RequestHeader | ValidationError | Der {paramName} für {Query parameter / Path parameter / Header} kann nicht validiert werden. {exception details} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| {headerName} | ResponseHeader | ValidationError | Der Header „{headerName}“ kann nicht validiert werden. {exception details} |
Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
| validate-status-code | |||||
| {status-code} | StatusCode | Nicht angegeben. | Der Antwortstatuscode „{status-code}“ ist nicht zulässig. | Die Anforderung konnte aufgrund eines internen Fehlers nicht verarbeitet werden. Kontaktieren Sie den API-Besitzer. | Erkennen/Verhindern |
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:
| `Reason` | Meldung |
|---|---|
| Ungültige Anforderung | {Details} für die Kontextvariable, {Public response} für den Client |
| Antwort nicht zulässig | {Details} für die Kontextvariable, {Public response} für den Client |
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 für Azure