Inhalt prüfen

GILT FÜR: Alle API Management-Ebenen

Mit der Richtlinie validate-content wird die Größe oder der Inhalt eines Anforderungs- oder Reaktionstexts anhand eines oder mehrerer unterstützten Schemas überprüft.

In der folgenden Tabelle werden die Schemaformate und Anforderungs- oder Reaktionsinhaltstypen dargestellt, die von der Richtlinie unterstützt werden. Bei Inhaltstypwerten wird die Groß-/Kleinschreibung nicht beachtet.

Überprüfte Inhalte

Die Richtlinie überprüft die folgenden Inhalte in der Anforderung oder Antwort auf das Schema:

• Vorhandensein aller erforderlichen Eigenschaften
• Vorhandensein oder Fehlen zusätzlicher Eigenschaften, wenn für das Schema das Feld additionalProperties festgelegt ist. Kann mit dem Attribut allow-additional-properties überschrieben werden.
• Typen aller Eigenschaften. Wenn beispielsweise ein Schema eine Eigenschaft als Integer angibt, muss die Anforderung (oder Antwort) einen Integer und nicht einen anderen Typ (etwa eine Zeichenfolge) enthalten.
• Das Format der Eigenschaften, sofern im Schema angegeben, z. B. RegEx (bei Angabe des Schlüsselworts pattern), minimum für Integer usw.

Richtlinienanweisung

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

Attribute

Elemente

content-type-map-Attribute

content-type-map-elements

content-Attribute

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, outbound, on-error
• Richtlinienbereiche: global, Arbeitsbereich, Produkt, API, Vorgang
• Gateways: klassisch, v2, Verbrauch, selbstgehostet, Arbeitsbereich

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.

Schemas für die Inhaltsvalidierung

Standardmäßig werden zur Validierung von Anforderungs- oder Reaktionsinhalten JSON- oder XML-Schemas aus der API-Definition verwendet. Diese Schemas können manuell angegeben oder automatisch generiert werden, wenn eine API aus einer OpenAPI- oder WSDL-Spezifikation in API Management importiert wird.

Mithilfe der Richtlinie validate-content können Sie optional anhand eines oder mehrerer JSON- oder XML-Schemas eine Validierung durchführen, die Sie Ihrer API Management-Instanz hinzugefügt haben und die nicht Teil der API-Definition sind. Ein Schema, das Sie API Management hinzufügen, kann für viele APIs wiederverwendet werden.

So fügen Sie Ihrer API Management-Instanz mithilfe des Azure-Portals ein Schema hinzu:

1. Navigieren Sie im Portal zu Ihrer API Management-Instanz.

2. Wählen Sie im Abschnitt APIs des linken Menüs Schemas>+ Hinzufügen aus.

3. Gehen Sie im Fenster Schema erstellen wie folgt vor:

   1. Geben Sie einen Namen (ID) für das Schema ein.
   2. Wählen Sie unter Schematyp die Option JSON oder XML aus.
   3. Geben Sie eine Beschreibung ein.
   4. Führen Sie in Methode erstellen einen der folgenden Schritte aus:
      • Wählen Sie Neu erstellen aus, und geben Sie das Schema ein, oder fügen Sie es ein.
      • Wählen Sie Aus Datei importieren oder Aus URL importieren aus, und geben Sie einen Schemaspeicherort ein.

        Hinweis

        Um ein Schema aus einer URL zu importieren, muss Zugriff darauf im Browser über das Internet möglich sein.

   5. Wählen Sie Speichern aus.

   

API Management fügt die Schemaressource im relativen URI /schemas/<schemaId> hinzu, und das Schema wird auf der Seite Schemas in der Liste angezeigt. Wählen Sie ein Schema aus, um dessen Eigenschaften anzuzeigen oder es in einem Schema-Editor zu bearbeiten.

Beispiele

JSON-Schemavalidierung

Im folgenden Beispiel werden Anforderungen mit einem leeren Inhaltstypheader oder Anforderungen mit einem Inhaltstypheader application/hal+json als Anforderungen mit dem Inhaltstyp application/json von API Management interpretiert. Anschließend wird die Validierung im Erkennungsmodus von API Management anhand eines Schemas ausgeführt, das für den Inhaltstyp application/json in der API-Definition definiert ist. Meldungen mit Payloads von mehr als 100 KB werden blockiert. Anforderungen, die zusätzliche Eigenschaften enthalten, werden blockiert, auch wenn das Feld additionalProperties des Schemas so konfiguriert ist, dass zusätzliche Eigenschaften zulässig sind.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

SOAP-Schemaüberprüfung

Im folgenden Beispiel wird jede Anforderung von API Management als Anforderung mit dem Inhaltstyp application/soap+xml interpretiert (dem Inhaltstyp, der von SOAP 1.2-APIs verwendet wird), unabhängig vom eingehenden Inhaltstyp. Die Anforderung kann mit einem leeren Inhaltstypheader, einem Inhaltstypheader von text/xml (von SOAP 1.1-APIs verwendet) oder einem anderen Inhaltstypheader eingehen. Anschließend wird die XML-Nutzlast durch API Management aus dem SOAP-Umschlag extrahiert und die Überprüfung im Schutzmodus anhand des Schemas „myschema“ durchgeführt. Meldungen mit Payloads von mehr als 100 KB werden blockiert.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

Ü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