Sdílet prostřednictvím

Ověření parametrů

  • Článek

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

Zásada validate-parameters ověří parametry hlavičky, dotazu nebo cesty v požadavcích na schéma rozhraní API.

Důležité

Pokud jste naimportovali rozhraní API s použitím verze rozhraní API pro správu před tím 2021-01-01-preview, validate-parameters nemusí zásady fungovat. Možná budete muset rozhraní API znovu importovat pomocí verze 2021-01-01-preview rozhraní API pro správu nebo novější.

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.

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

Atributy

Atribut Popis Požaduje se Výchozí
specified-parameter-action Akce , která se má provést pro parametry požadavku zadané ve schématu rozhraní API

Pokud je hodnota zadaná v elementu headers, querynebo path element, přepíše hodnotu specified-parameter-action v elementu validate-parameters . Výrazy zásad jsou povolené.		 Yes –
nezadaná akce parametru Akce , která se má provést pro parametry požadavku, které nejsou zadané ve schématu rozhraní API

Pokud je tato hodnota zadaná v elementu headersnebo query prvku, přepíše hodnotu unspecified-parameter-action v elementu validate-parameters . 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
záhlaví Přidejte tento prvek a jeden nebo více parameter dílčích prvků pro přepsání výchozích ověřovacích akcí pro určité pojmenované parametry v požadavcích. Pokud je parametr zadán ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně specified-parameter-action . Pokud parametr není zadaný ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně unspecified-parameter-action . No
query Přidejte tento prvek a jeden nebo více parameter dílčích prvků, které přepíší výchozí ověřovací akce pro určité pojmenované parametry dotazu v požadavcích. Pokud je parametr zadán ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně specified-parameter-action . Pokud parametr není zadaný ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně unspecified-parameter-action . No
path Přidejte tento prvek a jeden nebo více parameter dílčích prvků, které přepíší výchozí ověřovací akce pro určité parametry cesty URL v požadavcích. Pokud je parametr zadán ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně specified-parameter-action . Pokud parametr není zadaný ve schématu rozhraní API, tato hodnota přepíše konfiguraci vyšší úrovně unspecified-parameter-action . No

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í

Poznámky k využití

  • Tuto zásadu je možné v oddílu zásad použít jenom jednou.

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.

Příklad

V tomto příkladu jsou všechny parametry dotazu a cesty ověřeny v režimu prevence a hlaviček v režimu detekce. Ověření se přepíše pro několik parametrů hlaviček:

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

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

Související obsah

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