API Management advanced policies (Geavanceerde beleidsregels API Management)

  • Artikel
  • 25 minuten om te lezen

Dit artikel bevat een verwijzing naar geavanceerde beleidsregels voor API Management, zoals beleidsregels die zijn gebaseerd op beleidsexpressies.

Meer informatie over beleidsregels:

Geavanceerde beleidsregels

Controlestroom

Het choose beleid past ingesloten beleidsinstructies toe op basis van het resultaat van de evaluatie van Boole-expressies, vergelijkbaar met een if-then-else of een switchconstructie in een programmeertaal.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Het beheerstroombeleid moet ten minste één <when/> element bevatten. Het <otherwise/> element is optioneel. Voorwaarden in <when/> elementen worden geëvalueerd in volgorde van hun uiterlijk binnen het beleid. Beleidsinstructie(s) die zijn ingesloten in het eerste <when/> element met voorwaardekenmerk dat gelijk is aan is true , worden toegepast. Beleidsregels die zijn opgenomen in het <otherwise/> element, indien aanwezig, worden toegepast als alle kenmerken van de <when/> elementvoorwaarde zijn false.

Voorbeelden

Voorbeeld

In het volgende voorbeeld ziet u een setvariabelebeleid en twee beleidsregels voor controlestromen.

Het setvariabelebeleid bevindt zich in de binnenkomende sectie en maakt een isMobile Booleaanse contextvariabele die is ingesteld op waar als de User-Agent aanvraagheader de tekst iPad bevat of .iPhone

Het eerste controlestroombeleid bevindt zich ook in de sectie Binnenkomend en past voorwaardelijk een van de twee parameterbeleidsregels voor queryreeksen instellen toe, afhankelijk van de waarde van de isMobile contextvariabele.

Het tweede controlestroombeleid bevindt zich in de sectie Uitgaand en past voorwaardelijk het XML-beleid converteren naar JSON toe wanneer isMobile dit is ingesteld op 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>

Voorbeeld

In dit voorbeeld ziet u hoe u inhoudsfiltering uitvoert door gegevenselementen te verwijderen uit het antwoord dat is ontvangen van de back-endservice bij het gebruik van het Starter product. Het voorbeeld van een back-endantwoord bevat eigenschappen op hoofdniveau die vergelijkbaar zijn met de 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>

Elementen

Element Beschrijving Vereist
Kies Hoofdelement. Yes
Wanneer De voorwaarde die moet worden gebruikt voor de if of ifelse onderdelen van het choose beleid. Als het choose beleid meerdere when secties heeft, worden ze opeenvolgend geëvalueerd. Zodra het condition element wordt geëvalueerd true, worden er geen verdere when voorwaarden geëvalueerd. Yes
Anders Bevat het beleidsfragment dat moet worden gebruikt als geen van de when voorwaarden wordt geëvalueerd true. No

Kenmerken

Kenmerk Beschrijving Vereist
condition="Booleaanse expressie | Booleaanse constante" De Booleaanse expressie of constante die moet worden geëvalueerd wanneer de beleidsinstructie when wordt geëvalueerd. Yes

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Aanvraag doorsturen

Het forward-request beleid stuurt de binnenkomende aanvraag door naar de back-endservice die is opgegeven in de aanvraagcontext. De URL van de back-endservice wordt opgegeven in de API-instellingen en kan worden gewijzigd met behulp van het set back-endservicebeleid .

Belangrijk

  • Dit beleid is vereist om aanvragen door te sturen naar een API-back-end. Standaard stelt API Management dit beleid in op het globale bereik.
  • Als u dit beleid verwijdert, wordt de aanvraag niet doorgestuurd naar de back-endservice. Beleidsregels in de sectie Uitgaand verkeer worden onmiddellijk geëvalueerd nadat het beleid is voltooid in de sectie Binnenkomend verkeer.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeelden

Voorbeeld

Het volgende API-beleid stuurt alle API-aanvragen door naar de back-endservice met een time-outinterval van 60 seconden.

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

Voorbeeld

Dit beleid op bewerkingsniveau maakt gebruik van het base element om het back-endbeleid over te nemen van het bereik op bovenliggend API-niveau.

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

Voorbeeld

Met dit beleid op bewerkingsniveau worden alle aanvragen expliciet doorgestuurd naar de back-endservice met een time-out van 120 en wordt het back-endbeleid op het bovenliggende API-niveau niet overgenomen. Als de back-endservice reageert met een foutcode van 400 tot en met 599, wordt de sectie on-error geactiveerd.

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

Voorbeeld

Dit beleid op bewerkingsniveau stuurt geen aanvragen door naar de back-endservice.

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

Elementen

Element Beschrijving Vereist
doorstuuraanvraag Hoofdelement. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
time-out="integer" De hoeveelheid tijd in seconden die moet worden gewacht totdat de HTTP-antwoordheaders worden geretourneerd door de back-endservice voordat er een time-outfout optreedt. De minimumwaarde is 0 seconden. Waarden die langer zijn dan 240 seconden, worden mogelijk niet gehonoreerd omdat de onderliggende netwerkinfrastructuur na deze tijd niet-actieve verbindingen kan verwijderen. No Geen
follow-redirects="false | waar" Hiermee geeft u op of omleidingen van de back-endservice worden gevolgd door de gateway of worden geretourneerd naar de aanroeper. No onjuist
buffer-request-body="false | waar" Wanneer de aanvraag is ingesteld op 'true', wordt de aanvraag gebufferd en opnieuw gebruikt bij opnieuw proberen. No onjuist
buffer-response="false | waar" Beïnvloedt de verwerking van gesegmenteerde antwoorden. Wanneer dit is ingesteld op 'false', wordt elk segment dat van de back-end is ontvangen, onmiddellijk teruggezet naar de aanroeper. Als deze optie is ingesteld op 'true', worden segmenten gebufferd (8 kB, tenzij het einde van de stream wordt gedetecteerd) en worden ze alleen teruggezet naar de beller.

Ingesteld op 'false' met back-ends, zoals de implementatie van door de server verzonden gebeurtenissen (SSE) waarvoor inhoud onmiddellijk moet worden geretourneerd of gestreamd naar de beller.		 No true
fail-on-error-status-code="false | waar" Als deze waarde is ingesteld op waar, activeert u de sectie Fout bij reactiecodes in het bereik van 400 tot en met 599. No onjuist

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: back-end
  • Beleidsbereiken: alle bereiken

Gelijktijdigheid beperken

Het limit-concurrency beleid voorkomt dat ingesloten beleidsregels worden uitgevoerd door meer dan het opgegeven aantal aanvragen op elk gewenst moment. Wanneer dat aantal wordt overschreden, mislukken nieuwe aanvragen onmiddellijk met de 429 statuscode Te veel aanvragen.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeelden

Voorbeeld

In het volgende voorbeeld ziet u hoe u het aantal aanvragen dat wordt doorgestuurd naar een back-end beperkt op basis van de waarde van een contextvariabele.

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

Elementen

Element Beschrijving Vereist
limiet gelijktijdigheid Hoofdelement. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
sleutel Een tekenreeks. Expressie toegestaan. Hiermee geeft u het gelijktijdigheidsbereik op. Kan worden gedeeld door meerdere beleidsregels. Yes N.v.t.
max-count Een geheel getal. Hiermee geeft u een maximum aantal aanvragen op dat is toegestaan om het beleid in te voeren. Yes N.v.t.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Aanmelden bij Event Hub

Het log-to-eventhub beleid verzendt berichten in de opgegeven indeling naar een Event Hub die is gedefinieerd door een Logger-entiteit. Zoals de naam al aangeeft, wordt het beleid gebruikt voor het opslaan van geselecteerde aanvraag- of antwoordcontextinformatie voor online- of offlineanalyse.

Notitie

For a step-by-step guide on configuring an event hub and logging events, see How to log API Management events with Azure Event Hubs.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

Elke tekenreeks kan worden gebruikt als de waarde die moet worden vastgelegd in Event Hubs. In dit voorbeeld worden de datum en tijd, de naam van de implementatieservice, de aanvraag-id, het IP-adres en de naam van de bewerking voor alle binnenkomende aanroepen geregistreerd bij de Event Hub Logger geregistreerd bij de contoso-logger 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>

Elementen

Element Beschrijving Vereist
log-to-eventhub Hoofdelement. De waarde van dit element is de tekenreeks om u aan te melden bij uw Event Hub. Yes

Kenmerken

Kenmerk Beschrijving Vereist
logger-id De id van de Logger die is geregistreerd bij uw API Management service. Yes
partitie-id Hiermee geeft u de index van de partitie waar berichten worden verzonden. Optioneel. Dit kenmerk wordt mogelijk niet gebruikt als partition-key dit wordt gebruikt.
partitiesleutel Hiermee geeft u de waarde die wordt gebruikt voor partitietoewijzing wanneer berichten worden verzonden. Optioneel. Dit kenmerk wordt mogelijk niet gebruikt als partition-id dit wordt gebruikt.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Metrische gegevens verzenden

Het emit-metric beleid verzendt aangepaste metrische gegevens in de opgegeven indeling naar Application Insights.

Notitie

Tip

Meer informatie over het instellen of bewerken van API Management beleid.

Beleidsverklaring

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

Voorbeeld

In het volgende voorbeeld wordt een aangepaste metrische waarde verzonden om het aantal API-aanvragen samen met gebruikers-id, client-IP en API-id als aangepaste dimensies te tellen.

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

Elementen

Element Beschrijving Vereist
emit-metric Hoofdelement. De waarde van dit element is de tekenreeks voor het verzenden van uw aangepaste metrische gegevens. Yes
dimensie Subelement. Voeg een of meer van deze elementen toe voor elke dimensie die is opgenomen in de aangepaste metrische gegevens. Yes

Kenmerken

emit-metric

Kenmerk Beschrijving Vereist Type Standaardwaarde
naam Naam van aangepaste metrische gegevens. Yes tekenreeks, expressie N.v.t.
naamruimte Naamruimte van aangepaste metrische gegevens. No tekenreeks, expressie API Management
waarde Waarde van aangepaste metrische gegevens. No int, expressie 1

dimensie

Kenmerk Beschrijving Vereist Type Standaardwaarde
naam Naam van dimensie. Yes tekenreeks, expressie N.v.t.
waarde Waarde van dimensie. Kan alleen worden weggelaten als name deze overeenkomt met een van de standaarddimensies. Zo ja, dan wordt de waarde opgegeven op basis van de dimensienaam. No tekenreeks, expressie N.v.t.

Standaarddimensienamen die zonder waarde kunnen worden gebruikt:

  • API-id
  • Bewerkings-id
  • Product-id
  • Gebruikers-id
  • Abonnements-id
  • Locatie-id
  • Gateway-id

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Gesimuleerd antwoord

De mock-response, zoals de naam al aangeeft, wordt gebruikt om API's en bewerkingen te mocken. Hiermee wordt de normale pijplijnuitvoering afgebroken en wordt een gesimuleerd antwoord op de aanroeper geretourneerd. Het beleid probeert altijd antwoorden van hoogste kwaliteit te retourneren. Het geeft de voorkeur aan voorbeelden van antwoordinhoud, indien beschikbaar. Er worden voorbeeldantwoorden gegenereerd op basis van schema's, wanneer er schema's worden opgegeven en voorbeelden niet. Als er geen voorbeelden of schema's worden gevonden, worden antwoorden zonder inhoud geretourneerd.

Tip

Meer informatie over het instellen of bewerken van API Management beleid.

Beleidsverklaring

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

Voorbeelden

<!-- 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'/>

Elementen

Element Beschrijving Vereist
mock-response Hoofdelement. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
statuscode Hiermee geeft u antwoordstatuscode op en wordt gebruikt om het bijbehorende voorbeeld of schema te selecteren. No 200
inhoudstype Hiermee geeft u Content-Type de waarde van de antwoordheader op en wordt gebruikt om een bijbehorend voorbeeld of schema te selecteren. No Geen

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: inkomend, uitgaand, on-error

  • Beleidsbereiken: alle bereiken

Opnieuw proberen

Het retry beleid voert eenmaal onderliggende beleidsregels uit en probeert vervolgens de uitvoering opnieuw totdat het opnieuw conditionfalse wordt geprobeerd of opnieuw te proberen count is uitgeput.

Tip

Meer informatie over het instellen of bewerken van API Management beleid.

Beleidsverklaring


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

Voorbeeld

In het volgende voorbeeld wordt het doorsturen van aanvragen maximaal tien keer geprobeerd met behulp van een algoritme voor exponentiële nieuwe pogingen. Aangezien first-fast-retry deze is ingesteld op onwaar, zijn alle nieuwe pogingen onderworpen aan het algoritme voor exponentiële nieuwe pogingen.


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

Elementen

Element Beschrijving Vereist
retry Hoofdelement. Kan andere beleidsregels bevatten als onderliggende elementen. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
Voorwaarde Een booleaanse letterlijke waarde of expressie die aangeeft of nieuwe pogingen moeten worden gestopt (false) of voortgezet (true). Yes N.v.t.
count Een positief getal dat het maximum aantal nieuwe pogingen aangeeft dat moet worden geprobeerd. Yes N.v.t.
interval Een positief getal in seconden dat het wachttijdinterval aangeeft tussen de nieuwe pogingen. Yes N.v.t.
max-interval Een positief getal in seconden dat het maximale wachttijdsinterval tussen de nieuwe pogingen aangeeft. Het wordt gebruikt om een algoritme voor exponentiële nieuwe pogingen te implementeren. No N.v.t.
delta Een positief getal in seconden dat de intervalverhoging voor het wachtinterval aangeeft. Het wordt gebruikt om de lineaire en exponentiële algoritmen voor opnieuw proberen te implementeren. No N.v.t.
first-fast-retry Als deze optie is ingesteld true , wordt de eerste nieuwe poging onmiddellijk uitgevoerd. No false

Notitie

Wanneer alleen het interval opgegeven is, worden nieuwe pogingen met een vast interval uitgevoerd. Wanneer alleen de interval en delta zijn opgegeven, wordt een algoritme voor het opnieuw proberen van een lineair interval gebruikt, waarbij de wachttijd tussen nieuwe pogingen wordt berekend volgens de volgende formule - . interval + (count - 1)*delta Wanneer het intervalmax-intervaldeltaalgoritme voor exponentieel interval opnieuw proberen wordt toegepast en de wachttijd tussen de nieuwe pogingen exponentieel toeneemt van de waarde naar de waarde intervalmax-interval volgens de volgende formule- min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval)

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken. Gebruiksbeperkingen voor onderliggend beleid worden overgenomen door dit beleid.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Antwoord retourneren

Het return-response beleid verwijdert de uitvoering van pijplijnen en retourneert een standaard- of aangepaste reactie op de aanroeper. Het standaardantwoord is 200 OK zonder hoofdtekst. Aangepast antwoord kan worden opgegeven via een contextvariabele of beleidsinstructies. Wanneer beide worden opgegeven, wordt het antwoord in de contextvariabele gewijzigd door de beleidsinstructies voordat ze worden geretourneerd naar de aanroeper.

Tip

Meer informatie over het instellen of bewerken van API Management beleid.

Beleidsverklaring

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

Voorbeeld

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

Elementen

Element Beschrijving Vereist
return-response Hoofdelement. Yes
set-header Een beleidsinstructie voor set-headers . No
set-body Een beleidsinstructie voor de set-body . No
set-status Een beleidsverklaring voor de setstatus . No

Kenmerken

Kenmerk Beschrijving Vereist
response-variable-name De naam van de contextvariabele waarnaar wordt verwezen, bijvoorbeeld een upstream send-request-beleid en met een Response object Optioneel.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Aanvraag voor één manier verzenden

Het send-one-way-request beleid verzendt de opgegeven aanvraag naar de opgegeven URL zonder te wachten op een antwoord.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

Dit voorbeeldbeleid toont een voorbeeld van het gebruik van het beleid voor het send-one-way-request verzenden van een bericht naar een Slack-chatruimte als de HTTP-antwoordcode groter is dan of gelijk is aan 500. Zie Externe services gebruiken vanuit de Azure API Management-service voor meer informatie over dit voorbeeld.

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

Elementen

Element Beschrijving Vereist
send-one-way-request Hoofdelement. Yes
set-URL De URL van de aanvraag. Nee als modus=kopiëren; Anders ja.
method De HTTP-methode voor de aanvraag. Nee als modus=kopiëren; Anders ja.
koptekst Aanvraagheader. Gebruik meerdere headerelementen voor meerdere aanvraagheaders. No
body De hoofdtekst van de aanvraag. No
verificatiecertificaat Certificaat dat moet worden gebruikt voor clientverificatie No

Kenmerken

Kenmerk Beschrijving Vereist Standaard
mode="string" Bepaalt of dit een nieuwe aanvraag of een kopie van de huidige aanvraag is. In de uitgaande modus initialiseert mode=copy de hoofdtekst van de aanvraag niet. No Nieuw
naam Hiermee geeft u de naam van de in te stellen header op. Yes N.v.t.
bestaat-actie Hiermee geeft u op welke actie moet worden uitgevoerd wanneer de header al is opgegeven. Dit kenmerk moet een van de volgende waarden hebben.

- overschrijven - vervangt de waarde van de bestaande header.
- overslaan - vervangt de bestaande headerwaarde niet.
- toevoegen: voegt de waarde toe aan de bestaande headerwaarde.
- verwijderen - verwijdert de header uit de aanvraag.

Wanneer deze is ingesteld op override het inschakelen van meerdere vermeldingen met dezelfde naam, wordt de koptekst ingesteld op basis van alle vermeldingen (die meerdere keren worden weergegeven). Alleen vermelde waarden worden in het resultaat ingesteld.		 No overschrijven

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Aanvraag verzenden

Het send-request beleid verzendt de opgegeven aanvraag naar de opgegeven URL en wacht niet langer dan de opgegeven time-outwaarde.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

In dit voorbeeld ziet u een manier om een verwijzingstoken te verifiëren met een autorisatieserver. Zie Externe services gebruiken vanuit de Azure API Management-service voor meer informatie over dit voorbeeld.

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

Elementen

Element Beschrijving Vereist
verzenden-aanvraag Hoofdelement. Yes
url De URL van de aanvraag. Nee als modus=kopiëren; Anders ja.
method De HTTP-methode voor de aanvraag. Nee als modus=kopiëren; Anders ja.
koptekst Aanvraagheader. Gebruik meerdere headerelementen voor meerdere aanvraagheaders. No
body De hoofdtekst van de aanvraag. No
verificatiecertificaat Certificaat dat moet worden gebruikt voor clientverificatie No

Kenmerken

Kenmerk Beschrijving Vereist Standaard
mode="string" Bepaalt of dit een nieuwe aanvraag of een kopie van de huidige aanvraag is. In de uitgaande modus initialiseert mode=copy de hoofdtekst van de aanvraag niet. No Nieuw
response-variable-name="string" De naam van de contextvariabele die een antwoordobject ontvangt. Als de variabele niet bestaat, wordt deze gemaakt na een geslaagde uitvoering van het beleid en wordt deze toegankelijk via context.Variable verzameling. Yes N.v.t.
time-out="integer" Het time-outinterval in seconden voordat de aanroep naar de URL mislukt. No 60
ignore-error Als waar en de aanvraag resulteert in een fout, wordt de fout genegeerd en bevat de antwoordvariabele een null-waarde. No onjuist
naam Hiermee geeft u de naam van de in te stellen header op. Yes N.v.t.
bestaat-actie Hiermee geeft u op welke actie moet worden uitgevoerd wanneer de header al is opgegeven. Dit kenmerk moet een van de volgende waarden hebben.

- overschrijven - vervangt de waarde van de bestaande header.
- overslaan - vervangt de bestaande headerwaarde niet.
- toevoegen: voegt de waarde toe aan de bestaande headerwaarde.
- verwijderen - verwijdert de header uit de aanvraag.

Wanneer deze is ingesteld op override het inschakelen van meerdere vermeldingen met dezelfde naam, wordt de koptekst ingesteld op basis van alle vermeldingen (die meerdere keren worden weergegeven). Alleen vermelde waarden worden in het resultaat ingesteld.		 No overschrijven

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

HTTP-proxy instellen

Met proxy het beleid kunt u aanvragen routeren die zijn doorgestuurd naar back-ends via een HTTP-proxy. Alleen HTTP (niet HTTPS) wordt ondersteund tussen de gateway en de proxy. Alleen basis- en NTLM-verificatie.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

Let op het gebruik van eigenschappen als waarden van de gebruikersnaam en het wachtwoord om te voorkomen dat gevoelige informatie wordt opgeslagen in het beleidsdocument.

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

Elementen

Element Beschrijving Vereist
proxy Hoofdelement Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
url="string" Proxy-URL in de vorm van http://host:port. Yes N.v.t.
username="string" Gebruikersnaam die moet worden gebruikt voor verificatie met de proxy. No N.v.t.
password="string" Wachtwoord dat moet worden gebruikt voor verificatie met de proxy. No N.v.t.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend verkeer

  • Beleidsbereiken: alle bereiken

Aanvraagmethode instellen

Met set-method het beleid kunt u de HTTP-aanvraagmethode voor een aanvraag wijzigen.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

Dit voorbeeldbeleid dat gebruikmaakt van het set-method beleid toont een voorbeeld van het verzenden van een bericht naar een Slack-chatruimte als de HTTP-antwoordcode groter is dan of gelijk is aan 500. Zie Externe services gebruiken vanuit de Azure API Management-service voor meer informatie over dit voorbeeld.

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

Elementen

Element Beschrijving Vereist
set-method Hoofdelement. De waarde van het element geeft de HTTP-methode op. Yes

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomende, on-error

  • Beleidsbereiken: alle bereiken

Statuscode instellen

Het set-status beleid stelt de HTTP-statuscode in op de opgegeven waarde.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

In dit voorbeeld ziet u hoe u een 401-antwoord retourneert als het autorisatietoken ongeldig is. Zie Externe services gebruiken vanuit de Azure API Management-service voor meer informatie

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

Elementen

Element Beschrijving Vereist
set-status Hoofdelement. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
code="integer" De HTTP-statuscode die moet worden geretourneerd. Yes N.v.t.
reason="string" Een beschrijving van de reden voor het retourneren van de statuscode. Yes N.v.t.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error
  • Beleidsbereiken: alle bereiken

Variabele instellen

Het set-variable beleid declareert een contextvariabele en wijst deze toe aan een waarde die is opgegeven via een expressie of een letterlijke tekenreeks. als de expressie een letterlijke waarde bevat, wordt deze geconverteerd naar een tekenreeks en het type van de waarde.System.String

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

In het volgende voorbeeld ziet u een set variabelebeleid in de sectie Binnenkomend verkeer. Met dit setvariabelebeleid wordt een isMobile Booleaanse contextvariabele gemaakt die is ingesteld op waar als de User-Agent aanvraagheader de tekst iPad bevat of .iPhone

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

Elementen

Element Beschrijving Vereist
set-variable Hoofdelement. Yes

Kenmerken

Kenmerk Beschrijving Vereist
naam De naam van de variabele. Yes
waarde De waarde van de variabele. Dit kan een expressie of een letterlijke waarde zijn. Yes

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end, on-error
  • Beleidsbereiken: alle bereiken

Toegestane typen

Expressies die in het set-variable beleid worden gebruikt, moeten een van de volgende basistypen retourneren.

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

Tracering

Met trace het beleid wordt een aangepaste tracering toegevoegd aan de API Inspector-uitvoer, application Insights telemetrieën en/of resourcelogboeken.

  • Het beleid voegt een aangepaste tracering toe aan de API Inspector-uitvoer wanneer tracering wordt geactiveerd, dat wil gezegd hebben dat Ocp-Apim-Trace de aanvraagheader aanwezig is en is ingesteld op waar en Ocp-Apim-Subscription-Key de aanvraagheader aanwezig is en een geldige sleutel bevat waarmee tracering mogelijk is.
  • Het beleid maakt een traceringstelemetrie in application Insights, wanneer application Insights integratie is ingeschakeld en het severity opgegeven in het beleid gelijk is aan of groter is dan de verbosity opgegeven in de diagnostische instelling.
  • Met het beleid wordt een eigenschap toegevoegd in de logboekvermelding wanneer resourcelogboeken zijn ingeschakeld en het ernstniveau dat in het beleid is opgegeven, zich op of hoger bevindt dan het uitbreidingsniveau dat is opgegeven in de diagnostische instelling.

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie


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

Voorbeeld

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

Elementen

Element Beschrijving Vereist
tracering Hoofdelement. Yes
message Een tekenreeks of expressie die moet worden geregistreerd. Yes
metagegevens Hiermee voegt u een aangepaste eigenschap toe aan de Toepassing Insights Telemetrie traceren. No

Kenmerken

Kenmerk Beschrijving Vereist Standaard
source Letterlijke tekenreeks die zinvol is voor de traceringsviewer en de bron van het bericht opgeeft. Yes N.v.t.
ernst Hiermee geeft u het ernstniveau van de tracering op. Toegestane waarden zijn verbose, errorinformation(van laagste naar hoogste). No Uitgebreid
naam Naam van de eigenschap. Yes N.v.t.
waarde Waarde van de eigenschap. Yes N.v.t.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken .

  • Beleidssecties: inkomend, uitgaand, back-end, on-error

  • Beleidsbereiken: alle bereiken

Wait

Het wait beleid voert de onmiddellijke onderliggende beleidsregels parallel uit en wacht totdat alle of een van de directe onderliggende beleidsregels is voltooid voordat het is voltooid. Het wachtbeleid kan bestaan uit het onmiddellijke onderliggende beleid verzenden van aanvraag, waarde ophalen uit de cache en beleidsregels voor controlestromen .

Tip

Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Voorbeeld

In het volgende voorbeeld zijn er twee choose beleidsregels als direct onderliggend beleid van het wait beleid. Elk van deze choose beleidsregels wordt parallel uitgevoerd. Elk choose beleid probeert een waarde in de cache op te halen. Als er een cache ontbreekt, wordt een back-endservice aangeroepen om de waarde op te geven. In dit voorbeeld wordt het wait beleid pas voltooid als alle onderliggende beleidsregels zijn voltooid, omdat het for kenmerk is ingesteld op all. In dit voorbeeld worden de contextvariabelen (execute-branch-one, value-one, execute-branch-twoen value-two) gedeclareerd buiten het bereik van dit voorbeeldbeleid.

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

Elementen

Element Beschrijving Vereist
Wacht Hoofdelement. Mag alleen send-requestonderliggende elementen bevatten, cache-lookup-valueen choose beleidsregels. Yes

Kenmerken

Kenmerk Beschrijving Vereist Standaard
voor Bepaalt of het wait beleid wacht totdat alle directe onderliggende beleidsregels zijn voltooid of slechts één. Toegestane waarden zijn:

- all - wacht totdat alle directe onderliggende beleidsregels zijn voltooid
- any - wacht tot een direct onderliggend beleid is voltooid. Zodra het eerste onderliggende beleid is voltooid, wordt het wait beleid voltooid en wordt het uitvoeren van andere directe onderliggende beleidsregels beëindigd.		 No all

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en bereiken.

  • Beleidssecties: inkomend, uitgaand, back-end
  • Beleidsbereiken: alle bereiken

Volgende stappen

Zie voor meer informatie over het werken met beleid: