Dela via

Verifiera parametrar

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

Principen validate-parameters validerar parametrarna för sidhuvud, fråga eller sökväg i begäranden mot API-schemat.

Viktigt!

Om du importerade ett API med en hanterings-API-version före 2021-01-01-previewkanske validate-parameters principen inte fungerar. Du kan behöva importera api: et igen med hjälp av hanterings-API-versionen 2021-01-01-preview eller senare.

Kommentar

Den maximala storleken på API-schemat som kan användas av den här valideringsprincipen är 4 MB. Om schemat överskrider den här gränsen returnerar valideringsprinciper fel vid körning. Kontakta supporten om du vill öka den.

Kommentar

Ange principens element och underordnade element i den ordning som anges i principbeskrivningen. För att hjälpa dig att konfigurera den här principen tillhandahåller portalen en guidad, formulärbaserad redigerare. Läs mer om hur du anger eller redigerar API Management-principer.

Principuttryck

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

Attribut

Attribut beskrivning Obligatoriskt Standardvärde
specified-parameter-action Åtgärd att utföra för begärandeparametrar som anges i API-schemat.

När värdet anges i elementet headers, queryeller path åsidosätter det värdet specified-parameter-action i elementet validate-parameters . Principuttryck tillåts.		 Ja Ej tillämpligt
unspecified-parameter-action Åtgärd att utföra för begärandeparametrar som inte anges i API-schemat.

När det anges i ett headerseller -element åsidosätter unspecified-parameter-action värdet i elementet validate-parameters query. Principuttryck tillåts.		 Ja Ej tillämpligt
errors-variable-name Namnet på variabeln i context.Variables för att logga valideringsfel till. Principuttryck tillåts inte. Nej Ej tillämpligt

Element

Name beskrivning Obligatoriskt
rubriker Lägg till det här elementet och en eller flera parameter underelement för att åsidosätta standardverifieringsåtgärder för vissa namngivna parametrar i begäranden. Om parametern anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå specified-parameter-action . Om parametern inte anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå unspecified-parameter-action . Nej
query Lägg till det här elementet och ett eller flera parameter underelement för att åsidosätta standardverifieringsåtgärder för vissa namngivna frågeparametrar i begäranden. Om parametern anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå specified-parameter-action . Om parametern inte anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå unspecified-parameter-action . Nej
path Lägg till det här elementet och ett eller flera parameter underelement för att åsidosätta standardverifieringsåtgärder för vissa URL-sökvägsparametrar i begäranden. Om parametern anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå specified-parameter-action . Om parametern inte anges i API-schemat åsidosätter det här värdet konfigurationen på högre nivå unspecified-parameter-action . Nej

Åtgärder

Innehållsvalideringsprinciperna innehåller ett eller flera attribut som anger en åtgärd, som API Management tar när en entitet verifieras i en API-begäran eller ett svar mot API-schemat.

  • En åtgärd kan anges för element som representeras i API-schemat och, beroende på principen, för element som inte representeras i API-schemat.

  • En åtgärd som anges i en princips underordnade element åsidosätter en åtgärd som angetts för dess överordnade element.

Tillgängliga åtgärder:

Åtgärd Description
bortse från Hoppa över validering.
hindra Blockera bearbetningen av begäran eller svar, logga det utförliga valideringsfelet och returnera ett fel. Bearbetningen avbryts när den första uppsättningen fel identifieras.
detect Loggvalideringsfel, utan att avbryta bearbetningen av begäran eller svar.

Användning

Användningsanteckningar

  • Den här principen kan bara användas en gång i ett principavsnitt.

Loggar

Information om valideringsfelen under principkörningen loggas till variabeln som anges i context.Variables errors-variable-name attributet i principens rotelement. När det konfigureras i en prevent åtgärd blockerar ett valideringsfel ytterligare bearbetning av förfrågningar eller svar och sprids även till egenskapen context.LastError .

Om du vill undersöka fel använder du en spårningsprincip för att logga felen från kontextvariabler till Application Insights.

Prestandaöverväganden

Att lägga till en valideringsprincip kan påverka API-dataflödet. Följande allmänna principer gäller:

  • Ju större API-schemastorlek desto lägre blir dataflödet.
  • Ju större nyttolast i en begäran eller ett svar, desto lägre blir dataflödet.
  • Storleken på API-schemat har en större inverkan på prestanda än storleken på nyttolasten.
  • Validering mot ett API-schema som är flera megabyte i storlek kan orsaka tidsgränser för begäran eller svar under vissa förhållanden. Effekten är mer uttalad i förbruknings- och utvecklarnivåerna för tjänsten.

Vi rekommenderar att du utför belastningstester med dina förväntade produktionsarbetsbelastningar för att utvärdera effekten av valideringsprinciper på API-dataflödet.

Exempel

I det här exemplet verifieras alla fråge- och sökvägsparametrar i förebyggande läge och rubriker i identifieringsläget. Verifieringen åsidosättas för flera rubrikparametrar:

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

Valideringsfel

API Management genererar innehållsverifieringsfel i följande format:

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

I följande tabell visas alla möjliga fel i valideringsprinciperna.

  • Information: Kan användas för att undersöka fel. Inte tänkt att delas offentligt.
  • Offentligt svar: Felet returnerades till klienten. Läcker inte implementeringsinformation.

När en valideringsprincip prevent anger åtgärden och genererar ett fel innehåller svaret från API Management en HTTP-statuskod: 400 när principen tillämpas i avsnittet inkommande trafik och 502 när principen tillämpas i avsnittet för utgående trafik.

Namn Typ Verifieringsuttryck Detaljer Offentligt svar Åtgärd
validate-content
RequestBody SizeLimit Begärandetexten är {size} byte lång och överskrider den konfigurerade gränsen på {maxSize} byte. Begärandetexten är {size} byte lång och överskrider gränsen på {maxSize} byte. identifiera/förhindra
ResponseBody SizeLimit Svarets brödtext är {size} byte lång och överskrider den konfigurerade gränsen på {maxSize} byte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody Ospecificerad Den ospecificerade innehållstypen {messageContentType} är inte tillåten. Den ospecificerade innehållstypen {messageContentType} är inte tillåten. identifiera/förhindra
{messageContentType} ResponseBody Ospecificerad Den ospecificerade innehållstypen {messageContentType} är inte tillåten. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API:ets schema finns inte eller så gick det inte att matcha det. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API:s schema anger inte definitioner. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody/ResponseBody MissingDefinition API:s schema innehåller inte definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody IncorrectMessage Brödtexten i begäran överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 Brödtexten i begäran överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 identifiera/förhindra
{messageContentType} ResponseBody IncorrectMessage Brödtexten i svaret överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
RequestBody ValidationException Det går inte att verifiera brödtexten i begäran för innehållstypen {messageContentType}.

{undantagsinformation}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ResponseBody ValidationException Det går inte att verifiera svarets brödtext för innehållstypen {messageContentType}.

{undantagsinformation}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
validate-parameters/validate-headers
{paramName} / {headerName} QueryParameter/PathParameter/RequestHeader Ospecificerad Ospecificerad {path parameter/frågeparameter/header} {paramName} tillåts inte. Ospecificerad {path parameter/frågeparameter/header} {paramName} tillåts inte. identifiera/förhindra
{headerName} ResponseHeader Ospecificerad Ospecificerad rubrik {headerName} tillåts inte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API:ets schema finns inte eller så gick det inte att lösa det. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API-schemat anger inte definitioner. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader/ResponseHeader MissingDefinition API:s schema innehåller inte definitionen {definitionName}, som är associerad med {frågeparametern/sökvägsparametern/header} {paramName}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Begäran får inte innehålla flera värden för {frågeparametern/sökvägsparametern /header} {paramName}. Begäran får inte innehålla flera värden för {frågeparametern/sökvägsparametern /header} {paramName}. identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Svaret får inte innehålla flera värden för huvudet {headerName}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Värdet för {frågeparametern/sökvägsparametern/huvudet} {paramName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 Värdet för {frågeparametern/sökvägsparametern /header} {paramName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Värdet för rubriken {headerName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Värdet för {frågeparametern/sökvägsparametern /header} {paramName} kan inte parsas enligt definitionen.

{ex. Meddelande}		 Värdet för {frågeparametern/sökvägsparametern/huvudet} {paramName} kunde inte parsas enligt definitionen.

{ex. Meddelande}		 identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Det gick inte att parsa värdet för rubriken {headerName} enligt definitionen. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError {Frågeparameter/Sökvägsparameter/Rubrik} Det går inte att verifiera {paramName}.

{undantagsinformation}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{headerName} ResponseHeader ValidationError Det går inte att verifiera rubriken {headerName}.

{undantagsinformation}		 Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
validate-status-code
{statuskod} StatusCode Ospecificerad Svarsstatuskoden {status-code} är inte tillåten. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra

I följande tabell visas alla möjliga orsaksvärden för ett valideringsfel tillsammans med möjliga meddelandevärden:

Anledning Meddelande
Felaktig begäran {Details} för kontextvariabeln {Public response} för klienten
Svar tillåts inte {Details} för kontextvariabeln {Public response} för klienten

Relaterat innehåll

Mer information om hur du arbetar med principer finns i: