Az Azure API Management szabályzatai

Alkalmazható minden API Management-szintre

Az Azure API Managementben az API-közzétevők a szabályzatok használatával módosíthatják az API viselkedését a konfiguráción keresztül. Ez a cikk a szabályzatok használatát ismerteti.

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

• XML formátum átalakítása JSON formátumba.
• A hívássebesség korlátozása a fejlesztőtől érkező hívások számának korlátozásához.
• Bizonyos 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. Bár az átjáró fogadja a kéréseket, és változatlanul továbbítja azokat a mögöttes API-nak, a szabályzatok módosításokat alkalmazhatnak mind a bejövő kérésre, mind a kimenő válaszra.

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 inboundbackendoutbound és szakaszokra on-erroroszlik. A megadott házirend-utasítások sorozata a kérés és a válasz érdekében fut. Így néz ki:

<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's 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 , inboundvagy backend a outboundszakaszok többi lépését.
• A végrehajtás on-error rész utasításaira ugrik.

A következőket teheti, ha az irányelveket a on-error szakaszba helyezi:

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

Szabályzat-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 egyike:

• Egyetlen C#-utasítás, amely @(expression) között van.
• Egy többsoros C# kódblokk, amely @{expression} lezárva egy é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 a szabályzatok meghatározását a következő hatókörökben, amelyek itt jelennek meg a legszélesebbtől a legszűkebbig:

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

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.

• Az egyes hatókörök és szabályzatszakaszok nem minden szabályzatot támogatnak.

• 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 base egyes szabályzatszakaszokban.

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

• Házirendek beállítása vagy szerkesztése
• Előfizetések az API Managementben

GraphQL-feloldó szabályzatok

Az API Managementben a GraphQL-feloldó olyan szabályzatokkal van konfigurálva, amelyek egy GraphQL-séma egy adott művelettípusára és mezőjére terjednek ki.

• Az API Management jelenleg támogatja a HTTP API-t, az Azure Cosmos DB-t vagy az Azure SQL-adatforrásokat meghatározó GraphQL-feloldókat. Konfigurálhat például egy olyan http-data-source házirendet, amely elemeket is tartalmazhat a HTTP-adatforrások kérésének (és opcionális válaszának) megadásához.
• A házirend-definíciókban nem szerepeltethet feloldási házirendet más hatókörökben, például API-k, termékek vagy minden API esetében. A szabályzat nem örökli a más hatókörökben konfigurált szabályzatokat sem.
• 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.

Copilot-segítség kérése

A Copilot AI-segítséget kaphat az API Management-szabályzatdefiníciók létrehozásához és szerkesztéséhez. A Copilot segítségével az adott követelményeknek megfelelő szabályzatokat hozhat létre és frissíthet anélkül, hogy ismernie kellene az XML-szintaxist. A meglévő szabályzatok magyarázatát is lekérheti. A Copilot pedig segíthet lefordítani azokat a szabályzatokat, amelyeket más API-kezelési megoldásokban konfigurálhatott.

• Az Azure-beli Microsoft Copilot az Azure Portalon segítséget nyújt a természetes nyelvi kérésekkel kapcsolatos szabályzatkészítéshez. Szabályzatokat készíthet az API Management szabályzatszerkesztőjében, és megkérheti a Copilototot, hogy magyarázza el a szabályzatszakaszokat.
• Az Azure-hoz készült GitHub Copilot a Visual Studio Code-ban szabályzatkészítési segítséget nyújt a Visual Studio Code-ban, és a Visual Studio Code-hoz készült Azure API Management-bővítmény használatával felgyorsíthatja a szabályzatkonfigurációt. A copilot-csevegést vagy a természetes nyelvű Copilot-szerkesztéseket kérheti a szabályzatdefiníciók létrehozásához és pontosításához.

Példakérés:

Generate a policy that adds an Authorization header to the request with a Bearer token.

A Copilot mesterséges intelligenciával működik, így meglepetések és hibák lehetségesek. További információért lásd a Copilot általános használatra vonatkozó gyakori kérdéseket.

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>

Az előző példaszabályzat definíciójában:

• Az cross-domain utasítás fut először.
• A find-and-replace szabályzat minden szélesebb hatókörű szabályzat után fut.

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. A terméken és szélesebb hatókörökön konfigurált 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ésekhez 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ó található.

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

• Oktatóanyag: AZ API átalakítása és védelme
• Szabályzathivatkozás a szabályzatutasságok és azok beállításainak teljes listájához
• Politika kifejezések
• Házirendek beállítása vagy szerkesztése
• Szabályzatkonfigurációk újrafelhasználása
• Szabályzatrészletek adattára
• Házirend-játszótér adattára
• Azure API Management policy toolkit
• A Copilot segítségével szabályzatokat hozhat létre, magyarázhat el és háríthat el hibákat.