Delen via

Parameters valideren

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Het validate-parameters beleid valideert de header-, query- of padparameters in aanvragen op basis van het API-schema.

Belangrijk

Als u een API hebt geïmporteerd met behulp van een management-API-versie vóór 2021-01-01-preview, werkt het validate-parameters beleid mogelijk niet. Mogelijk moet u uw API opnieuw importeren met behulp van de management-API-versie 2021-01-01-preview of hoger.

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.

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

Kenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
specified-parameter-action Actie die moet worden uitgevoerd voor aanvraagparameters die zijn opgegeven in het API-schema.

Wanneer de waarde wordt opgegeven in een headers, queryof path element, wordt de waarde in specified-parameter-action het validate-parameters element overschreven. Beleidsexpressies zijn toegestaan.		 Ja N.v.t.
unspecified-parameter-action Actie die moet worden uitgevoerd voor aanvraagparameters die niet zijn opgegeven in het API-schema.

Wanneer deze wordt opgegeven in een headersof query element, overschrijft de waarde van unspecified-parameter-action het validate-parameters element. 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
headers Voeg dit element en een of meer parameter subelementen toe om standaardvalidatieacties voor bepaalde benoemde parameters in aanvragen te overschrijven. Als de parameter is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau specified-parameter-action . Als de parameter niet is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau unspecified-parameter-action . Nee
query Voeg dit element en een of meer parameter subelementen toe om standaardvalidatieacties voor bepaalde benoemde queryparameters in aanvragen te overschrijven. Als de parameter is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau specified-parameter-action . Als de parameter niet is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau unspecified-parameter-action . Nee
path Voeg dit element en een of meer parameter subelementen toe om standaardvalidatieacties voor bepaalde URL-padparameters in aanvragen te overschrijven. Als de parameter is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau specified-parameter-action . Als de parameter niet is opgegeven in het API-schema, overschrijft deze waarde de configuratie op een hoger niveau unspecified-parameter-action . Nee

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

Gebruiksnotities

  • Dit beleid kan slechts eenmaal worden gebruikt in een beleidssectie.

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.

Opmerking

In dit voorbeeld worden alle query- en padparameters gevalideerd in de preventiemodus en headers in de detectiemodus. Validatie wordt overschreven voor verschillende headerparameters:

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

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: