Validieren von Statuscodes

  • Artikel

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

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: