Verifiera innehåll

  • Artikel

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

Principen validate-content verifierar storleken eller innehållet i en begäran eller svarstext mot ett eller flera scheman som stöds.

I följande tabell visas schemaformat och innehållstyper för begäran eller svar som stöds av principen. Innehållstypvärden är skiftlägesokänsliga.

Format Innehållstyper
JSON Exempel: application/json
application/hal+json
XML Exempel: application/xml
SOAP Tillåtna värden: application/soap+xml för SOAP 1.2-API:er
text/xml för SOAP 1.1 API:er

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.

Vilket innehåll som verifieras

Principen validerar följande innehåll i begäran eller svaret mot schemat:

  • Förekomst av alla obligatoriska egenskaper.
  • Närvaro eller frånvaro av ytterligare egenskaper, om schemat har fältuppsättningen additionalProperties . Kan åsidosättas med attributet allow-additional-properties .
  • Typer av alla egenskaper. Om ett schema till exempel anger en egenskap som ett heltal måste begäran (eller svaret) innehålla ett heltal och inte en annan typ, till exempel en sträng.
  • Formatet för egenskaperna, om det anges i schemat , till exempel regex (om nyckelordet pattern har angetts), minimum för heltal och så vidare.

Dricks

Exempel på regex-mönsterbegränsningar som kan användas i scheman finns i OWASP Validation Regex Repository.

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

Attribut

Attribut beskrivning Obligatoriskt Standardvärde
unspecified-content-type-action Åtgärd att utföra för begäranden eller svar med en innehållstyp som inte anges i API-schemat. Principuttryck tillåts. Ja Ej tillämpligt
maxstorlek Maximal längd på brödtexten för begäran eller svaret i byte, markerat mot Content-Length rubriken. Om begärandetexten eller svarstexten komprimeras är det här värdet den dekomprimerade längden. Högsta tillåtna värde: 102 400 byte (100 KB). (Kontakta supporten om du behöver öka den här gränsen.) Principuttryck tillåts. Ja Ej tillämpligt
storleksförskredd åtgärd Åtgärd att utföra för begäranden eller svar vars brödtext överskrider den storlek som anges i max-size. 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
content-type-map Lägg till det här elementet för att mappa innehållstypen för den inkommande begäran eller svaret till en annan innehållstyp som används för att utlösa validering. Nej
innehåll Lägg till ett eller flera av dessa element för att verifiera innehållstypen i begäran eller svaret, eller den mappade innehållstypen, och utför den angivna åtgärden. Nej

content-type-map-attribut

Attribut beskrivning Obligatoriskt Standardvärde
any-content-type-value Innehållstyp som används för validering av brödtexten för en begäran eller ett svar, oavsett inkommande innehållstyp. Principuttryck tillåts inte. Nej Ej tillämpligt
missing-content-type-value Innehållstyp som används för validering av brödtexten i en begäran eller ett svar, när den inkommande innehållstypen saknas eller är tom. Principuttryck tillåts inte. Nej Ej tillämpligt

content-type-map-elements

Name beskrivning Obligatoriskt
type Lägg till ett eller flera av dessa element för att mappa en inkommande innehållstyp till en innehållstyp som används för validering av brödtexten i en begäran eller ett svar. Använd from för att ange en känd inkommande innehållstyp eller använd when med ett principuttryck för att ange en inkommande innehållstyp som matchar ett villkor. Åsidosätter mappningen i any-content-type-value och missing-content-type-value, om den anges. Nej

innehållsattribut

Attribut beskrivning Obligatoriskt Standardvärde
type Innehållstyp att köra brödtextvalidering för, markerad mot innehållstypshuvudet eller värdet som mappas i content-type-mapping, om det anges. Om den är tom gäller den för alla innehållstyper som anges i API-schemat.

För att verifiera SOAP-begäranden och -svar (validate-as attributet inställt på "soap"), inställt typeapplication/soap+xml på för SOAP 1.2-API:er eller text/xml för SOAP 1.1-API:er.		 Nej Ej tillämpligt
validate-as Valideringsmotor som ska användas för validering av brödtexten för en begäran eller ett svar med matchande type. Värden som stöds: "json", "xml", "soap".

När "soap" har angetts extraheras XML från begäran eller svaret från SOAP-kuvertet och verifieras mot ett XML-schema.		 Ja Ej tillämpligt
schema-id Namn på ett befintligt schema som lades till i API Management-instansen för innehållsverifiering. Om det inte anges används standardschemat från API-definitionen. Nej Ej tillämpligt
schema-ref För ett JSON-schema som anges i schema-id, valfri referens till en giltig lokal referenssökväg i JSON-dokumentet. Exempel: #/components/schemas/address. Attributet ska returnera ett JSON-objekt som API Management hanterar som ett giltigt JSON-schema.

För ett XML-schema schema-ref stöds inte och något schemaelement på den översta nivån kan användas som rot för XML-begäran eller svarsnyttolasten. Verifieringen kontrollerar att alla element som startar från XML-begäran eller svarsnyttolastens rot följer det angivna XML-schemat.		 Nej Ej tillämpligt
allow-additional-properties Boolesk. För ett JSON-schema anger om en körnings åsidosättning av värdet additionalProperties som konfigurerats i schemat ska implementeras:
- true: tillåt ytterligare egenskaper i begäran eller svarstexten, även om JSON-schemats fält har konfigurerats additionalProperties för att inte tillåta ytterligare egenskaper.
- false: Tillåt inte ytterligare egenskaper i begäran eller svarstexten, även om JSON-schemats fält har konfigurerats additionalProperties för att tillåta ytterligare egenskaper.

Om attributet inte har angetts validerar principen ytterligare egenskaper enligt konfigurationen additionalProperties av fältet i schemat.		 Nej Ej tillämpligt

Å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
Ignorera Hoppa över validering.
Förhindra 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

Loggar

Information om valideringsfelen under principkörningen loggas till variabeln som anges i context.Variableserrors-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.

Scheman för innehållsverifiering

Som standard använder validering av begäran- eller svarsinnehåll JSON- eller XML-scheman från API-definitionen. Dessa scheman kan anges manuellt eller genereras automatiskt när du importerar ett API från en OpenAPI- eller WSDL-specifikation till API Management.

Med hjälp av validate-content principen kan du eventuellt verifiera mot ett eller flera JSON- eller XML-scheman som du har lagt till i DIN API Management-instans och som inte ingår i API-definitionen. Ett schema som du lägger till i API Management kan återanvändas för många API:er.

Så här lägger du till ett schema i DIN API Management-instans med hjälp av Azure-portalen:

  1. I portalen navigerar du till din API Management-instans.

  2. I avsnittet API:er i den vänstra menyn väljer du Scheman>+ Lägg till.

  3. Gör följande i fönstret Skapa schema :

    1. Ange ett namn (ID) för schemat.
    2. I Schematyp väljer du JSON eller XML.
    3. Ange en beskrivning.
    4. Gör något av följande i Skapa-metoden:
      • Välj Skapa ny och ange eller klistra in schemat.
      • Välj Importera från fil eller Importera från URL och ange en schemaplats.

        Kommentar

        Om du vill importera ett schema från URL:en måste schemat vara tillgängligt via Internet från webbläsaren.

    5. Välj Spara.

    Skapa schema

API Management lägger till schemaresursen på den relativa URI: /schemas/<schemaId>n och schemat visas i listan på sidan Scheman . Välj ett schema för att visa dess egenskaper eller redigera i ett schemaredigerare.

Kommentar

Ett schema kan korsreferensa ett annat schema som läggs till i API Management-instansen. Inkludera till exempel ett XML-schema som lagts till i API Management med hjälp av ett element som liknar:

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

Dricks

Verktyg med öppen källkod för att matcha WSDL- och XSD-schemareferenser och för batchimportgenererade scheman till API Management är tillgängliga på GitHub.

Exempel

JSON-schemavalidering

I följande exempel tolkar API Management begäranden med ett tomt innehållstyphuvud eller begäranden med en innehållstyprubrik application/hal+json som begäranden med innehållstypen application/json. Sedan utför API Management verifieringen i identifieringsläget mot ett schema som definierats för application/json innehållstypen i API-definitionen. Meddelanden med nyttolaster som är större än 100 KB blockeras. Begäranden som innehåller ytterligare egenskaper blockeras, även om schemats fält har konfigurerats additionalProperties för att tillåta ytterligare egenskaper.

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

Verifiering av SOAP-schema

I följande exempel tolkar API Management alla begäranden som en begäran med innehållstypen application/soap+xml (innehållstypen som används av SOAP 1.2-API:er), oavsett inkommande innehållstyp. Begäran kan komma med ett tomt innehållstyphuvud, innehållstyprubrik text/xml (används av SOAP 1.1-API:er) eller en annan innehållstyprubrik. Sedan extraherar API Management XML-nyttolasten från SOAP-kuvertet och utför valideringen i förebyggande läge mot schemat med namnet "myschema". Meddelanden med nyttolaster som är större än 100 KB blockeras.

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

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 Ospecificerat Den ospecificerade innehållstypen {messageContentType} är inte tillåten. Den ospecificerade innehållstypen {messageContentType} är inte tillåten. identifiera/förhindra
{messageContentType} ResponseBody Ospecificerat 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 Ospecificerat 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 Ospecificerat 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 Ospecificerat 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: