Zásady ve službě Azure API Management

  • Článek
  • 3 min ke čtení

V Azure API Management můžou vydavatelé rozhraní API měnit chování rozhraní API prostřednictvím konfigurace pomocí zásad. Zásady jsou kolekce příkazů, které se spouštějí postupně na žádost nebo odpověď rozhraní API. Mezi oblíbené příkazy 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é přicházejí z určitých IP adres

K dispozici je mnoho dalších zásad. Úplný seznam najdete v referenčních informacích k zásadám API Management.

Zásady se použijí uvnitř brány mezi příjemcem 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 základního rozhraní API, zásada může 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 s asistencí založený na formulářích pro zjednodušení konfigurace oblíbených zásad bez kódování XML
  • Editor kódu, ve kterém můžete přímo vkládat fragmenty kódu XML nebo upravovat XML

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

Konfigurace XML zásad je rozdělená na inboundoddíly , outboundbackend, a on-error . Tato řada zadaných prohlášení o zásadách 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 zásad XML najdete v ukázkách zásad API Management.

Zpracování chyb

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

  • Všechny zbývající kroky v inboundčástech , backendnebo outbound 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 oddílu on-error můžete:

  • Zkontrolujte chybu pomocí context.LastError vlastnosti .
  • Pomocí zásad prozkoumejte a přizpůsobte chybovou set-body odpověď.
  • Nakonfigurujte, co se stane, když dojde k chybě.

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

Výrazy zásad

Pokud zásada neurčí jinak, je možné výrazy zásad použít jako hodnoty atributů nebo textové hodnoty v kterékoli ze zásad API Management. Výraz zásady je:

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

Každý výraz má přístup k implicitně zadané 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, aniž byste museli 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. Další informace najdete v tématu Pokročilé zásady.

Obory

API Management umožňuje definovat zásady v následujících oborech, od nejširších po nejužší:

  • Globální (všechna rozhraní API)
  • Produkt (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 potřeba vědět

  • Pro podrobné řízení různých příjemců rozhraní API můžete nakonfigurovat definice zásad ve více než jednom oboru.
  • Ne všechny zásady se dají použít v každém oboru a oddílu zásad.
  • Při konfiguraci definic zásad ve více než jednom oboru řídíte pořadí vyhodnocování zásad v jednotlivých oddílech zásad umístěním elementu base .

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

Příklady

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

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

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

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

V příkladu definice zásady výše:

  • Příkaz by se cross-domain spustil jako první.
  • Zásada by se spustila find-and-replace po jakýchkoli zásadách v širším rozsahu.

Poznámka

Pokud odeberete base element v oboru rozhraní API, použijí se pouze zásady nakonfigurované v oboru rozhraní API. Nepouužijí se ani zásady produktu ani globálního rozsahu.

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

Následující příklad používá výrazy zásad a zásadu set-header 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 ke klíči předplatného v požadavku a oblast, kde je hostovaná 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>

Další kroky

Další informace o práci se zásadami najdete tady: