Sdílet prostřednictvím

Zásady ve službě Azure API Management

PLATÍ PRO: Všechny úrovně služby správy rozhraní API

Ve službě Azure API Management můžou vydavatelé rozhraní API měnit chování rozhraní API prostřednictvím konfigurace pomocí zásad. Tento článek popisuje, jak používat zásady.

Zásady představují kolekci příkazů, které se postupně provádí na základě požadavku nebo odezvy z rozhraní API. Služba API Management nabízí více než 75 zásad, které můžete nakonfigurovat tak, aby řešily běžné scénáře rozhraní API, jako je ověřování, omezování rychlosti, ukládání do mezipaměti a transformace požadavků nebo odpovědí. Úplný seznam najdete v referenčních informacích k zásadám API Management.

Mezi oblíbené zásady patří:

  • Převod formátu z XML na JSON
  • Omezení četnosti volání za účelem omezení počtu příchozích hovorů od vývojáře
  • Filtrování požadavků, které pocházejí z určitých IP adres

Zásady se použijí uvnitř brány mezi uživatelem rozhraní API a spravovaným rozhraním API. I když brána přijímá požadavky a předává je do základního rozhraní API beze změny, může zásada použít změny na příchozí i odchozí odpověď.

Principy konfigurace zásad

Definice zásad jsou jednoduché dokumenty XML, které popisují posloupnost příkazů, které se mají použít na požadavky a odpovědi. Portál nabízí tyto možnosti, které vám pomůžou s konfigurací definic zásad:

  • Editor založený na formulářích, který zjednodušuje konfiguraci oblíbených zásad bez kódování XML
  • Editor kódu, do kterého můžete vkládat fragmenty KÓDU XML nebo upravovat XML přímo

Další informace o konfiguraci zásad najdete v tématu Nastavení nebo úprava zásad.

Konfigurace XML zásad je rozdělena do inbound, backend, outbounda on-error oddíly. Tato série specifikovaných politických prohlášení se provádí v pořadí pro žádost a odpověď. Vypadá takto:

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

Příklady xml zásad najdete v úložišti fragmentů zásad služby API Management.

Zpracování chyb

Pokud během zpracování požadavku dojde k chybě:

  • Všechny zbývající kroky v oddílech inbound, backend nebo outbound se přeskočí.
  • Provádění přejde na příkazy v oddílu on-error.

Umístěním prohlášení o zásadách do on-error části můžete:

  • Zkontrolujte chybu pomocí context.LastError vlastnosti.
  • Zkontrolujte a přizpůsobte odpověď na chybu pomocí set-body politiky.
  • Nakonfigurujte, co se stane, když dojde k chybě.

Další informace najdete v tématu Zpracování chyb v zásadách služby API Management.

Výrazy zásad

Pokud zásada neurčí jinak, výrazy zásad se dají použít jako hodnoty atributů nebo textové hodnoty v některé ze zásad služby API Management. Výraz zásady je jedním z následujících výrazů:

  • Jeden příkaz jazyka C# uzavřený v @(expression)
  • Blok kódu jazyka C# s více příkazy, uzavřený v @{expression}, který vrací hodnotu

Každý výraz má přístup k implicitně poskytnuté context proměnné a povolené podmnožině typů rozhraní .NET Framework.

Výrazy zásad poskytují sofistikované prostředky pro řízení provozu a úpravu chování rozhraní API bez nutnosti psát specializovaný kód nebo upravovat back-endové služby. Některé zásady jsou založené na výrazech zásad, jako je tok řízení a proměnná Set.

Rozsah působnosti

Služba API Management umožňuje definovat zásady v následujících oborech, které jsou zde uvedeny od nejširšího po nejužší:

  • Globální (všechna rozhraní API)
  • Pracovní prostor (všechna rozhraní API přidružená k vybranému pracovnímu prostoru)
  • Produkt (všechna rozhraní API přidružená k vybranému produktu)
  • ROZHRANÍ API (všechny operace v rozhraní API)
  • Operace (jedna operace v rozhraní API)

Při konfiguraci zásady musíte nejprve vybrat obor, na který se zásada vztahuje.

Diagram znázorňující pět oborů zásad

Co je potřeba vědět

  • Pro jemně odstupňované řízení pro různé uživatele rozhraní API můžete nakonfigurovat definice zásad ve více než jednom oboru.

  • Ne všechny zásady jsou podporovány v každém oboru a oddílu zásad.

  • Při konfiguraci definic zásad ve více než jednom oboru řídíte dědičnost zásad a pořadí vyhodnocení zásad v každé části zásad umístěním base prvku.

  • Zásady použité na požadavky rozhraní API mají vliv také na kontext požadavku, včetně přítomnosti nebo nepřítomnosti klíče předplatného použitého v požadavku, rozhraní API nebo rozsahu produktu klíče předplatného a toho, jestli rozhraní API nebo produkt vyžaduje předplatné.

    Poznámka:

    Pokud používáte předplatné omezené na API, předplatné pro všechny rozhraní API nebo předdefinované předplatné s úplným přístupem, zásady nakonfigurované v rámci produktu se na žádosti z takového předplatného nepoužijí.

Další informace najdete tady:

Zásady resolveru GraphQL

Ve službě API Management je překladač GraphQL nakonfigurovaný se zásadami vymezenými na konkrétní typ operace a pole ve schématu GraphQL.

  • Api Management v současné době podporuje překladače GraphQL, které určují zdroje dat HTTP API, Azure Cosmos DB nebo Azure SQL. Můžete například nakonfigurovat jednu http-data-source zásadu s prvky pro určení požadavku na zdroj dat HTTP a případně i odpovědi z něj.
  • Zásady resolveru nemůžete zahrnout do definic politiky v jiných oblastech, jako jsou rozhraní API, produkt nebo všechna rozhraní API. Zásady také nedědí zásady nakonfigurované v jiných oborech.
  • Brána vyhodnocuje zásadu s oborem řešitele po jakýchkoli nakonfigurovaných inbound a backend zásadách v kanálu spouštění zásad.

Další informace najdete v tématu Konfigurace překladače GraphQL.

Získejte asistenci Copilota

Pomoc s AI můžete získat od společnosti Copilot k vytvoření a úpravě definic zásad služby API Management. Pomocí Copilotu můžete vytvářet a aktualizovat zásady, které odpovídají vašim konkrétním požadavkům, aniž byste museli znát syntaxi XML. Můžete také získat vysvětlení existujících zásad. A Copilot vám může pomoct přeložit zásady, které jste možná nakonfigurovali v jiných řešeních služby API Management.

Příklad výzvy:

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

Copilot využívá AI, takže překvapení a chyby jsou možné. Další informace najdete v tématu Nejčastější dotazy k obecnému použití copilotu.

Příklady

Použití zásad zadaných v různých oborech

Pokud máte zásady na globální úrovni a zásady nakonfigurované pro rozhraní API, je možné obě zásady použít při každém použití tohoto konkrétního rozhraní API. Služba API Management umožňuje deterministické řazení kombinovaných příkazů zásad prostřednictvím elementu base .

Příklad definice zásady v oboru rozhraní API:

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

V předchozí ukázkové definici zásady:

  • Příkaz se cross-domain spustí jako první.
  • Zásady find-and-replace se spouští po všech zásadách v širším rozsahu.

Poznámka:

Pokud odeberete base prvek v oboru rozhraní API, použijí se pouze zásady nakonfigurované v oboru rozhraní API. Zásady nakonfigurované v produktech a širších oborech se nepoužijí.

Použití výrazů zásad k úpravě požadavků

Následující příklad používá výrazy zásad a set-header zásady k přidání uživatelských dat do příchozích požadavků. Přidaná hlavička obsahuje ID uživatele přidruženého ke klíči předplatného v požadavku a region, kde je hostována brána zpracovávající požadavek.

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

Související obsah

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