Utforska API Management-principer

Slutförd

I Azure API Management gör principer att utgivaren kan ändra beteendet för API:et via konfiguration. Principer är en samling instruktioner som körs sekventiellt på begäran eller svar från ett API.

Principer tillämpas i gatewayen som finns mellan API-konsumenten och det hanterade API:et. Gatewayen tar emot alla begäranden och vidarebefordrar dem vanligtvis oförändrade till det underliggande API:et. En princip kan dock tillämpa ändringar på både inkommande begäran och utgående svar. Principuttryck kan användas som attributvärden eller textvärden i API Management-principer, under förutsättning att principen tillåter det.

Förstå principkonfiguration

Principdefinitionen är ett enkelt XML-dokument som beskriver en sekvens med inkommande och utgående instruktioner. XML-koden kan redigeras direkt i definitionsfönstret.

Konfigurationen är indelad i inbound, backend, outboundoch on-error. Serien med angivna principinstruktioner körs för en begäran och ett svar.

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

Om det uppstår ett fel under bearbetningen av en begäran hoppas eventuella återstående steg i avsnitten inbound, backendeller outbound över och körningen hoppar till -instruktionerna i on-error avsnittet. Genom att placera principinstruktioner on-error i avsnittet kan du granska felet med hjälp context.LastError av egenskapen, inspektera och anpassa felsvaret set-body med hjälp av principen och konfigurera vad som händer om ett fel inträffar.

Principuttryck

Om inte principen anger något annat kan principuttryck användas som attributvärden eller textvärden i någon av API Management-principerna. Ett principuttryck är antingen:

• en enda C#-instruktion som omges av @(expression), eller
• ett C#-kodblock med flera instruktioner, omgivet av @{expression}, som returnerar ett värde

Varje uttryck har åtkomst till den implicit angivna context variabeln och en tillåten delmängd av .NET Framework-typer.

Principuttryck är ett avancerat sätt att styra trafik och ändra API-beteende utan att du behöver skriva specialiserad kod eller ändra serverdelstjänster.

I följande exempel används principuttryck och principen för set-header för att lägga till användardata i den inkommande begäran. Det tillagda huvudet innehåller användar-ID:t som är associerat med prenumerationsnyckeln i begäran och den region där gatewayen som bearbetar begäran finns.

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

Tillämpa principer som anges i olika omfång

Om du har en princip på global nivå och en princip som konfigurerats för ett API tillämpas båda principerna när det specifika API:et används. API Management möjliggör deterministisk ordning av kombinerade principinstruktioner via baselementet.

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

I föregående exempelprincipdefinition skulle instruktionen cross-domain köras först. Principen find-and-replace skulle köras efter alla principer i ett bredare omfång.

Filtrera svarsinnehåll

Principen som definieras i följande exempel visar hur du filtrerar dataelement från svarsnyttolasten baserat på den produkt som är associerad med begäran.

Kodfragmentet förutsätter att svarsinnehållet formateras som JSON och innehåller egenskaper på rotnivå med namnet minutvis, varje timme, dagligen och flaggor.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>