Dela via

Principer i Azure API Management

GÄLLER FÖR: Alla API Management-nivåer

I Azure API Management kan API-utgivare ändra API-beteendet genom konfiguration med hjälp av principer. I den här artikeln beskrivs hur du använder principer.

Policys är en samling instruktioner som körs sekventiellt på begäran eller svaret från ett API. API Management tillhandahåller mer än 75 principer som du kan konfigurera för att hantera vanliga API-scenarier som autentisering, hastighetsbegränsning, cachelagring och omvandling av begäranden eller svar. En fullständig lista finns i API Management policyreferens.

Populära principer är:

  • Formatera konvertering från XML till JSON.
  • Anropsfrekvensbegränsning för att begränsa antalet inkommande samtal från en utvecklare.
  • Filtrering av begäranden som kommer från vissa IP-adresser.

Principer tillämpas i gatewayen mellan API-konsumenten och det hanterade API:et. Även om gatewayen tar emot begäranden och vidarebefordrar dem, oförändrade, till det underliggande API:et, kan en princip tillämpa ändringar på både inkommande begäran och utgående svar.

Förstå principkonfiguration

Principdefinitioner är enkla XML-dokument som beskriver en sekvens med instruktioner som ska tillämpas på begäranden och svar. Portalen innehåller följande alternativ för att konfigurera principdefinitioner:

  • En guidad, formulärbaserad redigerare för att förenkla konfigurationen av populära principer utan att koda XML
  • En kodredigerare där du kan infoga XML-kodfragment eller redigera XML direkt

Mer information om hur du konfigurerar principer finns i Ange eller redigera principer.

XML-konfigurationen är indelad i avsnitten inbound, backend, outbound, och on-error. Den här serien med specificerade policyuttalanden körs i ordning för en begäran och ett svar. Så här ser det ut:

<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's an error condition go here -->
  </on-error>
</policies>

Exempel på princip-XML finns i API Management-principexempel i arkivet.

Felhantering

Om ett fel uppstår under bearbetningen av en begäran:

  • Eventuella återstående steg i avsnitten inbound, backendeller outbound hoppas över.
  • Körningen övergår till instruktionerna i avsnittet on-error.

Genom att placera policyuttalanden i on-error-avsnittet kan du:

  • Granska felet genom att använda egenskapen context.LastError.
  • Granska och anpassa felsvaret genom att använda set-body-policyn.
  • Konfigurera vad som händer om ett fel inträffar.

Mer information finns i Felhantering i API Management-principer.

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 något av följande:

  • En enda C#-instruktion omgiven i @(expression)
  • 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. Vissa principer baseras på principuttryck, till exempel Kontrollflöde och Ange variabel.

Räckvidder

Med API Management kan du definiera principer i följande omfång, som presenteras här från bredast till smalaste:

  • Global (alla API:er)
  • Arbetsyta (alla API:er som är associerade med en vald arbetsyta)
  • Produkt (alla API:er som är associerade med en vald produkt)
  • API (alla åtgärder i ett API)
  • Åtgärd (en enskild åtgärd i ett API)

När du konfigurerar en princip måste du först välja det omfång som principen gäller för.

Diagram som illustrerar de fem principomfattningarna.

Bra att känna till

  • För detaljerad kontroll för olika API-konsumenter kan du konfigurera principdefinitioner med mer än ett omfång.

  • Alla principer stöds inte i varje omfångs- och principavsnitt.

  • När du konfigurerar principdefinitioner i mer än ett omfång kontrollerar du principarv och principutvärderingsordningen i varje principavsnitt genom att placera elementet base .

  • Principer som tillämpas på API-begäranden påverkas också av begärandekontexten, inklusive förekomsten eller frånvaron av en prenumerationsnyckel som används i begäran, API:et eller produktomfånget för prenumerationsnyckeln och om API:et eller produkten kräver en prenumeration.

    Anteckning

    Om du använder en API-begränsad prenumeration, en prenumeration med alla API:er eller den inbyggda all-access-prenumerationen tillämpas inte principer som konfigurerats i produktomfånget på begäranden från den prenumerationen.

Mer information finns i:

GraphQL-matchningsprinciper

I API Management konfigureras en GraphQL-matchare med principer som är begränsade till en specifik åtgärdstyp och ett fält i ett GraphQL-schema.

  • API Management stöder för närvarande GraphQL-matchare som anger http-API, Azure Cosmos DB eller Azure SQL-datakällor. Du kan till exempel konfigurera en enskild http-data-source princip med element för att ange en begäran till (och eventuellt svara från) en HTTP-datakälla.
  • Du kan inte inkludera en matchningsprincip i principdefinitioner i andra omfång, till exempel API, produkt eller alla API:er. Principen ärver inte heller principer som konfigurerats i andra omfång.
  • Gatewayern utvärderar en princip på lösarnivå efter alla konfigurerade inbound-principer och backend-principer i pipelinen för principkörning.

Mer information finns i Konfigurera en GraphQL-matchare.

Få Hjälp med Copilot

Du kan få AI-hjälp från Copilot för att skapa och redigera api Management-principdefinitioner. Du kan använda Copilot för att skapa och uppdatera principer som matchar dina specifika krav utan att behöva känna till XML-syntaxen. Du kan också få förklaringar av befintliga principer. Och Copilot kan hjälpa dig att översätta principer som du kan ha konfigurerat i andra API-hanteringslösningar.

Exempelfråga:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot drivs av AI, så överraskningar och misstag är möjliga. Mer information finns i vanliga frågor och svar om användning av Copilot.

Exempel

Tillämpa principer som anges i olika omfång

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

Exempel på principdefinition i API-omfång:

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

I föregående exempel på principdefinition:

Anteckning

Om du tar bort elementet base i API-omfånget tillämpas endast principer som konfigurerats i API-omfånget. Policier som konfigurerats för produkten och bredare omfattningar tillämpas inte.

Använda principuttryck för att ändra begäranden

I följande exempel används principuttryck och set-header principen för att lägga till användardata i inkommande begäranden. 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 är placerad.

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

Relaterat innehåll

Mer information om hur du arbetar med principer finns i: