Principer i Azure API Management

  • Artikel

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

I Azure API Management kan API-utgivare ändra API-beteendet via konfiguration med hjälp av principer. Principer är en samling instruktioner som körs sekventiellt på begäran av eller efter ett svar från ett API. API Management tillhandahåller mer än 50 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 principreferens.

Populära principer är:

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

Principer tillämpas i gatewayen mellan API-konsumenten och det hanterade API:et. Gatewayen tar emot begäranden och vidarebefordrar dem, oförändrade, till det underliggande API:et, men en princip kan 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.

Princip-XML-konfigurationen är indelad i inboundavsnitten , backend, outboundoch on-error . Den här 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>

Exempel på princip-XML finns i API Management-principfragment på lagringsplatsen.

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 hoppar till -instruktionerna i avsnittet on-error .

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

  • Granska felet med hjälp av context.LastError egenskapen .
  • Granska och anpassa felsvaret med hjälp av set-body principen.
  • 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 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. Vissa principer baseras på principuttryck, till exempel Kontrollflöde och Ange variabel.

Omfattningar

Med API Management kan du definiera principer i följande omfång, från mest breda till mest smala:

  • 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 (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.

Principomfattningar

Bra att känna till

  • För detaljerad kontroll för olika API-konsumenter kan du konfigurera principdefinitioner i 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.

    Kommentar

    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, 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 som API, produkt eller alla API:er. Den ärver inte heller principer som konfigurerats i andra omfång.
  • Gatewayen utvärderar en princip med matchningsomfång 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 att skapa principer med Hjälp av Microsoft Copilot för Azure (förhandsversion)

Microsoft Copilot för Azure (förhandsversion) tillhandahåller principredigeringsfunktioner för Azure API Management. Använd Copilot för Azure i kontexten för API Managements principredigerare för att skapa principer som matchar dina specifika krav utan att känna till syntaxen eller som redan har konfigurerat principer som förklaras för dig.

Du kan uppmana Copilot för Azure att generera principdefinitioner och sedan kopiera resultaten till principredigeraren och göra nödvändiga justeringar. Ställ frågor för att få insikter om olika alternativ, ändra den angivna principen eller klargöra vilken princip du redan har. Läs mer

Viktigt!

Microsoft Copilot för Azure (förhandsversion) kräver registrering och är för närvarande endast tillgängligt för godkända företagskunder och partner. Mer information finns i Begränsad åtkomst till Microsoft Copilot för Azure (förhandsversion).

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 exempelprincipdefinitionen ovan:

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

Kommentar

Om du tar bort elementet base i API-omfånget tillämpas endast principer som konfigurerats i API-omfånget. Varken produktprinciper eller globala omfångsprinciper skulle tillämpas.

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

Relaterat innehåll

Mer information om hur du arbetar med principer finns i: