Ověření obsahu

Článek
08/30/2024

PLATÍ PRO: Všechny úrovně služby API Management

Zásada validate-content ověří velikost nebo obsah textu požadavku nebo odpovědi na základě jednoho nebo více podporovaných schémat.

Následující tabulka ukazuje formáty schématu a typy obsahu požadavků nebo odpovědí, které zásady podporují. Hodnoty typu obsahu nerozlišují malá a velká písmena.

Formát	Typy obsahu
JSON	Příklady: `application/json` `application/hal+json`
XML	Příklad: `application/xml`
SOAP	Povolené hodnoty: `application/soap+xml` pro rozhraní API SOAP 1.2 `text/xml` pro rozhraní API SOAP 1.1

Poznámka:

Maximální velikost schématu rozhraní API, které lze použít touto zásadou ověřování, je 4 MB. Pokud schéma tento limit překročí, zásady ověřování vrátí chyby za běhu. Pokud ho chcete zvýšit, obraťte se na podporu.

Jaký obsah je ověřený

Zásada ověří následující obsah v požadavku nebo odpovědi na základě schématu:

Přítomnost všech požadovaných vlastností.
Přítomnost nebo absence dalších vlastností, pokud má schéma nastaveno additionalProperties pole. Lze přepsat atributem allow-additional-properties .
Typy všech vlastností. Pokud například schéma určuje vlastnost jako celé číslo, požadavek (nebo odpověď) musí obsahovat celé číslo a ne jiný typ, například řetězec.
Formát vlastností, pokud je zadán ve schématu – například regulární výraz (pokud pattern je zadán klíčové slovo), minimum pro celá čísla atd.

Tip

Příklady omezení vzoru regulárních výrazů, která se dají použít ve schématech, najdete v tématu Úložiště regulárních výrazů ověřování OWASP.

Poznámka:

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Portál poskytuje průvodce editorem založeným na formulářích, který vám pomůže s konfigurací této zásady. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady služby API Management.

Prohlášení o zásadách

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

Atributy

Atribut	Popis	Požaduje se	Výchozí
nezadaná akce typu obsahu	Akce , která se má provést u požadavků nebo odpovědí s typem obsahu, který není zadaný ve schématu rozhraní API Výrazy zásad jsou povolené.	Yes	–
max-size	Maximální délka textu požadavku nebo odpovědi v bajtech, zaškrtnutá v hlavičce `Content-Length` . Pokud je text požadavku nebo text odpovědi komprimovaný, jedná se o dekompresovanou délku. Maximální povolená hodnota: 4 MB. Výrazy zásad jsou povolené.	Yes	–
akce s překročením velikosti	Akce , která se má provést pro požadavky nebo odpovědi, jejichž text překračuje velikost uvedenou v `max-size`. Výrazy zásad jsou povolené.	Yes	–
errors-variable-name	Název proměnné `context.Variables` , do které se protokoluje chyby ověření. Výrazy zásad nejsou povolené.	No	–

Elementy

Název	Popis	Povinní účastníci
content-type-map	Přidejte tento prvek pro mapování typu obsahu příchozího požadavku nebo odpovědi na jiný typ obsahu, který se používá k aktivaci ověření.	No
content	Přidejte jeden nebo více těchto prvků pro ověření typu obsahu v požadavku nebo odpovědi nebo mapovaného typu obsahu a provedení zadané akce.	No

atributy mapování typu obsahu

Atribut	Popis	Požaduje se	Výchozí
any-content-type-value	Typ obsahu používaný k ověření textu požadavku nebo odpovědi bez ohledu na typ příchozího obsahu. Výrazy zásad nejsou povolené.	No	–
missing-content-type-value	Typ obsahu používaný k ověření textu požadavku nebo odpovědi, pokud typ příchozího obsahu chybí nebo je prázdný. Výrazy zásad nejsou povolené.	No	–

content-type-map-elements

Název	Popis	Povinní účastníci
type	Přidejte jeden nebo více těchto prvků pro mapování příchozího typu obsahu na typ obsahu, který se používá k ověření textu požadavku nebo odpovědi. Slouží `from` k zadání známého typu příchozího obsahu nebo použití `when` s výrazem zásady k určení libovolného příchozího typu obsahu, který odpovídá podmínce. Přepíše mapování v `any-content-type-value` zadaném formátu a `missing-content-type-value`, pokud je zadáno.	No

atributy obsahu

Atribut	Popis	Požaduje se	Výchozí
type	Typ obsahu, pro který se má provést ověření textu, kontrola hlavičky typu obsahu nebo hodnota namapovaná v `content-type-mapping`případě, že je zadána. Pokud je prázdný, vztahuje se na každý typ obsahu zadaný ve schématu rozhraní API. Pokud chcete ověřit požadavky a odpovědi SOAP (`validate-as` atribut nastavený na soap), nastavte `type` na `application/soap+xml` rozhraní API SOAP 1.2 nebo `text/xml` pro rozhraní API SOAP 1.1.	No	–
validate-as	Ověřovací modul, který se má použít k ověření textu požadavku nebo odpovědi s odpovídajícím `type`kódem . Podporované hodnoty: "json", "xml", "soap". Při zadání soap se XML z požadavku nebo odpovědi extrahuje z obálky SOAP a ověří se vůči schématu XML.	Yes	–
schema-id	Název existujícího schématu přidaného do instance služby API Management pro ověření obsahu Pokud není zadáno, použije se výchozí schéma z definice rozhraní API.	No	–
odkaz schématu	Pro schéma JSON zadané v `schema-id`volitelném odkazu na platnou místní cestu odkazu v dokumentu JSON. Příklad: `#/components/schemas/address`. Atribut by měl vrátit objekt JSON, který služba API Management zpracovává jako platné schéma JSON. Pro schéma `schema-ref` XML není podporován a jakýkoli element schématu nejvyšší úrovně lze použít jako kořen požadavku XML nebo datové části odpovědi. Ověření zkontroluje, že všechny elementy začínající z kořene datové části požadavku XML nebo odpovědi odpovídají zadanému schématu XML.	No	–
allow-additional-properties	Logický. U schématu JSON určuje, jestli se má implementovat přepsání `additionalProperties` modulu runtime hodnoty nakonfigurované ve schématu: - `true`: Povolit další vlastnosti v textu požadavku nebo odpovědi, i když je pole schématu `additionalProperties` JSON nakonfigurované tak, aby nepovolovaly další vlastnosti. - `false`: Nepovolujte v textu požadavku nebo odpovědi další vlastnosti, i když je pole schématu `additionalProperties` JSON nakonfigurované tak, aby umožňovalo další vlastnosti. Pokud atribut není zadaný, zásada ověří další vlastnosti podle konfigurace `additionalProperties` pole ve schématu.	No	–
Case-insensitive-property-names	Logický. U schématu JSON určuje, jestli se mají porovnávat názvy vlastností objektů JSON bez ohledu na velikost písmen. - `true`: porovnávání názvů vlastností nerozlišuje malá a velká písmena. - `false`: rozlišovat malá a velká písmena názvů vlastností.	No	false (nepravda)

Akce

Zásady ověřování obsahu zahrnují jeden nebo více atributů, které určují akci, kterou služba API Management provádí při ověřování entity v požadavku rozhraní API nebo odpovědi vůči schématu rozhraní API.

Pro elementy, které jsou reprezentované ve schématu rozhraní API, může být zadána akce a v závislosti na zásadách pro elementy, které nejsou reprezentovány ve schématu rozhraní API.
Akce zadaná v podřízené elementu zásady přepíše akci zadanou pro nadřazenou položku.

Dostupné akce:

Akce	Popis
ignorovat	Přeskočte ověření.
zabránit	Zablokujte zpracování požadavku nebo odpovědi, zakažte podrobnou chybu ověření a vraťte chybu. Zpracování se přeruší při zjištění první sady chyb.
zjistit	Chyby ověření protokolu bez přerušení zpracování požadavků nebo odpovědí

Využití

Oddíly zásad: příchozí, odchozí, při chybě
Obory zásad: globální, pracovní prostor, produkt, rozhraní API, operace
Brány: Classic, v2, consumption, self-host, workspace

Protokoly

Podrobnosti o chybách ověřování během provádění zásad jsou zaznamenány do proměnné zadané context.Variables v errors-variable-name atributu v kořenovém elementu zásady. Při konfiguraci v prevent akci blokuje chyba ověření další zpracování požadavku nebo odpovědi a je také rozšířena do context.LastError vlastnosti.

K prošetření chyb použijte zásadu trasování k protokolování chyb z kontextových proměnných do Application Insights.

Vliv na výkon

Přidání zásady ověření může mít vliv na propustnost rozhraní API. Platí následující obecné principy:

Čím větší je velikost schématu rozhraní API, tím nižší bude propustnost.
Čím větší je datová část v požadavku nebo odpovědi, tím nižší bude propustnost.
Velikost schématu rozhraní API má větší vliv na výkon než velikost datové části.
Ověření vůči schématu rozhraní API, které má velikost několika megabajtů, může způsobit vypršení časového limitu požadavků nebo odpovědí za určitých podmínek. Účinek je výraznější v úrovních Consumption a Developer služby.

Doporučujeme provádět zátěžové testy s očekávanými produkčními úlohami, abyste posoudili dopad zásad ověřování na propustnost rozhraní API.

Schémata pro ověření obsahu

Ve výchozím nastavení používá ověřování obsahu požadavku nebo odpovědi schémata JSON nebo XML z definice rozhraní API. Tato schémata je možné zadat ručně nebo generovat automaticky při importu rozhraní API ze specifikace OpenAPI nebo WSDL do služby API Management.

validate-content Pomocí zásad můžete volitelně ověřit jedno nebo více schémat JSON nebo XML, která jste přidali do instance služby API Management a která nejsou součástí definice rozhraní API. Schéma, které přidáte do služby API Management, je možné opakovaně používat v mnoha rozhraních API.

Přidání schématu do instance služby API Management pomocí webu Azure Portal:

Na portálu přejděte do vaší instance služby API Management.
V části Rozhraní API v nabídce vlevo vyberte Schémata> + Přidat.
V okně Vytvořit schéma udělejte toto:
1. Zadejte název (ID) schématu.
2. V typu schématu vyberte JSON nebo XML.
3. Zadejte popis.
4. V metodě Create proveďte jednu z následujících věcí:
  - Vyberte Vytvořit nový a zadejte nebo vložte schéma.
  - Vyberte Importovat ze souboru nebo Importovat z adresy URL a zadejte umístění schématu.
    
    Poznámka:
    
    Pokud chcete importovat schéma z adresy URL, musí být schéma přístupné přes internet z prohlížeče.
5. Zvolte Uložit.

Služba API Management přidá prostředek schématu do relativního identifikátoru URI /schemas/<schemaId>a schéma se zobrazí v seznamu na stránce Schémata . Vyberte schéma pro zobrazení jeho vlastností nebo úprav v editoru schématu.

Poznámka:

Schéma může křížově odkazovat na jiné schéma, které je přidáno do instance služby API Management. Zahrnout například schéma XML přidané do služby API Management pomocí elementu podobného:

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

Tip

Opensourcové nástroje pro překlad odkazů na schématu WSDL a XSD a dávkového importu generovaných schémat do služby API Management jsou k dispozici na GitHubu.

Příklady

Ověřování schématu JSON

V následujícím příkladu služba API Management interpretuje požadavky s prázdnou hlavičkou typu obsahu nebo požadavky s hlavičkou application/hal+json typu obsahu jako požadavky s typem application/jsonobsahu . Pak služba API Management provede ověření v režimu detekce vůči schématu definovanému application/json pro typ obsahu v definici rozhraní API. Zprávy s datovými částmi většími než 100 kB jsou blokované. Požadavky obsahující další vlastnosti jsou blokované, i když je pole schématu additionalProperties nakonfigurované tak, aby umožňovalo další vlastnosti.

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

Ověřování schématu SOAP

V následujícím příkladu služba API Management interpretuje jakýkoli požadavek jako požadavek s typem application/soap+xml obsahu (typ obsahu, který používá rozhraní API SOAP 1.2), bez ohledu na typ příchozího obsahu. Požadavek by mohl přijít s prázdnou hlavičkou typu obsahu, hlavičkou text/xml typu obsahu (používanou rozhraními API SOAP 1.1) nebo jinou hlavičkou typu obsahu. Služba API Management pak extrahuje datovou část XML z obálky SOAP a provede ověření v režimu prevence proti schématu s názvem myschema. Zprávy s datovými částmi většími než 100 kB jsou blokované.

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

Chyby ověření

Služba API Management generuje chyby ověření obsahu v následujícím formátu:

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

Následující tabulka uvádí všechny možné chyby zásad ověřování.

Podrobnosti: Je možné použít k prošetření chyb. Nemělo by se sdílet veřejně.
Veřejná odpověď: Chyba vrácená klientovi. Nedochází k úniku podrobností implementace.

Když zásada ověření určuje prevent akci a vygeneruje chybu, odpověď ze služby API Management obsahuje stavový kód HTTP: 400, když se zásada použije v příchozí části, a 502, když se zásada použije v odchozím oddílu.

Název	Typ	Ověřovací pravidlo	Podrobnosti	Veřejná odpověď	Akce
validate-content
	RequestBody	SizeLimit	Text požadavku je {size} bajtů dlouhý a překračuje nakonfigurovaný limit počtu bajtů {maxSize}.	Text požadavku je {size} bajtů dlouhý a překračuje limit {maxSize} bajtů.	detekce nebo prevence
	ResponseBody	SizeLimit	Text odpovědi má délku {size} bajtů a překračuje nakonfigurovaný limit počtu bajtů {maxSize}.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{messageContentType}	RequestBody	Nespecifikovaný	Zadaný typ obsahu {messageContentType} není povolený.	Zadaný typ obsahu {messageContentType} není povolený.	detekce nebo prevence
{messageContentType}	ResponseBody	Nespecifikovaný	Zadaný typ obsahu {messageContentType} není povolený.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	ApiSchema		Schéma rozhraní API neexistuje nebo ho nelze přeložit.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	ApiSchema		Schéma rozhraní API nezadává definice.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	Schéma rozhraní API neobsahuje definici {definitionName}, která je přidružena k typu obsahu {messageContentType}.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{messageContentType}	RequestBody	Nesprávná zpráva	Text požadavku neodpovídá definici {definitionName}, která je přidružena k typu obsahu {messageContentType}. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	Text požadavku neodpovídá definici {definitionName}, která je přidružena k typu obsahu {messageContentType}. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	detekce nebo prevence
{messageContentType}	ResponseBody	Nesprávná zpráva	Text odpovědi neodpovídá definici {definitionName}, která je přidružena k typu obsahu {messageContentType}. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	RequestBody	ValidationException	Text požadavku nelze ověřit pro typ obsahu {messageContentType}. {podrobnosti o výjimce}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	ResponseBody	ValidationException	Text odpovědi nelze ověřit pro typ obsahu {messageContentType}. {podrobnosti o výjimce}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	Nespecifikovaný	Zadaný parametr {path / parametr dotazu / header} {paramName} není povolený.	Zadaný parametr {path / parametr dotazu / header} {paramName} není povolený.	detekce nebo prevence
{headerName}	ResponseHeader	Nespecifikovaný	Nezadaná hlavička {headerName} není povolená.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	ApiSchema		Schéma rozhraní API neexistuje nebo ho nelze přeložit.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
	ApiSchema		Schéma rozhraní API nezadává definice.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	Schéma rozhraní API neobsahuje definici {definitionName}, která je přidružená k {parametru dotazu / parametru cesty / header} {paramName}.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{paramName}	QueryParameter / PathParameter / RequestHeader	Nesprávná zpráva	Požadavek nemůže obsahovat více hodnot pro {parametr dotazu / parametr cesty / header} {paramName}.	Požadavek nemůže obsahovat více hodnot pro {parametr dotazu / parametr cesty / header} {paramName}.	detekce nebo prevence
{headerName}	ResponseHeader	Nesprávná zpráva	Odpověď nemůže obsahovat více hodnot hlavičky {headerName}.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{paramName}	QueryParameter / PathParameter / RequestHeader	Nesprávná zpráva	Hodnota parametru dotazu / parametru cesty / header} {paramName} neodpovídá definici. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	Hodnota parametru dotazu / parametru cesty / header} {paramName} neodpovídá definici. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	detekce nebo prevence
{headerName}	ResponseHeader	Nesprávná zpráva	Hodnota hlavičky {headerName} neodpovídá definici. Řádek {valError.Message}: {valError.LineNumber}, pozice: {valError.LinePosition}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{paramName}	QueryParameter / PathParameter / RequestHeader	Nesprávná zpráva	Hodnotu parametru dotazu / parametru cesty / header} {paramName} nelze analyzovat podle definice. {ex. Zpráva}	Hodnotu parametru dotazu / parametru cesty / header} {paramName} nelze analyzovat podle definice. {ex. Zpráva}	detekce nebo prevence
{headerName}	ResponseHeader	Nesprávná zpráva	Hodnotu hlavičky {headerName} nelze analyzovat podle definice.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{paramName}	QueryParameter / PathParameter / RequestHeader	Chyba ověření	{Parametr dotazu / Parametr cesty / Header} {paramName} nelze ověřit. {podrobnosti o výjimce}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
{headerName}	ResponseHeader	Chyba ověření	Hlavičku {headerName} nelze ověřit. {podrobnosti o výjimce}	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence
validate-status-code
{status-code}	StatusCode	Nespecifikovaný	Stavový kód odpovědi {status-code} není povolen.	Požadavek nelze zpracovat kvůli vnitřní chybě. Obraťte se na vlastníka rozhraní API.	detekce nebo prevence

V následující tabulce jsou uvedeny všechny možné hodnoty důvodu chyby ověření spolu s možnými hodnotami zpráv:

Důvod	Zpráva
Chybný požadavek	{Details} pro kontextovou proměnnou, {Public response} pro klienta
Odpověď není povolena.	{Details} pro kontextovou proměnnou, {Public response} pro klienta

Ověření obsahu

Další informace o práci se zásadami najdete v tématech:

Kurz: Transformace a ochrana rozhraní API
Referenční informace o zásadách pro úplný seznam prohlášení o zásadách a jejich nastavení
Výrazy zásad
Nastavení nebo úprava zásad
Opakované použití konfigurací zásad
Úložiště fragmentů zásad
Sada nástrojů zásad služby Azure API Management
Vytváření zásad pomocí Microsoft Copilotu v Azure

Sdílet prostřednictvím

Ověření obsahu

Jaký obsah je ověřený

Prohlášení o zásadách

Atributy

Elementy

atributy mapování typu obsahu

content-type-map-elements

atributy obsahu

Akce

Využití

Protokoly

Vliv na výkon

Schémata pro ověření obsahu

Příklady

Ověřování schématu JSON

Ověřování schématu SOAP

Chyby ověření

Váš názor

Další materiály

Sdílet prostřednictvím

Ověření obsahu

Jaký obsah je ověřený

Prohlášení o zásadách

Atributy

Elementy

atributy mapování typu obsahu

content-type-map-elements

atributy obsahu

Akce

Využití

Protokoly

Vliv na výkon

Schémata pro ověření obsahu

Příklady

Ověřování schématu JSON

Ověřování schématu SOAP

Chyby ověření

Související zásady

Související obsah

Váš názor

Další materiály