Zásady ve službě Azure API Management

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Ve službě Azure API Management můžou vydavatelé rozhraní API měnit chování rozhraní API prostřednictvím konfigurace pomocí zásad. 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ž 50 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ří:

  • Formát převodu z XML na JSON
  • Omezení četnosti hovorů za účelem omezení počtu příchozích hovorů od vývojáře
  • Filtrování požadavků, které přichá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. Zatímco brána přijímá požadavky a předá je beze změny do podkladového rozhraní API, zásady můžou použít změny příchozího požadavku i odchozí odpovědi.

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 zadaných prohlášení zásad se provádí v pořadí pro požadavek a odpověď.

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

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ílu inboundnebo backendoutbound oddílu se přeskočí.
  • Provádění přeskočí 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 zásad.
  • 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ásad je buď:

  • jeden příkaz jazyka C# uzavřený v @(expression), nebo
  • blok kódu jazyka C# s více příkazy, který je uzavřený , @{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.

Rozsahy

SLUŽBA API Management umožňuje definovat zásady v následujících oborech, 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.

Obory zásad

Co je tř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 se podporují 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é s oborem rozhraní API, předplatné all-API nebo předdefinované předplatné s přístupem, zásady nakonfigurované v oboru produktu se na žádosti z tohoto předplatného nepoužijí.

Další informace naleznete v tématu:

Zásady překladače GraphQL

Ve službě API Management je překladač GraphQL nakonfigurovaný pomocí zásad omezených 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, Cosmos DB nebo Azure SQL. Můžete například nakonfigurovat jednu http-data-source zásadu s prvky, které určují požadavek na zdroj dat HTTP (a volitelně na odpověď).
  • Zásady překladače nemůžete zahrnout do definic zásad v jiných oborech, jako jsou rozhraní API, produkt nebo všechna rozhraní API. Také nedědí zásady nakonfigurované v jiných oborech.
  • Brána vyhodnocuje zásadu s oborem překladače po všech 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ískání pomoci s vytvářením zásad pomocí Microsoft Copilotu pro Azure (Preview)

Microsoft Copilot pro Azure (Preview) poskytuje možnosti vytváření zásad pro Azure API Management. Pomocí Copilotu pro Azure v kontextu editoru zásad služby API Management můžete vytvářet zásady, které odpovídají vašim konkrétním požadavkům, aniž byste znali syntaxi nebo jste už nakonfigurovali zásady.

K vygenerování definic zásad můžete vyzvat Copilot pro Azure a pak výsledky zkopírovat do editoru zásad a provést potřebné úpravy. Položte otázky, abyste získali přehled o různých možnostech, upravili poskytnuté zásady nebo objasnili zásady, které už máte. Další informace

Důležité

Microsoft Copilot pro Azure (Preview) vyžaduje registraci a je aktuálně k dispozici jenom schváleným podnikovým zákazníkům a partnerům. Další informace najdete v tématu Omezený přístup ke službě Microsoft Copilot pro Azure (Preview).

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 ukázkové definici zásady výše:

  • Příkaz cross-domain by se spustil jako první.
  • Zásady find-and-replace by se spouštěly po jakýchkoli 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. Produkt ani globální zásady rozsahu by se nepoužádly.

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ího požadavku. Přidaná hlavička obsahuje ID uživatele přidruženého k klíči předplatného v požadavku a oblast, kde brána zpracovává požadavek, je hostovaná.

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