Paraméterek érvényesítése

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

A validate-parameters szabályzat ellenőrzi a fejléc, a lekérdezés vagy az elérési út paramétereit az API-sémára irányuló kérelmekben.

Fontos

Ha korábban felügyeleti API-verzióval importált egy API-t, előfordulhat, hogy 2021-01-01-previewa validate-parameters szabályzat nem működik. Előfordulhat, hogy újra kell importálnia az API-t a felügyeleti API-verzióval vagy újabb verzióval 2021-01-01-preview .

Feljegyzés

Az érvényesítési szabályzat által használható API-séma maximális mérete 4 MB. Ha a séma túllépi ezt a korlátot, az érvényesítési szabályzatok hibát adnak vissza futásidőben. A növeléséhez forduljon az ügyfélszolgálathoz.

Feljegyzés

Állítsa be a szabályzat elemeit és gyermekelemeit a szabályzatutasításban megadott sorrendben. A szabályzat konfigurálásához a portál egy irányított, űrlapalapú szerkesztőt biztosít. További információ az API Management-szabályzatok beállításáról és szerkesztéséről.

Szabályzatutasítás

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

Attribútumok

Attribútum Leírás Kötelező Alapértelmezett
specified-parameter-action Az API-sémában megadott kérésparaméterek végrehajtására szolgáló művelet .

Ha egy headers, queryvagy path elem megadja, az érték felülbírálja az validate-parameters elem értékétspecified-parameter-action. A szabályzatkifejezések engedélyezettek.		 Igen n/a
unspecified-parameter-action Az API-sémában nem megadott kérésparaméterek esetében végrehajtandó művelet .

Ha egy vagy több headerselemben meg van adva, az érték felülbírálja az validate-parameters elem értékétunspecified-parameter-action.query A szabályzatkifejezések engedélyezettek.		 Igen n/a
errors-variable-name Annak a változónak a neve, amelybe context.Variables naplózni szeretné az érvényesítési hibákat. A szabályzatkifejezések nem engedélyezettek. Nem N.A.

Elemek

Név Leírás Kötelező
Fejlécek Adja hozzá ezt az elemet és egy vagy több parameter alelemet bizonyos elnevezett paraméterek alapértelmezett érvényesítési műveleteinek felülbírálásához a kérelmekben. Ha a paraméter az API-sémában van megadva, ez az érték felülírja a magasabb szintű specified-parameter-action konfigurációt. Ha a paraméter nincs megadva az API-sémában, ez az érték felülírja a magasabb szintű unspecified-parameter-action konfigurációt. Nem
Lekérdezés Adja hozzá ezt az elemet és egy vagy több parameter alelemet egyes elnevezett lekérdezési paraméterek alapértelmezett érvényesítési műveleteinek felülbírálásához a kérelmekben. Ha a paraméter az API-sémában van megadva, ez az érték felülírja a magasabb szintű specified-parameter-action konfigurációt. Ha a paraméter nincs megadva az API-sémában, ez az érték felülírja a magasabb szintű unspecified-parameter-action konfigurációt. Nem
ösvény Adja hozzá ezt az elemet és egy vagy több parameter alelemet, hogy felülbírálja bizonyos URL-elérési útparaméterek alapértelmezett érvényesítési műveleteit a kérelmekben. Ha a paraméter az API-sémában van megadva, ez az érték felülírja a magasabb szintű specified-parameter-action konfigurációt. Ha a paraméter nincs megadva az API-sémában, ez az érték felülírja a magasabb szintű unspecified-parameter-action konfigurációt. Nem

Műveletek

A tartalomérvényesítési szabályzatok egy vagy több olyan attribútumot tartalmaznak, amelyek egy műveletet határoznak meg, amelyet az API Management hajt végre egy entitás API-kérésben vagy -válaszban való érvényesítésekor az API-séma alapján.

  • Műveletet lehet megadni az API-sémában szereplő elemekhez, valamint a szabályzattól függően az API-sémában nem szereplő elemekhez.

  • A házirend gyermekelemében megadott művelet felülírja a szülőhöz megadott műveletet.

Elérhető műveletek:

Művelet Leírás
Figyelmen kívül hagyja Érvényesítés kihagyása.
Megakadályozzák Tiltsa le a kérés- vagy válaszfeldolgozást, naplózza a részletes érvényesítési hibát, és küldjön vissza egy hibát. A feldolgozás megszakad az első hibakészlet észlelésekor.
detect Naplóérvényesítési hibák a kérések vagy válaszfeldolgozás megszakítása nélkül.

Használat

Használati megjegyzések

  • Ez a szabályzat csak egyszer használható egy szabályzatszakaszban.

Naplók

A szabályzat végrehajtása során fellépő érvényesítési hibák részleteit a rendszer naplózza a errors-variable-name szabályzat gyökérelemében található attribútumban context.Variables megadott változóba. Ha egy prevent műveletben konfigurálva van, az érvényesítési hiba blokkolja a további kérések vagy válaszok feldolgozását, és a tulajdonságra context.LastError is propagálja.

A hibák vizsgálatához használjon nyomkövetési szabályzatot a környezeti változók hibáinak az Alkalmazás Elemzések való naplózásához.

A teljesítményre gyakorolt hatások

Az érvényesítési szabályzat hozzáadása hatással lehet az API átviteli sebességére. A következő általános alapelvek érvényesek:

  • Minél nagyobb az API-séma mérete, annál alacsonyabb lesz az átviteli sebesség.
  • Minél nagyobb a hasznos adat egy kérelemben vagy válaszban, annál alacsonyabb lesz az átviteli sebesség.
  • Az API-séma mérete nagyobb hatással van a teljesítményre, mint a hasznos adat méretére.
  • A több megabájt méretű API-sémán való érvényesítés bizonyos feltételek mellett kérés- vagy válaszidőkorlátokat okozhat. A hatás hangsúlyosabb a szolgáltatás használat ésfejlesztői szintjeiben.

Javasoljuk, hogy a várt éles számítási feladatokkal végezzen terhelésteszteket az érvényesítési szabályzatok API-átviteli sebességre gyakorolt hatásának felméréséhez.

Példa

Ebben a példában a rendszer az összes lekérdezési és elérési útvonalparamétert érvényesíti a megelőzési módban, a fejléceket pedig észlelési módban. Az ellenőrzés felül van bírálva több fejlécparaméter esetében:

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

Ellenőrzési hibák

Az API Management a következő formátumban hoz létre tartalomérvényesítési hibákat:

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

Az alábbi táblázat az érvényesítési szabályzatok összes lehetséges hibáját felsorolja.

  • Részletek: A hibák kivizsgálására használható. Nem nyilvános megosztásra szánták.
  • Nyilvános válasz: Az ügyfélnek visszaadott hiba. Nem szivárognak ki a megvalósítás részletei.

Ha egy érvényesítési szabályzat megadja a prevent műveletet, és hibát okoz, az API management válasza tartalmaz egy HTTP-állapotkódot: 400, ha a szabályzatot a bejövő szakaszban alkalmazza, és 502, amikor a szabályzatot a kimenő szakaszban alkalmazza a rendszer.

Név Típus Érvényesítési szabály Részletek Nyilvános válasz Művelet
tartalom ellenőrzése
RequestBody SizeLimit A kérelem törzse {size} bájt hosszú, és túllépi a (z) {maxSize} bájtok konfigurált korlátját. A kérelem törzse {size} bájt hosszú, és túllépi a {maxSize} bájtok korlátját. észlelés/megelőzés
ResponseBody SizeLimit A válasz törzse {size} bájt hosszú, és túllépi a (z) {maxSize} bájtok konfigurált korlátját. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{messageContentType} RequestBody Meghatározatlan A(z) {messageContentType} nem meghatározott tartalomtípus nem engedélyezett. A(z) {messageContentType} nem meghatározott tartalomtípus nem engedélyezett. észlelés/megelőzés
{messageContentType} ResponseBody Meghatározatlan A(z) {messageContentType} nem meghatározott tartalomtípus nem engedélyezett. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
ApiSchema Az API sémája nem létezik, vagy nem oldható fel. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
ApiSchema Az API sémája nem határoz meg definíciókat. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{messageContentType} RequestBody / ResponseBody MissingDefinition Az API sémája nem tartalmazza a(z) {definitionName} definíciót, amely a(z) {messageContentType} tartalomtípushoz van társítva. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{messageContentType} RequestBody IncorrectMessage A kérelem törzse nem felel meg a(z) {definitionName} definíciónak, amely a(z) {messageContentType} tartalomtípushoz van társítva.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 A kérelem törzse nem felel meg a(z) {definitionName} definíciónak, amely a(z) {messageContentType} tartalomtípushoz van társítva.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 észlelés/megelőzés
{messageContentType} ResponseBody IncorrectMessage A válasz törzse nem felel meg a(z) {definitionName} definíciónak, amely a(z) {messageContentType} tartalomtípushoz van társítva.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
RequestBody ValidationException A kérés törzse nem érvényesíthető a(z) {messageContentType} tartalomtípushoz.

{kivétel részletei}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
ResponseBody ValidationException A válasz törzse nem érvényesíthető a(z) {messageContentType} tartalomtípushoz.

{kivétel részletei}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
validate-parameters /validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader Meghatározatlan A(z) {elérési út paramétere/ lekérdezési paraméter/ fejléc} {paramName} nem engedélyezett. A(z) {elérési út paramétere/ lekérdezési paraméter/ fejléc} {paramName} nem engedélyezett. észlelés/megelőzés
{headerName} ResponseHeader Meghatározatlan A(z) {headerName} nem megadott fejléc nem engedélyezett. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
ApiSchema Az API sémája nem létezik, vagy nem oldható fel. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
ApiSchema Az API-séma nem határoz meg definíciókat. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition Az API sémája nem tartalmazza a(z) {definitionName} definíciót, amely a(z) {query parameter / path parameter / header} {paramName} paraméterhez van társítva. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage A kérelem nem tartalmazhat több értéket a(z) {query parameter/ path parameter / header} {paramName} paraméterhez. A kérelem nem tartalmazhat több értéket a(z) {query parameter/ path parameter / header} {paramName} paraméterhez. észlelés/megelőzés
{headerName} ResponseHeader IncorrectMessage A válasz nem tartalmazhat több értéket a(z) {headerName} fejléchez. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage A (z) {query parameter/ path parameter/header} {paramName} értéke nem felel meg a definíciónak.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 A(z) {query parameter/ path parameter/header} {paramName} értéke nem felel meg a definíciónak.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 észlelés/megelőzés
{headerName} ResponseHeader IncorrectMessage A(z) {headerName} fejléc értéke nem felel meg a definíciónak.

{valError.Message} Sor: {valError.LineNumber}, Pozíció: {valError.LinePosition}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage A(z) {query parameter/ path parameter/header} {paramName} paraméter értéke nem elemezhető a definíció szerint.

{ex. Üzenet}		 A(z) {query parameter/ path parameter/header} {paramName} paraméter értéke nem elemezhető a definíció szerint.

{ex. Üzenet}		 észlelés/megelőzés
{headerName} ResponseHeader IncorrectMessage A(z) {headerName} fejléc értéke nem elemezhető a definíció szerint. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{paramName} QueryParameter / PathParameter / RequestHeader ValidationError {Lekérdezési paraméter / Elérési út paraméter / Fejléc} A(z) {paramName} nem érvényesíthető.

{kivétel részletei}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
{headerName} ResponseHeader ValidationError A(z) {headerName} fejléc nem érvényesíthető.

{kivétel részletei}		 A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés
validate-status-code
{status-code} StatusCode Meghatározatlan A(z) {status-code} válaszállapotkód nem engedélyezett. A kérést belső hiba miatt nem sikerült feldolgozni. Lépjen kapcsolatba az API tulajdonosával. észlelés/megelőzés

Az alábbi táblázat az érvényesítési hiba összes lehetséges okértékét és a lehetséges üzenetértékeket sorolja fel:

Ok Üzenet
Hibás kérés {Details} a környezeti változóhoz, {Nyilvános válasz} az ügyfélhez
A válasz nem engedélyezett {Details} a környezeti változóhoz, {Nyilvános válasz} az ügyfélhez

Kapcsolódó tartalom

A szabályzatok használatával kapcsolatos további információkért lásd: