Pokročilé zásady služby API Management

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

Tento článek obsahuje referenční informace pro pokročilé zásady API Management, jako jsou ty, které jsou založené na výrazech zásad.

Další informace o zásadách:

Pokročilé zásady

Tok řízení

Zásady choose se vztahují k uzavřeným prohlášením zásad na základě výsledku vyhodnocení logických výrazů, podobně jako if-then-else nebo konstruktor přepínače v programovacím jazyce.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<choose>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <otherwise>
        <!— one or more policy statements to be applied if none of the above conditions are true  -->
    </otherwise>
</choose>

Zásady toku řízení musí obsahovat alespoň jeden <when/> prvek. Prvek <otherwise/> je volitelný. Podmínky v <when/> elementech se vyhodnocují v pořadí jejich vzhledu v rámci zásad. Použijí se příkazy zásad uzavřené v prvním <when/> prvku s atributem podmínky rovná se true . Zásady uzavřené v elementu<otherwise/>, pokud jsou k dispozici, se použijí, pokud jsou falsevšechny <when/> atributy podmínky elementu .

Příklady

Příklad

Následující příklad ukazuje zásadu set-variable a dvě zásady toku řízení.

Zásada proměnné sady je v příchozí části a vytvoří isMobile logickou kontextovou proměnnou, která je nastavená na true, pokud User-Agent hlavička požadavku obsahuje text iPad nebo iPhone.

První zásada toku řízení je také v příchozí části a podmíněně použije jednu ze dvou zásad parametrů řetězce dotazu v závislosti na hodnotě isMobile kontextové proměnné.

Druhá zásada toku řízení je v oddílu odchozích dat a podmíněně použije zásadu Convert XML na JSON , pokud isMobile je nastavená na true.

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPhone"))" />
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <set-query-parameter name="mobile" exists-action="override">
                    <value>true</value>
                </set-query-parameter>
            </when>
            <otherwise>
                <set-query-parameter name="mobile" exists-action="override">
                    <value>false</value>
                </set-query-parameter>
            </otherwise>
        </choose>
    </inbound>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <xml-to-json kind="direct" apply="always" consider-accept-header="false"/>
            </when>
        </choose>
    </outbound>
</policies>

Příklad

Tento příklad ukazuje, jak provádět filtrování obsahu odebráním datových prvků z odpovědi přijaté z back-endové služby při použití Starter produktu. Ukázková back-endová odpověď obsahuje vlastnosti na úrovni kořenového adresáře podobné rozhraní OpenWeather One Call API.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"current", "minutely", "hourly", "daily", "alerts"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

Elementy

Element Popis Povinné
zvolit Kořenový prvek. Yes
Kdy Podmínka, která se má použít pro if zásady nebo ifelse jeho části choose . Pokud zásada choose obsahuje více when oddílů, vyhodnocují se postupně. condition Jakmile se element vyhodnotí jako trueelement , nebudou vyhodnoceny žádné další when podmínky. Yes
jinak Obsahuje fragment zásad, který se má použít, pokud se žádná z when podmínek nevyhodnocuje na true. No

Atributy

Atribut Popis Povinné
condition="Logický výraz | Logická konstanta" Logický výraz nebo konstanta, které se mají vyhodnotit, když when se vyhodnotí příkaz obsahující zásady. Yes

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Přeposlání požadavku

Zásada forward-request předá příchozí požadavek back-endové službě zadané v kontextu požadavku. Adresa URL back-endové služby je zadaná v nastavení rozhraní API a dá se změnit pomocí zásad nastavené back-endové služby .

Důležité

  • Tato zásada se vyžaduje k předávání požadavků do back-endu rozhraní API. Ve výchozím nastavení API Management tuto zásadu nastaví v globálním oboru.
  • Odebráním této zásady se požadavek nepřesměruje do back-endové služby. Zásady v oddílu odchozích přenosů se vyhodnocují okamžitě po úspěšném dokončení zásad v příchozím oddílu.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<forward-request timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

Příklady

Příklad

Následující zásady na úrovni rozhraní API předávají všechny požadavky rozhraní API do back-endové služby s časovým limitem 60 sekund.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Příklad

Tato zásada na úrovni operace používá base prvek k dědění back-endové zásady z oboru nadřazené úrovně rozhraní API.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Příklad

Tato zásada na úrovni operace explicitně předává všechny požadavky do back-endové služby s časovým limitem 120 a nedědí nadřazenou zásadu back-endu na úrovni rozhraní API. Pokud back-endová služba reaguje se stavovým kódem chyby od 400 do 599 včetně, aktivuje se část s chybou .

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120" fail-on-error-status-code="true" />
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Příklad

Tato zásada na úrovni operace nepředává požadavky do back-endové služby.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Elementy

Element Popis Povinné
forward-request Kořenový prvek. Yes

Atributy

Atribut Popis Povinné Výchozí
timeout="integer" Doba v sekundách čekání na vrácení hlaviček odpovědi HTTP back-endovou službou před vyvoláním chyby časového limitu Minimální hodnota je 0 sekund. Hodnoty větší než 240 sekund nemusí být dodrženy, protože základní síťová infrastruktura může po této době vynechat nečinná připojení. No 300
follow-redirects="false | true" Určuje, jestli se za bránou následují přesměrování z back-endové služby, nebo se vrátí volajícímu. No false (nepravda)
buffer-request-body="false | true" Pokud je nastavená hodnota true, požadavek se uloží do vyrovnávací paměti a znovu se použije při opakování. No false (nepravda)
buffer-response="false | true" Ovlivňuje zpracování blokovaných odpovědí. Při nastavení na hodnotu false se každý blok přijatý z back-endu okamžitě vrátí volajícímu. Pokud je nastavená hodnota true, bloky dat se ukládají do vyrovnávací paměti (8 kB, pokud není zjištěn konec datového proudu) a pak se vrátí volajícímu.

U back-endů, jako jsou ty, které implementují události odesílané serverem (SSE), které vyžadují, aby se obsah vrátil nebo streamoval okamžitě volajícímu, nastavte na hodnotu false.		 No true
fail-on-error-status-code="false | true" Pokud je nastavená hodnota true, aktivuje se část o chybě pro kódy odpovědí v rozsahu od 400 do 599 včetně. No false (nepravda)

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: back-end
  • Obory zásad: všechny obory

Zahrnout fragment

Zásada include-fragment vloží do definice zásady obsah dříve vytvořeného fragmentu zásad . Fragment zásad je centrálně spravovaný a opakovaně použitelný fragment zásad XML, který je možné zahrnout do definic zásad ve vaší instanci API Management.

Zásada vloží fragment zásad tak, jak je v umístění, které vyberete v definici zásady.

Prohlášení o zásadách

<include-fragment fragment-id="fragment" />

Příklad

V následujícím příkladu se fragment zásad s názvem myFragment přidá do příchozí části definice zásady.

<inbound>
    <include-fragment fragment-id="myFragment" />
    <base />
</inbound>
[...]

Elementy

Element Popis Povinné
include-fragment Kořenový prvek. Yes

Atributy

Atribut Popis Povinné Výchozí
fragment-ID Řetězec. Výraz je povolený. Určuje identifikátor (název) fragmentu zásady vytvořeného v instanci API Management. Yes –

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, odchozí, back-end, chyba

  • Obory zásad: všechny obory

Omezení souběžnosti

Zásada limit-concurrency zabraňuje provádění uzavřených zásad více než zadaným počtem požadavků kdykoli. Když je toto číslo překročeno, nové požadavky okamžitě selžou se stavovým 429 kódem Příliš mnoho požadavků.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<limit-concurrency key="expression" max-count="number">
        <!— nested policy statements -->
</limit-concurrency>

Příklad

Následující příklad ukazuje, jak omezit počet požadavků předávaných do back-endu na základě hodnoty kontextové proměnné.

<policies>
  <inbound>…</inbound>
  <backend>
    <limit-concurrency key="@((string)context.Variables["connectionId"])" max-count="3">
      <forward-request timeout="120"/>
    </limit-concurrency>
  </backend>
  <outbound>…</outbound>
</policies>

Elementy

Element Popis Povinné
limit-concurrency Kořenový prvek. Yes

Atributy

Atribut Popis Povinné Výchozí
key Řetězec. Výraz je povolený. Určuje obor souběžnosti. Může být sdílen více zásadami. Yes –
max-count Celé číslo Určuje maximální počet požadavků, které mají povoleno zadat zásadu. Yes –

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Přihlášení do centra událostí

Zásada log-to-eventhub odesílá zprávy v zadaném formátu do centra událostí definovaného entitou loggeru. Jak název napovídá, zásada se používá k ukládání vybraných informací o kontextu žádosti nebo odpovědi pro online nebo offline analýzu.
Na zásadu nemá vliv vzorkování Application Insights. Všechny vyvolání zásad se zaprotokoluje.

Poznámka

Podrobný průvodce konfigurací centra událostí a událostí protokolování najdete v tématu Jak protokolovat API Management události pomocí Azure Event Hubs.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<log-to-eventhub logger-id="id of the logger entity" partition-id="index of the partition where messages are sent" partition-key="value used for partition assignment">
  Expression returning a string to be logged
</log-to-eventhub>

Příklad

Libovolný řetězec lze použít jako hodnotu, která se má protokolovat ve službě Event Hubs. V tomto příkladu se název služby nasazení, ID požadavku, IP adresa a název operace pro všechna příchozí volání zaprotokolují do protokolovacího modulu centra událostí zaregistrovaného contoso-logger s ID.

<policies>
  <inbound>
    <log-to-eventhub logger-id ='contoso-logger'>
      @( string.Join(",", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) )
    </log-to-eventhub>
  </inbound>
  <outbound>
  </outbound>
</policies>

Elementy

Element Popis Povinné
log-to-eventhub Kořenový prvek. Hodnota tohoto prvku je řetězec, který se má protokolovat do centra událostí. Yes

Atributy

Atribut Popis Povinné
logger-id ID protokolovacího nástroje zaregistrovaného ve vaší službě API Management. Yes
id oddílu Určuje index oddílu, ve kterém se odesílají zprávy. Nepovinný parametr. Tento atribut nelze použít, pokud partition-key se používá.
klíč oddílu Určuje hodnotu použitou pro přiřazení oddílu při odesílání zpráv. Nepovinný parametr. Tento atribut nelze použít, pokud partition-id se používá.

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Generování metrik

Zásada emit-metric odesílá do Application Insights vlastní metriky v zadaném formátu.

Poznámka

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<emit-metric name="name of custom metric" value="value of custom metric" namespace="metric namespace"> 
    <dimension name="dimension name" value="dimension value" /> 
</emit-metric>

Příklad

Následující příklad odešle vlastní metriku pro počítání počtu požadavků rozhraní API spolu s ID uživatele, IP adresou klienta a ID rozhraní API jako vlastní dimenze.

<policies>
  <inbound>
    <emit-metric name="Request" value="1" namespace="my-metrics"> 
        <dimension name="User ID" /> 
        <dimension name="Client IP" value="@(context.Request.IpAddress)" /> 
        <dimension name="API ID" /> 
    </emit-metric> 
  </inbound>
  <outbound>
  </outbound>
</policies>

Elementy

Element Popis Povinné
metrika emit-metric Kořenový prvek. Hodnota tohoto prvku je řetězec pro generování vlastní metriky. Yes
Dimenze Dílčí prvek. Přidejte jeden nebo více těchto prvků pro jednotlivé dimenze zahrnuté do vlastní metriky. Yes

Atributy

metrika emit-metric

Atribut Popis Povinné Typ Výchozí hodnota
name Název vlastní metriky Yes string, expression –
namespace Obor názvů vlastní metriky No string, expression API Management
hodnota Hodnota vlastní metriky No int, expression 1

Dimenze

Atribut Popis Povinné Typ Výchozí hodnota
name Název dimenze. Yes string, expression –
hodnota Hodnota dimenze. Je možné vynechat pouze v případě, že name odpovídá jedné z výchozích dimenzí. Pokud ano, zobrazí se hodnota podle názvu dimenze. No string, expression –

Výchozí názvy dimenzí, které lze použít bez hodnoty:

  • API ID
  • ID operace
  • ID produktu
  • ID uživatele
  • ID předplatného
  • ID umístění
  • ID brány

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Napodobení odpovědi

Jak mock-responsenázev napovídá, slouží k napodobení rozhraní API a operací. Přeruší normální spuštění kanálu a vrátí napodobenou odpověď volajícímu. Zásady se vždy snaží vrátit odpovědi s nejvyšší věrností. Dává přednost příkladům obsahu odpovědí, kdykoli je k dispozici. Generuje ukázkové odpovědi ze schémat, pokud jsou k dispozici schémata a příklady nejsou. Pokud nenajdete žádné příklady ani schémata, vrátí se odpovědi bez obsahu.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<mock-response status-code="code" content-type="media type"/>

Příklady

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code. First found content type is used. If no example or schema is found, the content is empty. -->
<mock-response/>

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code and media type. If no example or schema found, the content is empty. -->
<mock-response status-code='200' content-type='application/json'/>

Elementy

Element Popis Povinné
mock-response Kořenový prvek. Yes

Atributy

Atribut Popis Povinné Výchozí
stavový kód Určuje stavový kód odpovědi a slouží k výběru odpovídajícího příkladu nebo schématu. No 200
content-type Určuje Content-Type hodnotu hlavičky odpovědi a slouží k výběru odpovídajícího příkladu nebo schématu. No Žádné

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, on-error

  • Obory zásad: všechny obory

Zkusit znovu

Zásady retry spustí své podřízené zásady jednou a potom opakují jejich spuštění, dokud se opakování condition nestane false nebo se opakování nevyčerpá count .

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách


<retry
    condition="boolean expression or literal"
    count="number of retry attempts"
    interval="retry interval in seconds"
    max-interval="maximum retry interval in seconds"
    delta="retry interval delta in seconds"
    first-fast-retry="boolean expression or literal">
        <!-- One or more child policies. No restrictions -->
</retry>

Příklad

V následujícím příkladu se požadavek na přeposílání opakuje až desetkrát pomocí exponenciálního algoritmu opakování. Vzhledem k tomu first-fast-retry , že je nastavena na hodnotu false, všechny pokusy o opakování podléhají exponenciálnímu zvýšení doby čekání opakování (v tomto příkladu přibližně 10 sekund, 20 sekund, 40 sekund, ...), až do maximálního max-intervalčekání .


<retry
    condition="@(context.Response.StatusCode == 500)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
        <forward-request buffer-request-body="true" />
</retry>

Příklad

V následujícím příkladu se odeslání požadavku na jinou adresu URL, než je definovaný back-end, opakovat až třikrát, pokud dojde k výpadku nebo vypršení časového limitu připojení, nebo výsledkem požadavku je chyba na straně serveru. Vzhledem k tomu, že first-fast-retry je nastavená hodnota true, první opakování se spustí okamžitě po selhání počátečního požadavku. Mějte na paměti, že send-request pokud má být hodnota null v případě chyby, musí být nastavená ignore-error na hodnotu true response-variable-name .


<retry
    condition="@(context.Variables["response"] == null || ((IResponse)context.Variables["response"]).StatusCode >= 500)"
    count="3"
    interval="1"
    first-fast-retry="true">
        <send-request 
            mode="new" 
            response-variable-name="response" 
            timeout="3" 
            ignore-error="true">
		        <set-url>https://api.contoso.com/products/5</set-url>
		        <set-method>GET</set-method>
		</send-request>
</retry>

Elementy

Element Popis Povinné
retry Kořenový prvek. Může obsahovat jakékoli jiné zásady jako podřízené prvky. Yes

Atributy

Atribut Popis Povinné Výchozí
podmínka Logický literál nebo výraz určující, jestli se mají opakování zastavit (false) nebo pokračovat (true). Yes –
count Kladné číslo určující maximální počet opakování k pokusu. Yes –
interval Kladné číslo v sekundách určující interval čekání mezi pokusy o opakování. Yes –
maximální interval Kladné číslo v sekundách určující maximální interval čekání mezi pokusy o opakování. Slouží k implementaci exponenciálního algoritmu opakování. No –
Delta Kladné číslo v sekundách určující přírůstek intervalu čekání. Slouží k implementaci lineárních a exponenciálních algoritmů opakování. No –
první rychlé opakování Pokud je nastavená hodnota true , první pokus o opakování se provede okamžitě. No false

Opakování doby čekání

  • Pokud je zadána pouze interval hodnota, provede se opakované pokusy s pevným intervalem.

  • Pokud je zadán pouze interval a delta jsou zadány, použije se algoritmus opakování lineárního intervalu. Doba čekání mezi opakovanými pokusy se zvýší podle následujícího vzorce: interval + (count - 1)*delta.

  • intervalmax-interval Po zadání a delta zadání se použije algoritmus opakování exponenciálního intervalu. Doba čekání mezi opakovanými pokusy se exponenciálně zvyšuje podle následujícího vzorce: interval + (2^count - 1) * random(delta * 0.8, delta * 1.2)až do maximálního intervalu nastaveného .max-interval

    Například když interval a jsou obě delta nastaveny na 10 sekund a max-interval je 100 sekund, přibližná doba čekání mezi opakovanými pokusy se zvýší takto: 10 sekund, 20 sekund, 40 sekund, 80 sekund a doba čekání 100 sekund použitá pro zbývající opakování.

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad. Omezení používání podřízených zásad budou zděděna touto zásadou.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Návratová odpověď

Zásady return-response přeruší spuštění kanálu a vrátí výchozí nebo vlastní odpověď volajícímu. Výchozí odpověď není 200 OK bez textu. Vlastní odpověď lze zadat prostřednictvím kontextové proměnné nebo příkazů zásad. Pokud jsou k dispozici obě, odpověď obsažená v kontextové proměnné se před vrácením volajícímu upraví příkazy zásad.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<return-response response-variable-name="existing context variable">
  <set-header/>
  <set-body/>
  <set-status/>
</return-response>

Příklad

<return-response>
   <set-status code="401" reason="Unauthorized"/>
   <set-header name="WWW-Authenticate" exists-action="override">
      <value>Bearer error="invalid_token"</value>
   </set-header>
</return-response>

Elementy

Element Popis Povinné
return-response Kořenový prvek. Yes
set-header Prohlášení o zásadách set-header No
set-body Prohlášení o zásadách set-body . No
set-status Prohlášení o zásadách stavu sady No

Atributy

Atribut Popis Povinné
response-variable-name Název kontextové proměnné odkazované například z nadřazené zásady požadavku na odeslání a obsahující Response objekt Nepovinný parametr.

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end, on-error

  • Obory zásad: všechny obory

Odeslání žádosti o jeden způsob

Zásada send-one-way-request odešle zadaný požadavek na zadanou adresu URL bez čekání na odpověď.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<send-one-way-request mode="new | copy">
  <set-url>...</set-url>
  <method>...</method>
  <header name="" exists-action="override | skip | append | delete">...</header>
  <body>...</body>
  <authentication-certificate thumbprint="thumbprint" />
</send-one-way-request>

Příklad

Tato ukázková zásada ukazuje příklad použití send-one-way-request zásady k odeslání zprávy do chatovací místnosti Slack, pokud je kód odpovědi HTTP větší nebo rovno 500. Další informace o této ukázce najdete v tématu Použití externích služeb ze služby Azure API Management.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

Elementy

Element Popis Povinné
send-one-way-request Kořenový prvek. Yes
set-url Adresa URL požadavku. Ne, pokud mode=copy; jinak ano.
method Metoda HTTP pro požadavek. Ne, pokud mode=copy; jinak ano.
header Hlavička požadavku. Pro více hlaviček požadavků použijte více prvků záhlaví. No
text Text požadavku. No
authentication-certificate Certifikát, který se má použít pro ověřování klientů No

Atributy

Atribut Popis Povinné Výchozí
mode="string" Určuje, zda se jedná o nový požadavek nebo kopii aktuálního požadavku. V režimu odchozích přenosů mode=copy neicializuje text požadavku. No Nová
name Určuje název hlavičky, který se má nastavit. Yes –
exist-action Určuje, jaká akce se má provést, když už je záhlaví zadané. Tento atribut musí mít jednu z následujících hodnot.

- přepsání – nahradí hodnotu existující hlavičky.
- skip - nenahrazuje existující hodnotu záhlaví.
- připojení – připojí hodnotu k existující hodnotě záhlaví.
- odstranit – odebere hlavičku z požadavku.

Pokud je override nastaveno zařazení více položek se stejným názvem, výsledkem je nastavení záhlaví podle všech položek (které budou uvedeny vícekrát); ve výsledku se nastaví pouze uvedené hodnoty.		 No override

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, odchozí, back-end, chyba

  • Obory zásad: všechny obory

Odeslat žádost

Zásada send-request odešle poskytnutý požadavek na zadanou adresu URL a nečeká déle než nastavená hodnota časového limitu.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<send-request mode="new|copy" response-variable-name="" timeout="60 sec" ignore-error
="false|true">
  <set-url>...</set-url>
  <set-method>...</set-method>
  <set-header name="" exists-action="override|skip|append|delete">...</set-header>
  <set-body>...</set-body>
  <authentication-certificate thumbprint="thumbprint" />
</send-request>

Příklad

Tento příklad ukazuje jeden ze způsobů, jak ověřit referenční token s autorizačním serverem. Další informace o této ukázce najdete v tématu Použití externích služeb ze služby Azure API Management.

<inbound>
  <!-- Extract Token from Authorization header parameter -->
  <set-variable name="token" value="@(context.Request.Headers.GetValueOrDefault("Authorization","scheme param").Split(' ').Last())" />

  <!-- Send request to Token Server to validate token (see RFC 7662) -->
  <send-request mode="new" response-variable-name="tokenstate" timeout="20" ignore-error="true">
    <set-url>https://microsoft-apiappec990ad4c76641c6aea22f566efc5a4e.azurewebsites.net/introspection</set-url>
    <set-method>POST</set-method>
    <set-header name="Authorization" exists-action="override">
      <value>basic dXNlcm5hbWU6cGFzc3dvcmQ=</value>
    </set-header>
    <set-header name="Content-Type" exists-action="override">
      <value>application/x-www-form-urlencoded</value>
    </set-header>
    <set-body>@($"token={(string)context.Variables["token"]}")</set-body>
  </send-request>

  <choose>
        <!-- Check active property in response -->
        <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
            <!-- Return 401 Unauthorized with http-problem payload -->
            <return-response>
                <set-status code="401" reason="Unauthorized" />
                <set-header name="WWW-Authenticate" exists-action="override">
                    <value>Bearer error="invalid_token"</value>
                </set-header>
            </return-response>
        </when>
    </choose>
  <base />
</inbound>

Elementy

Element Popis Povinné
send-request Kořenový prvek. Yes
url Adresa URL požadavku. Ne, pokud mode=copy; jinak ano.
method Metoda HTTP pro požadavek. Ne, pokud mode=copy; jinak ano.
header Hlavička požadavku. Pro více hlaviček požadavků použijte více prvků hlavičky. No
text Text požadavku. No
ověřovací certifikát Certifikát, který se má použít pro ověřování klientů No

Atributy

Atribut Popis Povinné Výchozí
mode="string" Určuje, jestli se jedná o nový požadavek, nebo kopii aktuálního požadavku. V režimu odchozích přenosů mode=copy neicializuje text požadavku. No Nová
response-variable-name="string" Název kontextové proměnné, která obdrží objekt odpovědi. Pokud proměnná neexistuje, vytvoří se po úspěšném spuštění zásady a bude přístupná prostřednictvím context.Variable kolekce. Yes –
timeout="integer" Interval časového limitu v sekundách před voláním adresy URL selže. No 60
ignorovat chybu Pokud je hodnota true a výsledkem požadavku je chyba, bude chyba ignorována a proměnná odpovědi bude obsahovat hodnotu null. No false (nepravda)
name Určuje název hlavičky, který se má nastavit. Yes –
exist-action Určuje, jaká akce se má provést, když už je záhlaví zadané. Tento atribut musí mít jednu z následujících hodnot.

- přepsání – nahradí hodnotu existující hlavičky.
- skip - nenahrazuje existující hodnotu záhlaví.
- připojení – připojí hodnotu k existující hodnotě záhlaví.
- odstranit – odebere hlavičku z požadavku.

Pokud je override nastaveno zařazení více položek se stejným názvem, výsledkem je nastavení záhlaví podle všech položek (které budou uvedeny vícekrát); ve výsledku se nastaví pouze uvedené hodnoty.		 No override

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, odchozí, back-end, chyba

  • Obory zásad: všechny obory

Nastavení proxy serveru HTTP

Tato proxy zásada umožňuje směrovat požadavky předávané na back-endy prostřednictvím proxy serveru HTTP. Mezi bránou a proxy serverem se podporuje jenom PROTOKOL HTTP (ne HTTPS). Pouze základní ověřování a ověřování NTLM

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<proxy url="http://hostname-or-ip:port" username="username" password="password" />

Příklad

Všimněte si použití vlastností jako hodnot uživatelského jména a hesla, abyste se vyhnuli ukládání citlivých informací v dokumentu zásad.

<proxy url="http://192.168.1.1:8080" username={{username}} password={{password}} />

Elementy

Element Popis Povinné
proxy Kořenový element Yes

Atributy

Atribut Popis Povinné Výchozí
url="string" Adresa URL proxy serveru ve formě http://host:port. Yes –
username="string" Uživatelské jméno, které se má použít k ověřování s proxy serverem. No –
password="string" Heslo, které se má použít k ověřování pomocí proxy serveru. No –

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí

  • Obory zásad: všechny obory

Nastavení metody požadavku

Zásady set-method umožňují změnit metodu požadavku HTTP pro požadavek.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<set-method>METHOD</set-method>

Příklad

Tato ukázková zásada, která používá zásadu set-method , ukazuje příklad odeslání zprávy do chatovací místnosti Slack, pokud je kód odpovědi HTTP větší nebo roven 500. Další informace o této ukázce najdete v tématu Použití externích služeb ze služby Azure API Management.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

Elementy

Element Popis Povinné
set-method Kořenový prvek. Hodnota elementu určuje metodu HTTP. Yes

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, on-error

  • Obory zásad: všechny obory

Nastavení stavových kódů

Zásady set-status nastaví stavový kód HTTP na zadanou hodnotu.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<set-status code="" reason=""/>

Příklad

Tento příklad ukazuje, jak vrátit odpověď 401, pokud je autorizační token neplatný. Další informace najdete v tématu Použití externích služeb ze služby Azure API Management

<choose>
  <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
    <return-response response-variable-name="existing response variable">
      <set-status code="401" reason="Unauthorized" />
      <set-header name="WWW-Authenticate" exists-action="override">
        <value>Bearer error="invalid_token"</value>
      </set-header>
    </return-response>
  </when>
</choose>

Elementy

Element Popis Povinné
set-status Kořenový prvek. Yes

Atributy

Atribut Popis Povinné Výchozí
code="integer" Stavový kód HTTP, který se má vrátit. Yes –
reason="string" Popis důvodu vrácení stavového kódu Yes –

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, odchozí, back-end, chyba
  • Obory zásad: všechny obory

Nastavit proměnnou

Zásada set-variable deklaruje kontextovou proměnnou a přiřadí jí hodnotu zadanou výrazem nebo řetězcovým literálem. pokud výraz obsahuje literál, bude převeden na řetězec a typ hodnoty bude System.String.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<set-variable name="variable name" value="Expression | String literal" />

Příklad

Následující příklad ukazuje zásadu množiny proměnných v příchozí části. Tato zásada proměnné sady vytvoří isMobile logickou kontextovou proměnnou nastavenou na true, pokud User-Agent hlavička požadavku obsahuje text iPad nebo iPhone.

<set-variable name="IsMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPhone"))" />

Elementy

Element Popis Povinné
set-variable Kořenový prvek. Yes

Atributy

Atribut Popis Vyžadováno
name Název proměnné. Yes
hodnota Hodnota proměnné. Může se jednat o výraz nebo literálovou hodnotu. Yes

Využití

Tuto zásadu je možné použít v následujících částech zásad a oborech.

  • Oddíly zásad: příchozí, odchozí, back-end, chyba
  • Obory zásad: všechny obory

Povolené typy

Výrazy použité v set-variable zásadách musí vracet jeden z následujících základních typů.

  • System.Boolean
  • System.SByte
  • System.Byte
  • System.UInt16
  • System.UInt32
  • System.UInt64
  • System.Int16
  • System.Int32
  • System.Int64
  • System.Decimal
  • System.Single
  • System.Double
  • System.Guid
  • System.String
  • System.Char
  • System.DateTime
  • System.TimeSpan
  • System.Byte?
  • System.UInt16?
  • System.UInt32?
  • System.UInt64?
  • System.Int16?
  • System.Int32?
  • System.Int64?
  • System.Decimal?
  • System.Single?
  • System.Double?
  • System.Guid?
  • System.String?
  • System.Char?
  • System.DateTime?

Trasování

Tato trace zásada přidá vlastní trasování do výstupu inspektoru rozhraní API, telemetrie Application Insights nebo protokolů prostředků.

  • Zásada při aktivaci trasování přidá do výstupu inspektoru rozhraní API vlastní trasování, tj. Ocp-Apim-Trace hlavička požadavku je přítomná a nastavená na true a Ocp-Apim-Subscription-Key hlavička požadavku je k dispozici a obsahuje platný klíč, který umožňuje trasování.
  • Zásada vytvoří telemetrii trasování ve službě Application Insights, pokud je povolená integrace Application Insights a severity zadaná v zásadách je rovna nebo větší než verbosity zadaná v nastavení diagnostiky.
  • Zásada přidá vlastnost v položce protokolu, pokud jsou povoleny protokoly prostředků a úroveň závažnosti zadaná v zásadě je na nebo vyšší úrovni než úroveň podrobností zadaná v nastavení diagnostiky.
  • Na zásadu nemá vliv vzorkování Application Insights. Všechny vyvolání zásad se zaprotokolují.

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách


<trace source="arbitrary string literal" severity="verbose|information|error">
    <message>String literal or expressions</message>
    <metadata name="string literal or expressions" value="string literal or expressions"/>
</trace>

Příklad

<trace source="PetStore API" severity="verbose">
    <message>@((string)context.Variables["clientConnectionID"])</message>
    <metadata name="Operation Name" value="New-Order"/>
</trace>

Elementy

Element Popis Povinné
trasování Kořenový prvek. Yes
zpráva Řetězec nebo výraz, který se má protokolovat. Yes
zprostředkovatele identity Přidá vlastní vlastnost do telemetrie trasování Application Insights. No

Atributy

Atribut Popis Povinné Výchozí
source Řetězcový literál smysluplný pro prohlížeč trasování a určení zdroje zprávy. Yes –
severity Určuje úroveň závažnosti trasování. Povolené hodnoty jsou verbose, informationerror (od nejnižších po nejvyšší). No Verbose
name Název vlastnosti. Yes –
hodnota Hodnota vlastnosti Yes –

Využití

Tuto zásadu lze použít v následujících částech zásad a oborech .

  • Oddíly zásad: příchozí, odchozí, back-end, chyba

  • Obory zásad: všechny obory

Wait

Zásada wait provádí své okamžité podřízené zásady paralelně a před dokončením čeká na dokončení všech nebo jedné z jejích bezprostředně podřízených zásad. Zásada čekání může mít jako své okamžité podřízené zásady odeslat požadavek, získat hodnotu z mezipaměti a zásady toku řízení .

Poznámka

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady API Management.

Prohlášení o zásadách

<wait for="all|any">
  <!--Wait policy can contain send-request, cache-lookup-value,
        and choose policies as child elements -->
</wait>

Příklad

V následujícím příkladu existují dvě choose zásady jako okamžité podřízené zásady wait zásady. Každá z těchto choose zásad se provádí paralelně. Každá choose zásada se pokusí načíst hodnotu uloženou v mezipaměti. Pokud dojde k chybě mezipaměti, zavolá se back-endová služba k zadání hodnoty. V tomto příkladu wait se zásada nedokončí, dokud se nedokončí všechny její okamžité podřízené zásady, protože for atribut je nastaven na all. V tomto příkladu jsou kontextové proměnné (execute-branch-one, value-one, execute-branch-twoa value-two) deklarovány mimo rozsah této ukázkové zásady.

<wait for="all">
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-one="])">
      <cache-lookup-value key="key-one" variable-name="value-one" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-one="))">
          <send-request mode="new" response-variable-name="value-one">
            <set-url>https://backend-one</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-two="])">
      <cache-lookup-value key="key-two" variable-name="value-two" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-two="))">
          <send-request mode="new" response-variable-name="value-two">
            <set-url>https://backend-two</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
</wait>

Elementy

Element Popis Povinné
Počkej Kořenový prvek. Může obsahovat pouze send-requestpodřízené prvky , cache-lookup-valuea choose zásady. Yes

Atributy

Atribut Popis Povinné Výchozí
pro Určuje, jestli wait zásady čekají na dokončení všech okamžitě podřízených zásad, nebo pouze na jednu. Povolené hodnoty jsou následující:

- all – počkejte na dokončení všech zásad okamžitého podřízeného dítěte.
- any - počkejte na dokončení jakékoli okamžité podřízené zásady. Jakmile se dokončí první okamžitá podřízená zásada, wait zásady se dokončí a spustí všechny ostatní okamžitě podřízené zásady.		 No Vše

Využití

Tuto zásadu je možné použít v následujících částech a oborech zásad.

  • Oddíly zásad: příchozí, odchozí, back-end
  • Obory zásad: všechny obory

Další kroky

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