Validieren von Statuscodes
GILT FÜR: Alle API Management-Ebenen
Die validate-status-code-Richtlinie überprüft die HTTP-Statuscodes in Antworten anhand des API-Schemas. Mit dieser Richtlinie kann die Preisgabe von Details zu Back-End-Fehlern verhindert werden, die Stapelüberwachungen enthalten können.
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-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
<status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>
Attribute
| Attribut | BESCHREIBUNG | Erforderlich | Standard |
|---|---|---|---|
| unspecified-status-code-action | Aktion, die für HTTP-Statuscodes in Reaktionen ausgeführt werden soll, die im API-Schema nicht angegeben sind 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 |
|---|---|---|
| status-code | Fügen Sie mindestens ein Element für HTTP-Statuscodes hinzu, um die Standardvalidierungsaktion für Statuscodes in Antworten außer Kraft zu setzen. | Nein |
status-code-Attribute
| attribute | BESCHREIBUNG | Erforderlich | Standard |
|---|---|---|---|
| code | Der HTTP-Statuscode, für den die Validierungsaktion außer Kraft gesetzt werden soll. | Ja | – |
| action | Aktion, die für den entsprechenden Statuscode ausgeführt werden soll, der im API-Schema nicht angegeben ist. Wenn der Statuscode im API-Schema angegeben ist, findet keine Außerkraftsetzung statt. | Ja | – |
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: outbound, on-error
- 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
<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />
Ü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 in Azure