Freigeben über

Validieren von Parametern

  • Artikel

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

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: