Verifiera innehåll

Artikel
08/30/2024

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" case-insensitive-property-names="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: 4 MB. 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 `type` `application/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
case-insensitive-property-names	Boolesk. För ett JSON-schema anger om du vill jämföra egenskapsnamn för JSON-objekt utan hänsyn till skiftläge. - `true`: jämför egenskapsnamn skiftläge okänsligt. - `false`: jämför egenskapsnamn skiftläge känsligt.	Nej	falskt

Å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

Principavsnitt: inkommande, utgående, vid fel
Principomfattningar: global, arbetsyta, produkt, API, åtgärd
Gatewayer: klassisk, v2, förbrukning, lokalt installerad, arbetsyta

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.

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

I portalen navigerar du till din API Management-instans.
I avsnittet API:er i den vänstra menyn väljer du Scheman>+ Lägg till.
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.

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

Innehållsverifiering

Mer information om hur du arbetar med principer finns i:

Självstudie: Transformera och skydda ditt API
Principreferens för en fullständig lista över principinstruktioner och deras inställningar
Principuttryck
Ange eller redigera principer
Återanvända principkonfigurationer
Lagringsplats för principfragment
Skapa principer med Microsoft Copilot i Azure

Dela via

Verifiera innehåll

Vilket innehåll som verifieras

Principuttryck

Attribut

Element

content-type-map-attribut

content-type-map-elements

innehållsattribut

Åtgärder

Användning

Loggar

Prestandaöverväganden

Scheman för innehållsverifiering

Exempel

JSON-schemavalidering

Verifiering av SOAP-schema

Valideringsfel

Feedback

Ytterligare resurser

Dela via

Verifiera innehåll

Vilket innehåll som verifieras

Principuttryck

Attribut

Element

content-type-map-attribut

content-type-map-elements

innehållsattribut

Åtgärder

Användning

Loggar

Prestandaöverväganden

Scheman för innehållsverifiering

Exempel

JSON-schemavalidering

Verifiering av SOAP-schema

Valideringsfel

Relaterade principer

Relaterat innehåll

Feedback

Ytterligare resurser