Tartalom ellenőrzése

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

A validate-content szabályzat egy kérelem- vagy választörzs méretét vagy tartalmát egy vagy több támogatott sémán ellenőrzi.

Az alábbi táblázat a szabályzat által támogatott sémaformátumokat és kérés- vagy választartalom-típusokat mutatja be. A tartalomtípus értékei nem érzékenyek a kis- és nagybetűkre.

Formátum Tartalomtípusok
JSON Példák: application/json
application/hal+json
XML Példa: application/xml
SZAPPAN Engedélyezett értékek: application/soap+xml SOAP 1.2 API-khoz
text/xml SOAP 1.1 API-khoz

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.

Milyen tartalom van érvényesítve?

A szabályzat a következő tartalmakat érvényesíti a kérésben vagy a válaszban a sémával szemben:

  • Az összes szükséges tulajdonság jelenléte.
  • További tulajdonságok jelenléte vagy hiánya, ha a séma rendelkezik a additionalProperties mezőkészlettel. Felül lehet bírálni az allow-additional-properties attribútumot.
  • Az összes tulajdonság típusa. Ha például egy séma egy tulajdonságot egész számként ad meg, a kérésnek (vagy válasznak) egész számot kell tartalmaznia, nem pedig más típust, például sztringet.
  • A tulajdonságok formátuma, ha meg van adva a sémában – például regex (ha a pattern kulcsszó meg van adva), minimum egész számokhoz stb.

Tipp.

Példák a sémákban használható regex mintakorlátozásokra: OWASP Validation Regex-adattár.

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

Attribútumok

Attribútum Leírás Kötelező Alapértelmezett
unspecified-content-type-action Az API-sémában nem megadott tartalomtípusú kérések vagy válaszok esetén végrehajtandó művelet . A szabályzatkifejezések engedélyezettek. Igen n/a
maximális méret A kérelem vagy válasz törzsének maximális hossza bájtban, a Content-Length fejlécen ellenőrizve. Ha a kérelem törzse vagy választörzse tömörítve van, ez az érték a tömörített hossz. Megengedett maximális érték: 102 400 bájt (100 KB). (Ha növelni szeretné ezt a korlátot, forduljon az ügyfélszolgálathoz .) A szabályzatkifejezések engedélyezettek. Igen n/a
méretkorlát túllépése művelet Olyan kérelmek vagy válaszok esetén végrehajtandó művelet , amelyek törzse meghaladja a megadott méretet max-size. 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ő
content-type-map Adja hozzá ezt az elemet a bejövő kérés vagy válasz tartalomtípusának leképezéséhez egy másik tartalomtípushoz, amely az ellenőrzés aktiválására szolgál. Nem
content Adjon hozzá egy vagy több elemet a kérelem vagy válasz tartalomtípusának, illetve a megfeleltetett tartalomtípus ellenőrzéséhez, és hajtsa végre a megadott műveletet. Nem

content-type-map attribútumok

Attribútum Leírás Kötelező Alapértelmezett
bármely-content-type-value A kérés vagy válasz törzsének ellenőrzésére használt tartalomtípus a bejövő tartalomtípustól függetlenül. A szabályzatkifejezések nem engedélyezettek. Nem N.A.
missing-content-type-value A kérés vagy válasz törzsének ellenőrzésére használt tartalomtípus, ha a bejövő tartalomtípus hiányzik vagy üres. A szabályzatkifejezések nem engedélyezettek. Nem N.A.

content-type-map-elements

Név Leírás Kötelező
típus Adjon hozzá egy vagy több ilyen elemet, hogy egy bejövő tartalomtípust egy kérés vagy válasz törzsének ellenőrzésére használt tartalomtípushoz rendeljen. Egy from ismert bejövő tartalomtípus megadására használható, vagy egy szabályzatkifejezéssel bármely olyan bejövő tartalomtípus megadására, when amely megfelel egy feltételnek. Felülbírálja a leképezést, any-content-type-value és missing-content-type-valueha meg van adva. Nem

tartalomattribútumok

Attribútum Leírás Kötelező Alapértelmezett
típus A törzsérvényesítés végrehajtásához használt tartalomtípus, ha meg van adva, a tartalomtípus fejlécén vagy a megfeleltetett értéken content-type-mappingvan bejelölve. Ha üres, az API-sémában megadott összes tartalomtípusra vonatkozik.

A SOAP-kérelmek és válaszok ellenőrzéséhez (validate-asa "soap" attribútum beállítása) a SOAP 1.2 API-khoz vagy text/xml a SOAP 1.1 API-khoz legyen állítva typeapplication/soap+xml.
Nem N.A.
érvényesítés másként A kérelem vagy válasz törzsének egyezéssel typevaló ellenőrzéséhez használható érvényesítő motor. Támogatott értékek: "json", "xml", "soap".

Ha a "soap" meg van adva, a kérelemből vagy válaszból származó XML ki lesz nyerve a SOAP-borítékból, és egy XML-sémán lesz érvényesítve.
Igen n/a
sémaazonosító Az API Management-példányhoz tartalomérvényesítés céljából hozzáadott meglévő séma neve. Ha nincs megadva, a rendszer az API-definíció alapértelmezett sémáját használja. Nem N.A.
schema-ref A JSON-sémában schema-idmegadott JSON-séma esetében nem kötelező hivatkozni a JSON-dokumentum érvényes helyi referenciaútvonalára. Példa: #/components/schemas/address Az attribútumnak egy olyan JSON-objektumot kell visszaadnia, amelyet az API Management érvényes JSON-sémaként kezel.

Az XML-sémák nem támogatottak, schema-ref és bármely legfelső szintű sémaelem használható az XML-kérések vagy válaszok hasznos adatainak gyökereként. Az ellenőrzés ellenőrzi, hogy az XML-kérelemből vagy válaszból kiinduló hasznos adatok gyökerétől kezdve minden elem megfelel-e a megadott XML-sémának.
Nem N.A.
allow-additional-properties Logikai. JSON-sémák esetén megadja, hogy implementálni kell-e a sémában konfigurált érték futtatókörnyezeti additionalProperties felülbírálását:
- true: további tulajdonságok engedélyezése a kérelem- vagy választörzsben, még akkor is, ha a JSON-séma mezője additionalProperties úgy van konfigurálva, hogy ne engedélyezzen további tulajdonságokat.
- false: ne engedélyezzen további tulajdonságokat a kérelem- vagy választörzsben, még akkor sem, ha a JSON-séma mezője additionalProperties további tulajdonságok engedélyezésére van konfigurálva.

Ha az attribútum nincs megadva, a szabályzat a séma mezőjének konfigurációja alapján ellenőrzi a additionalProperties további tulajdonságokat.
Nem N.A.

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

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.

Tartalomérvényesítési sémák

Alapértelmezés szerint a kérelem- vagy választartalmak érvényesítése JSON- vagy XML-sémákat használ az API-definícióból. Ezek a sémák megadhatóak manuálisan vagy automatikusan, amikor egy API-t openAPI- vagy WSDL-specifikációból importálnak az API Managementbe.

validate-content A szabályzat használatával igény szerint érvényesíthet egy vagy több olyan JSON- vagy XML-sémát, amelyet hozzáadott az API Management-példányhoz, és amelyek nem részei az API-definíciónak. Az API Managementhez hozzáadott sémák számos API-ban újra felhasználhatók.

Séma hozzáadása az API Management-példányhoz az Azure Portal használatával:

  1. A portálon keresse meg az API Management-példányt.

  2. A bal oldali menü API-k szakaszában válassza a Séma>+ Hozzáadás lehetőséget.

  3. A Séma létrehozása ablakban tegye a következőket:

    1. Adja meg a séma nevét (azonosítóját).
    2. Sématípus esetén válassza a JSON vagy az XML lehetőséget.
    3. Adjon meg egy leírást.
    4. A Létrehozás metódusban tegye az alábbiak egyikét:
      • Válassza az Új létrehozása lehetőséget, és adja meg vagy illessze be a sémát.
      • Válassza az Importálás fájlból vagy Importálás URL-címről lehetőséget, és adjon meg egy sémahelyet.

        Feljegyzés

        A séma URL-címről való importálásához a sémának az interneten keresztül kell elérhetőnek lennie a böngészőből.

    5. Válassza a Mentés lehetőséget.

    Séma létrehozása

Az API Management hozzáadja a sémaerőforrást a relatív URI-hez/schemas/<schemaId>, és a séma megjelenik a Séma lapon található listában. Válasszon ki egy sémát a tulajdonságainak megtekintéséhez vagy a sémaszerkesztőben való szerkesztéshez.

Feljegyzés

A sémák kereszthivatkozással hivatkozhatnak az API Management-példányhoz hozzáadott másik sémára. Például adjon hozzá egy XML-sémát az API Managementhez a következőhöz hasonló elem használatával:

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

Tipp.

A GitHubon nyílt forráskódú eszközök érhetők el a WSDL- és XSD-sémahivatkozások feloldásához, valamint a létrehozott sémák kötegelt importálásához az API Managementbe.

Példák

JSON-séma érvényesítése

Az alábbi példában az API Management üres tartalomtípusú fejléccel vagy tartalomtípus-fejléccel application/hal+json rendelkező kéréseket a tartalomtípussal application/jsonrendelkező kérésekként értelmezi. Ezután az API Management észlelési módban hajtja végre az ellenőrzést egy, az application/json API-definícióban a tartalomtípushoz definiált sémán. A 100 KB-nál nagyobb hasznos adattal rendelkező üzenetek le vannak tiltva. A további tulajdonságokat tartalmazó kérelmek akkor is le vannak tiltva, ha a séma mezője additionalProperties további tulajdonságok engedélyezésére van konfigurálva.

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

SOAP-séma érvényesítése

Az alábbi példában az API Management a bejövő tartalomtípustól függetlenül bármilyen kérést a tartalomtípussal application/soap+xml (a SOAP 1.2 API-k által használt tartalomtípussal) értelmez. A kérés egy üres tartalomtípus-fejléccel, a (SOAP 1.1 API-k által használt) tartalomtípus fejlécével text/xml vagy egy másik tartalomtípus-fejlécmel is érkezhet. Ezután az API Management kinyeri az XML hasznos adatokat a SOAP-borítékból, és megelőzési módban végrehajtja az ellenőrzést a "myschema" nevű sémán. A 100 KB-nál nagyobb hasznos adattal rendelkező üzenetek le vannak tiltva.

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

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

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