Az Azure API Management szabályzatai

  • Cikk

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

Az Azure API Managementben az API-közzétevők a szabályzatok használatával konfigurálva módosíthatják az API viselkedését. A szabályzatok olyan utasítások gyűjteményei, amelyeket a rendszer egymást követően futtat egy API kérésére vagy válaszára reagálva. Az API Management több mint 50 szabályzatot biztosít a dobozból, amelyeket konfigurálhat olyan gyakori API-forgatókönyvek kezelésére, mint a hitelesítés, a sebességkorlátozás, a gyorsítótárazás és a kérések vagy válaszok átalakítása. A teljes listát az API Management-szabályzatok referenciadokumentumában tekintheti meg.

Népszerű szabályzatok:

  • Formátum konvertálása XML-ből JSON-ba
  • Hívásgyakoriság korlátozása a fejlesztőktől érkező bejövő hívások számának korlátozásához
  • Adott IP-címekről érkező kérések szűrése

A szabályzatok alkalmazás az API-felhasználó és a felügyelt API közötti átjárón belül történik. Amíg az átjáró fogadja, majd változtatás nélkül a mögöttes API-nak továbbítja a kéréseket, a szabályzatok módosításokat alkalmazhatnak a bejövő kérésre és a kimenő válaszra egyaránt.

A szabályzatkonfiguráció ismertetése

A szabályzatdefiníciók egyszerű XML-dokumentumok, amelyek a kérelmekre és válaszokra alkalmazandó utasítások sorozatát írják le. A szabályzatdefiníciók konfigurálásához a portál az alábbi lehetőségeket kínálja:

  • Irányított, űrlapalapú szerkesztő, amely leegyszerűsíti a népszerű szabályzatok xml-kódolás nélküli konfigurálását
  • Kódszerkesztő, amelyben XML-kódrészleteket szúrhat be vagy szerkesztheti közvetlenül az XML-fájlokat

A szabályzatok konfigurálásával kapcsolatos további információkért lásd: Szabályzatok beállítása vagy szerkesztése.

A szabályzat XML-konfigurációja szakaszokra backendoutboundon-error és szakaszokra inboundoszlik. A megadott házirend-utasítások sorozata a kérés és a válasz érdekében lesz végrehajtva.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Szabályzat XML-példáiért tekintse meg az API Management szabályzatrészleteinek adattárát.

Hibakezelés

Ha egy kérés feldolgozása során hiba történik:

  • A program kihagyja az , backendvagy outbound a inboundszakaszok többi lépését.
  • A végrehajtás a szakasz utasításaira on-error ugrik.

A házirend-utasításoknak a szakaszban való on-error elhelyezésével a következőt teheti:

  • Tekintse át a hibát a context.LastError tulajdonság használatával.
  • Vizsgálja meg és szabja testre a hibaválaszt a set-body szabályzat használatával.
  • Konfigurálja, mi történik, ha hiba történik.

További információ: Hibakezelés az API Management-szabályzatokban.

Házirend-kifejezések

Ha a szabályzat másként nem rendelkezik, a szabályzatkifejezések attribútumértékként vagy szöveges értékként használhatók bármelyik API Management-házirendben. A szabályzatkifejezések a következők:

  • egyetlen C#-utasítást, amely a következő helyen @(expression)található:
  • egy többutas C# kódblokk, amely egy @{expression}értéket ad vissza

Minden kifejezés hozzáfér az implicit módon megadott context változóhoz és a .NET-keretrendszer-típusok engedélyezett részhalmazához.

A szabályzatkifejezések kifinomult módot biztosítanak a forgalom szabályozására és az API viselkedésének módosítására anélkül, hogy speciális kódot kellene írnia, vagy módosítania kellene a háttérszolgáltatásokat. Egyes szabályzatok olyan szabályzatkifejezéseken alapulnak, mint a Control flow és a Set variable.

Hatókörök

Az API Management lehetővé teszi, hogy a szabályzatokat a legtágabbtól a legszűkebbig a következő hatókörökben definiálja:

  • Globális (minden API)
  • Munkaterület (a kijelölt munkaterülethez társított összes API)
  • Termék (a kijelölt termékhez társított összes API)
  • API (egy API összes művelete)
  • Művelet (egyetlen művelet egy API-ban)

Szabályzat konfigurálásakor először ki kell választania azt a hatókört, amelyre a szabályzat vonatkozik.

Szabályzat hatókörei

Tudnivalók

  • A különböző API-felhasználók részletes vezérléséhez több hatókörben is konfigurálhatja a szabályzatdefiníciókat

  • Nem minden szabályzat támogatott az egyes hatókörök és szabályzatszakaszok esetében

  • Ha egynél több hatókörben konfigurálja a szabályzatdefiníciókat, az elem elhelyezésével szabályozhatja a szabályzatok öröklését és a szabályzatok kiértékelési sorrendjét az egyes szabályzatszakaszokban.base

  • Az API-kérelmekre alkalmazott szabályzatokat a kérelemkörnyezet is befolyásolja, beleértve a kérelemben használt előfizetési kulcs meglétét vagy hiányát, az előfizetési kulcs API-ját vagy termékhatókörét, valamint azt, hogy az API vagy a termék igényel-e előfizetést.

    Feljegyzés

    Ha API-hatókörű előfizetést, teljes API-előfizetést vagy beépített teljes hozzáférésű előfizetést használ, a termék hatókörében konfigurált szabályzatok nem lesznek alkalmazva az adott előfizetésből érkező kérelmekre.

További információkért lásd:

GraphQL-feloldó szabályzatok

Az API Managementben a GraphQL-feloldó egy GraphQL-sémában egy adott művelettípusra és mezőre hatókörrel rendelkező szabályzatok használatával van konfigurálva.

  • Az API Management jelenleg olyan GraphQL-feloldókat támogat, amelyek HTTP API-, Cosmos DB- vagy Azure SQL-adatforrásokat határoznak meg. Konfiguráljon például egy olyan http-data-source házirendet elemekkel, amelyek egy HTTP-adatforrásra irányuló kérést (és opcionálisan választ) adnak meg.
  • A szabályzatdefiníciókban nem vehet fel feloldóházirendet más hatókörökben, például API-kban, termékekben vagy az összes API-ban. Emellett nem örökli a más hatókörökben konfigurált szabályzatokat.
  • Az átjáró kiértékel egy feloldó hatókörű szabályzatot a szabályzatvégrehajtási folyamat konfigurált inbound és backend szabályzatai után.

További információ: GraphQL-feloldó konfigurálása.

Segítség kérése szabályzatok létrehozásához az Azure-hoz készült Microsoft Copilot használatával (előzetes verzió)

Az Azure-hoz készült Microsoft Copilot (előzetes verzió) szabályzatkészítési képességeket biztosít az Azure API Managementhez. Az API Management szabályzatszerkesztőjének kontextusában használja az Azure-hoz készült Copilotot az adott követelményeknek megfelelő szabályzatok létrehozásához anélkül, hogy ismerné a szintaxist, vagy már konfigurálta a szabályzatokat.

Megkérheti a Copilototot az Azure-hoz, hogy hozzon létre szabályzatdefiníciókat, majd másolja az eredményeket a szabályzatszerkesztőbe, és végezze el a szükséges módosításokat. Kérdéseket tehet fel a különböző lehetőségek megismeréséhez, a megadott szabályzat módosításához vagy a már meglévő szabályzat tisztázásához. Tudj meg többet

Fontos

Az Azure-hoz készült Microsoft Copilot (előzetes verzió) regisztrációt igényel, és jelenleg csak jóváhagyott nagyvállalati ügyfelek és partnerek számára érhető el. További információ: Korlátozott hozzáférés az Azure-hoz készült Microsoft Copilothoz (előzetes verzió).

Példák

Különböző hatókörökben megadott szabályzatok alkalmazása

Ha globális szintű szabályzattal és API-hoz konfigurált szabályzattal rendelkezik, mindkét szabályzat alkalmazható az adott API használatakor. Az API Management lehetővé teszi a kombinált szabályzatutasítások determinisztikus sorrendjét az base elemen keresztül.

Példa szabályzatdefiníció az API hatókörében:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

A fenti példaszabályzat-definícióban:

  • Először az cross-domain utasítás lesz végrehajtva.
  • A find-and-replace szabályzat a szélesebb hatókörű szabályzatok után fog futni.

Feljegyzés

Ha eltávolítja az base elemet az API-hatókörből, csak az API-hatókörben konfigurált szabályzatok lesznek alkalmazva. Sem a termékre, sem a globális hatókörre vonatkozó szabályzatok nem lesznek alkalmazva.

Szabályzatkifejezések használata a kérések módosításához

Az alábbi példa szabályzatkifejezéseket és szabályzatokat használ a set-header felhasználói adatok bejövő kéréshez való hozzáadásához. A hozzáadott fejléc tartalmazza a kérelemben szereplő előfizetési kulcshoz társított felhasználói azonosítót, valamint azt a régiót, ahol a kérést feldolgozó átjáró üzemel.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Kapcsolódó tartalom

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