Zásady ve službě Azure API Management

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 požadavku nebo odpovědi rozhraní API. Mezi oblíbené příkazy patří:

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

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

Zásady se použijí uvnitř brány mezi příjemcem rozhraní API a spravovaným rozhraním API. I když brána přijímá požadavky a předává je do podkladového rozhraní API bez omezení, může zásada použít změny pro 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 pro 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, ve kterém 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ílů. Tato řada zadaných prohlášení zásad se provádí 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 API Management ukázkách zásad.

Zpracování chyb

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

  • Všechny zbývající kroky v inboundoddílech nebo , outboundbackendse 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 v on-error části můžete:

  • Zkontrolujte chybu pomocí context.LastError vlastnosti.
  • Zkontrolujte a přizpůsobte chybovou set-body odpověď pomocí zásad.
  • 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 nezadá jinak, výrazy zásad se dají použít jako hodnoty atributů nebo textové hodnoty v libovolné ze zásad API Management. Výraz zásad je jeden z těchto:

  • jeden příkaz jazyka C# uzavřený v @(expression)nebo
  • blok kódu jazyka C# s více příkazy @{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. Další informace naleznete 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, ve kterém se zásady vztahují.

Policy scopes

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 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í vyhodnocení zásad v jednotlivých částech 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ásady na globální úrovni a zásady nakonfigurované pro rozhraní API, můžete obě zásady použít při každém použití daného rozhraní API. API Management umožňuje deterministické řazení kombinovaných prohlášení zásad prostřednictvím elementubase.

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ásad výše:

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

Poznámka

Pokud odeberete base prvek v oboru rozhraní API, použijí se jenom zásady nakonfigurované v oboru rozhraní API. Nepoužijí se 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 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, ve které 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> 

Další kroky

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