Inhoud valideren

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Het validate-content beleid valideert de grootte of inhoud van een aanvraag of antwoordtekst op basis van een of meer ondersteunde schema's.

In de volgende tabel ziet u de schema-indelingen en aanvraag- of antwoordinhoudstypen die door het beleid worden ondersteund. Inhoudstypewaarden zijn niet hoofdlettergevoelig.

Indeling Inhoudstypen
JSON Voorbeelden: application/json
application/hal+json
XML Voorbeeld: application/xml
SOAP Toegestane waarden: application/soap+xml voor SOAP 1.2-API's
text/xml voor SOAP 1.1 API's

Notitie

De maximale grootte van het API-schema dat door dit validatiebeleid kan worden gebruikt, is 4 MB. Als het schema deze limiet overschrijdt, retourneert validatiebeleid fouten tijdens runtime. Neem contact op met de ondersteuning om het te verhogen.

Welke inhoud wordt gevalideerd

Het beleid valideert de volgende inhoud in de aanvraag of het antwoord op het schema:

  • Aanwezigheid van alle vereiste eigenschappen.
  • Aanwezigheid of afwezigheid van aanvullende eigenschappen, als het schema het additionalProperties veld heeft ingesteld. Kan worden overschreven met het allow-additional-properties kenmerk.
  • Typen van alle eigenschappen. Als een schema bijvoorbeeld een eigenschap opgeeft als een geheel getal, moet de aanvraag (of het antwoord) een geheel getal bevatten en niet een ander type, zoals een tekenreeks.
  • De indeling van de eigenschappen, indien opgegeven in het schema, bijvoorbeeld regex (als het pattern trefwoord is opgegeven), minimum voor gehele getallen, enzovoort.

Tip

Zie OWASP Validation Regex Repository voor voorbeelden van regex-patroonbeperkingen die kunnen worden gebruikt in schema's.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Om u te helpen dit beleid te configureren, biedt de portal een begeleide editor op basis van formulieren. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

<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" />
</validate-content>

Kenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
unspecified-content-type-action Actie die moet worden uitgevoerd voor aanvragen of antwoorden met een inhoudstype dat niet is opgegeven in het API-schema. Beleidsexpressies zijn toegestaan. Ja N.v.t.
maximale grootte De maximale lengte van de hoofdtekst van de aanvraag of het antwoord in bytes, gecontroleerd op basis van de Content-Length header. Als de hoofdtekst of antwoordtekst van de aanvraag wordt gecomprimeerd, is deze waarde de gedecomprimeerde lengte. Maximaal toegestane waarde: 102.400 bytes (100 kB). (Neem contact op met de ondersteuning als u deze limiet wilt verhogen.) Beleidsexpressies zijn toegestaan. Ja N.v.t.
grootte overschreden-actie Actie die moet worden uitgevoerd voor aanvragen of antwoorden waarvan de hoofdtekst groter is dan de grootte die is opgegeven in max-size. Beleidsexpressies zijn toegestaan. Ja N.v.t.
errors-variable-name De naam van de variabele waarin context.Variables validatiefouten moeten worden vastgelegd. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

Elementen

Name Beschrijving Vereist
inhoudstypetoewijzing Voeg dit element toe om het inhoudstype van de binnenkomende aanvraag of het antwoord toe te wijzen aan een ander inhoudstype dat wordt gebruikt om validatie te activeren. Nee
content Voeg een of meer van deze elementen toe om het inhoudstype in de aanvraag of het antwoord of het toegewezen inhoudstype te valideren en voer de opgegeven actie uit. Nee

kenmerken van inhoudstypetoewijzing

Kenmerk Beschrijving Vereist Standaardinstelling
any-content-type-value Inhoudstype dat wordt gebruikt voor validatie van de hoofdtekst van een aanvraag of antwoord, ongeacht het binnenkomende inhoudstype. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.
missing-content-type-value Inhoudstype dat wordt gebruikt voor validatie van de hoofdtekst van een aanvraag of antwoord, wanneer het binnenkomende inhoudstype ontbreekt of leeg is. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

inhoudstype-kaart-elementen

Name Beschrijving Vereist
type Voeg een of meer van deze elementen toe om een binnenkomend inhoudstype toe te wijzen aan een inhoudstype dat wordt gebruikt voor validatie van de hoofdtekst van een aanvraag of antwoord. Gebruik from dit om een bekend binnenkomende inhoudstype op te geven of gebruik when deze met een beleidsexpressie om een binnenkomend inhoudstype op te geven dat overeenkomt met een voorwaarde. Overschrijft de toewijzing in any-content-type-value en missing-content-type-value, indien opgegeven. Nee

inhoudskenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
type Inhoudstype voor het uitvoeren van bodyvalidatie, gecontroleerd op de koptekst van het inhoudstype of de waarde die is toegewezen in content-type-mapping, indien opgegeven. Als deze leeg is, is dit van toepassing op elk inhoudstype dat is opgegeven in het API-schema.

Als u SOAP-aanvragen en -antwoorden wilt valideren (validate-as kenmerk ingesteld op 'soap'), ingesteld type op application/soap+xml VOOR SOAP 1.2-API's of text/xml voor SOAP 1.1-API's.		 Nee N.v.t.
validate-as Validatie-engine die moet worden gebruikt voor validatie van de hoofdtekst van een aanvraag of antwoord met een overeenkomende aanvraag type. Ondersteunde waarden: 'json', 'xml', 'soap'.

Wanneer 'soap' is opgegeven, wordt de XML uit de aanvraag of het antwoord geëxtraheerd uit de SOAP-envelop en gevalideerd op basis van een XML-schema.		 Ja N.v.t.
schema-id Naam van een bestaand schema dat is toegevoegd aan het API Management-exemplaar voor inhoudsvalidatie. Als dit niet is opgegeven, wordt het standaardschema van de API-definitie gebruikt. Nee N.v.t.
schema-ref Voor een JSON-schema dat is opgegeven in schema-id, optionele verwijzing naar een geldig lokaal referentiepad in het JSON-document. Voorbeeld: #/components/schemas/address. Het kenmerk moet een JSON-object retourneren dat API Management verwerkt als een geldig JSON-schema.

Voor een XML-schema schema-ref wordt niet ondersteund en kan een schema-element op het hoogste niveau worden gebruikt als de hoofdmap van de XML-aanvraag of nettolading van het antwoord. De validatie controleert of alle elementen die beginnen met de hoofdmap van de XML-aanvraag of de nettolading van het antwoord, voldoen aan het opgegeven XML-schema.		 Nee N.v.t.
allow-additional-properties Booleaans. Voor een JSON-schema geeft u op of een runtime-onderdrukking moet worden geïmplementeerd van de additionalProperties waarde die in het schema is geconfigureerd:
- true: sta aanvullende eigenschappen toe in de hoofdtekst van de aanvraag of het antwoord, zelfs als het veld van additionalProperties het JSON-schema is geconfigureerd om geen extra eigenschappen toe te staan.
- false: sta geen extra eigenschappen toe in de hoofdtekst van de aanvraag of het antwoord, zelfs als het veld van additionalProperties het JSON-schema is geconfigureerd om extra eigenschappen toe te staan.

Als het kenmerk niet is opgegeven, valideert het beleid aanvullende eigenschappen op basis van de configuratie van het additionalProperties veld in het schema.		 Nee N.v.t.

Acties

Het beleid voor inhoudsvalidatie bevat een of meer kenmerken die een actie opgeven die API Management uitvoert bij het valideren van een entiteit in een API-aanvraag of -reactie op basis van het API-schema.

  • Er kan een actie worden opgegeven voor elementen die worden weergegeven in het API-schema en, afhankelijk van het beleid, voor elementen die niet worden weergegeven in het API-schema.

  • Een actie die is opgegeven in het onderliggende element van een beleid overschrijft een actie die is opgegeven voor het bovenliggende element.

Beschikbare acties:

Actie Omschrijving
Negeren Validatie overslaan.
Voorkomen Blokkeer de verwerking van de aanvraag of het antwoord, registreer de uitgebreide validatiefout en retourneer een fout. De verwerking wordt onderbroken wanneer de eerste set fouten wordt gedetecteerd.
detect Logboekvalidatiefouten, zonder de verwerking van aanvragen of antwoorden te onderbreken.

Gebruik

Logboeken

Details over de validatiefouten tijdens het uitvoeren van het beleid worden vastgelegd in de variabele die is context.Variables opgegeven in het errors-variable-name kenmerk in het hoofdelement van het beleid. Wanneer een prevent actie is geconfigureerd, blokkeert een validatiefout verdere verwerking van aanvragen of antwoorden en wordt deze ook doorgegeven aan de context.LastError eigenschap.

Als u fouten wilt onderzoeken, gebruikt u een traceringsbeleid om de fouten van contextvariabelen te registreren bij Application Insights.

Gevolgen voor de prestaties

Het toevoegen van een validatiebeleid kan van invloed zijn op API-doorvoer. De volgende algemene principes zijn van toepassing:

  • Hoe groter de API-schemagrootte, hoe lager de doorvoer is.
  • Hoe groter de nettolading in een aanvraag of antwoord, hoe lager de doorvoer is.
  • De grootte van het API-schema heeft een grotere invloed op de prestaties dan de grootte van de nettolading.
  • Validatie op basis van een API-schema dat meerdere megabytes groot is, kan tot time-outs voor aanvragen of antwoorden leiden onder bepaalde omstandigheden. Het effect is meer uitgesproken in de verbruiks - en ontwikkelaarslagen van de service.

Het is raadzaam om belastingtests uit te voeren met uw verwachte productieworkloads om de impact van validatiebeleid op API-doorvoer te beoordelen.

Schema's voor inhoudsvalidatie

Validatie van aanvraag- of antwoordinhoud maakt standaard gebruik van JSON- of XML-schema's uit de API-definitie. Deze schema's kunnen handmatig worden opgegeven of automatisch worden gegenereerd bij het importeren van een API uit een OpenAPI- of WSDL-specificatie in API Management.

Met behulp van het validate-content beleid kunt u eventueel valideren op basis van een of meer JSON- of XML-schema's die u hebt toegevoegd aan uw API Management-exemplaar en die geen deel uitmaken van de API-definitie. Een schema dat u aan API Management toevoegt, kan opnieuw worden gebruikt in veel API's.

Ga als volgende te werk om een schema toe te voegen aan uw API Management-exemplaar met behulp van Azure Portal:

  1. Navigeer in de portal naar uw API Management-exemplaar.

  2. Selecteer Schema's>+ Toevoegen in de sectie API's van het linkermenu.

  3. Ga als volgt te werk in het venster Schema maken:

    1. Voer een naam (id) in voor het schema.
    2. Selecteer JSON of XML in schematype.
    3. Voer een beschrijving in.
    4. Voer in de methode Create een van de volgende handelingen uit:
      • Selecteer Nieuw maken en voer het schema in of plak deze.
      • Selecteer Importeren uit bestand of Importeren uit URL en voer een schemalocatie in.

        Notitie

        Als u een schema vanuit de URL wilt importeren, moet het schema toegankelijk zijn via internet vanuit de browser.

    5. Selecteer Opslaan.

    Schema maken

API Management voegt de schemaresource toe op de relatieve URI /schemas/<schemaId>en het schema wordt weergegeven in de lijst op de pagina Schema's . Selecteer een schema om de eigenschappen ervan weer te geven of om te bewerken in een schema-editor.

Notitie

Een schema kan kruisverwijzingen naar een ander schema dat wordt toegevoegd aan het API Management-exemplaar. Neem bijvoorbeeld een XML-schema op dat is toegevoegd aan API Management met behulp van een element dat vergelijkbaar is met:

<xs:include schemaLocation="/schemas/myschema" />

Tip

Opensource-hulpprogramma's voor het oplossen van WSDL- en XSD-schemaverwijzingen en voor batchimport gegenereerde schema's in API Management zijn beschikbaar op GitHub.

Voorbeelden

JSON-schemavalidatie

In het volgende voorbeeld interpreteert API Management aanvragen met een lege inhoudstypeheader of aanvragen met een inhoudstypeheader application/hal+json als aanvragen met het inhoudstype application/json. Vervolgens voert API Management de validatie uit in de detectiemodus op basis van een schema dat is gedefinieerd voor het application/json inhoudstype in de API-definitie. Berichten met nettoladingen die groter zijn dan 100 kB, worden geblokkeerd. Aanvragen met aanvullende eigenschappen worden geblokkeerd, zelfs als het veld van additionalProperties het schema is geconfigureerd om aanvullende eigenschappen toe te staan.

<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-schemavalidatie

In het volgende voorbeeld interpreteert API Management elke aanvraag als een aanvraag met het inhoudstype (het inhoudstype application/soap+xml dat wordt gebruikt door SOAP 1.2 API's), ongeacht het binnenkomende inhoudstype. De aanvraag kan binnenkomen met een lege inhoudstypeheader, inhoudstypeheader van text/xml (gebruikt door SOAP 1.1 API's) of een andere inhoudstypeheader. Vervolgens extraheert API Management de XML-nettolading van de SOAP-envelop en voert de validatie uit in de preventiemodus op basis van het schema met de naam 'myschema'. Berichten met nettoladingen die groter zijn dan 100 kB, worden geblokkeerd.

<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>

Validatiefouten

API Management genereert inhoudsvalidatiefouten in de volgende indeling:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

De volgende tabel bevat alle mogelijke fouten van het validatiebeleid.

  • Details: Kan worden gebruikt om fouten te onderzoeken. Niet bedoeld om openbaar te worden gedeeld.
  • Openbaar antwoord: Er is een fout geretourneerd naar de client. Lek geen implementatiedetails.

Wanneer een validatiebeleid de prevent actie opgeeft en er een fout optreedt, bevat het antwoord van API Management een HTTP-statuscode: 400 wanneer het beleid wordt toegepast in de binnenkomende sectie en 502 wanneer het beleid wordt toegepast in de uitgaande sectie.

Naam Type Validatieregel DETAILS Openbare reactie Actie
validate-content
RequestBody SizeLimit De hoofdtekst van de aanvraag is {size} bytes lang en overschrijdt de geconfigureerde limiet van {maxSize} bytes. De hoofdtekst van de aanvraag is {size} bytes lang en overschrijdt de limiet van {maxSize} bytes. detecteren/voorkomen
ResponseBody SizeLimit De hoofdtekst van het antwoord is {size} bytes lang en overschrijdt de geconfigureerde limiet van {maxSize} bytes. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{messageContentType} RequestBody Onbepaald Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. detecteren/voorkomen
{messageContentType} ResponseBody Onbepaald Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
ApiSchema Het schema van de API bestaat niet of kan niet worden omgezet. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
ApiSchema Het schema van de API geeft geen definities op. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{messageContentType} RequestBody/ResponseBody MissingDefinition Het schema van de API bevat geen definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{messageContentType} RequestBody IncorrectMessage De hoofdtekst van de aanvraag voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 De hoofdtekst van de aanvraag voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 detecteren/voorkomen
{messageContentType} ResponseBody IncorrectMessage De hoofdtekst van het antwoord voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
RequestBody ValidationException De hoofdtekst van de aanvraag kan niet worden gevalideerd voor het inhoudstype {messageContentType}.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
ResponseBody ValidationException De hoofdtekst van het antwoord kan niet worden gevalideerd voor het inhoudstype {messageContentType}.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter/PathParameter/RequestHeader Onbepaald Niet-opgegeven {padparameter/queryparameter/header} {paramName} is niet toegestaan. Niet-opgegeven {padparameter/queryparameter/header} {paramName} is niet toegestaan. detecteren/voorkomen
{headerName} ResponseHeader Onbepaald Niet-opgegeven header {headerName} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
ApiSchema Het schema van de API bestaat niet of kan niet worden omgezet. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
ApiSchema Api-schema geeft geen definities op. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition Het schema van de API bevat geen definitie {definitionName}, die is gekoppeld aan de {queryparameter/padparameter/header} {paramName}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage De aanvraag mag geen meerdere waarden bevatten voor de {queryparameter/padparameter/header} {paramName}. De aanvraag mag geen meerdere waarden bevatten voor de {queryparameter/padparameter/header} {paramName}. detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage Het antwoord mag niet meerdere waarden bevatten voor de header {headerName}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage De waarde van de {queryparameter/padparameter/header} {paramName} voldoet niet aan de definitie.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 De waarde van de {queryparameter/padparameter/header} {paramName} voldoet niet aan de definitie.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage De waarde van de header {headerName} voldoet niet aan de definitie.

{valError.Message} Lijn: {valError.LineNumber}, Positie: {valError.LinePosition}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage De waarde van de {queryparameter/padparameter/header} {paramName} kan niet worden geparseerd volgens de definitie.

{ex. Message}		 De waarde van de {queryparameter/padparameter/header} {paramName} kan niet worden geparseerd volgens de definitie.

{ex. Message}		 detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage De waarde van de header {headerName} kan niet worden geparseerd volgens de definitie. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError {Queryparameter/Padparameter/Header} {paramName} kan niet worden gevalideerd.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
{headerName} ResponseHeader ValidationError De header {headerName} kan niet worden gevalideerd.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen
validate-status-code
{status-code} StatusCode Onbepaald Antwoordstatuscode {status-code} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de API-eigenaar. detecteren/voorkomen

De volgende tabel bevat alle mogelijke redenwaarden van een validatiefout, samen met mogelijke berichtwaarden:

Reden Bericht
Ongeldige aanvraag {Details} voor contextvariabele {Openbaar antwoord} voor client
Antwoord is niet toegestaan {Details} voor contextvariabele {Openbaar antwoord} voor client

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: