Delen via

Beleid in Azure API Management

Van toepassing op: Alle API Management-lagen

In Azure API Management kunnen API-uitgevers het API-gedrag wijzigen via configuratie met behulp van beleid. In dit artikel wordt beschreven hoe u beleidsregels gebruikt.

Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. API Management biedt meer dan 75 beleidsregels die u kunt configureren om algemene API-scenario's aan te pakken, zoals verificatie, frequentiebeperking, caching en transformatie van aanvragen of antwoorden. Raadpleeg de API Management-beleidsreferentie voor een volledige lijst.

Populaire beleidsregels zijn onder andere:

  • Conversie van XML naar JSON.
  • Oproepsnelheidsbeperking om het aantal binnenkomende oproepen van een ontwikkelaar te beperken.
  • Filteren van aanvragen die afkomstig zijn van bepaalde IP-adressen.

Beleidsregels worden toegepast in de gateway tussen de API-consument en de beheerde API. Hoewel de gateway aanvragen ontvangt en doorstuurt naar de onderliggende API, kan een beleid wijzigingen toepassen op zowel de binnenkomende aanvraag als het uitgaande antwoord.

Informatie over beleidsconfiguratie

Beleidsdefinities zijn eenvoudige XML-documenten die een reeks instructies beschrijven die van toepassing zijn op aanvragen en antwoorden. De portal biedt de volgende opties om u te helpen bij het configureren van beleidsdefinities:

  • Een begeleide editor op basis van formulieren om het configureren van populair beleid te vereenvoudigen zonder XML te coderen
  • Een code-editor waarin u XML-fragmenten kunt invoegen of XML rechtstreeks kunt bewerken

Zie Beleid instellen of bewerken voor meer informatie over het configureren van beleid.

De XML-configuratie van het beleid is onderverdeeld in inbound, backenden outboundon-error secties. Deze reeks opgegeven beleidsinstructies wordt uitgevoerd op volgorde van een aanvraag en een antwoord. Dit ziet er als volgt uit:

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

Voor voorbeelden van beleids-XML's, zie de API Management beleidsfragmentenrepository.

Foutafhandeling

Als er een fout optreedt tijdens de verwerking van een aanvraag:

  • Alle resterende stappen in de inbound, backendof outbound secties worden overgeslagen.
  • De executie springt naar de instructies in de on-error sectie.

Door beleidsinstructies in de on-error sectie te plaatsen, kunt u het volgende doen:

  • Controleer de fout met behulp van de context.LastError eigenschap.
  • Inspecteer en pas de foutreactie aan met behulp van het set-body beleid.
  • Configureer wat er gebeurt als er een fout optreedt.

Zie Foutafhandeling in API Management-beleid voor meer informatie.

Beleidsuitdrukkingen

Tenzij het beleid anders opgeeft, kunnen beleidsexpressies worden gebruikt als kenmerkwaarden of tekstwaarden in een van de API Management-beleidsregels. Een beleidsexpressie is een van de volgende:

  • Eén C#-instructie ingesloten in @(expression)
  • Een C#-codeblok met meerdere instructies, ingesloten in @{expression}, dat een waarde retourneert

Elke expressie heeft toegang tot de impliciet opgegeven context variabele en een toegestane subset van .NET Framework-typen.

Beleidsexpressies bieden een geavanceerde methode voor het beheren van verkeer en het wijzigen van API-gedrag zonder dat u gespecialiseerde code hoeft te schrijven of back-endservices hoeft te wijzigen. Sommige beleidsregels zijn gebaseerd op beleidsexpressies, zoals controlestroom en variabele instellen.

Toepassingsgebieden

Met API Management kunt u beleidsregels definiëren op de volgende bereiken, die hier worden gepresenteerd van breed naar smalst:

  • Globaal (alle API's)
  • Werkruimte (alle API's die zijn gekoppeld aan een geselecteerde werkruimte)
  • Product (alle API's die zijn gekoppeld aan een geselecteerd product)
  • API (alle bewerkingen in een API)
  • Bewerking (één bewerking in een API)

Wanneer u een beleid configureert, moet u eerst het bereik selecteren waarop het beleid van toepassing is.

Diagram dat de vijf beleidsbereiken illustreert.

Dingen die u moet weten

  • Voor fijnmazige controle voor verschillende API-consumenten kunt u beleidsdefinities configureren op meer dan één bereik.

  • Niet alle beleidsregels worden ondersteund voor elk bereik en elke beleidssectie.

  • Wanneer u beleidsdefinities configureert in meer dan één bereik, beheert u de overname van beleid en de volgorde van beleidsevaluatie in elke beleidssectie door het base element te plaatsen.

  • Beleidsregels die worden toegepast op API-aanvragen, worden ook beïnvloed door de aanvraagcontext, waaronder de aanwezigheid of afwezigheid van een abonnementssleutel die wordt gebruikt in de aanvraag, de API of het productbereik van de abonnementssleutel en of de API of het product een abonnement vereist.

    Opmerking

    Als u een abonnement met API-bereik, een abonnement met alle API's of het ingebouwde abonnement voor alle toegang gebruikt, worden beleidsregels die zijn geconfigureerd op het productbereik, niet toegepast op aanvragen van dat abonnement.

Voor meer informatie, zie:

GraphQL resolver-beleid

In API Management wordt een GraphQL-resolver geconfigureerd met beleidsregels die zijn gericht op een specifiek bewerkingstype en -veld in een GraphQL-schema.

  • Momenteel ondersteunt API Management GraphQL-resolvers die HTTP-API, Azure Cosmos DB of Azure SQL-gegevensbronnen opgeven. U kunt bijvoorbeeld één http-data-source beleid configureren met elementen om een aanvraag voor een HTTP-gegevensbron op te geven (en optioneel te reageren vanuit).
  • U kunt geen resolverbeleid opnemen in beleidsdefinities binnen andere bereiken, zoals een enkele API, een product of alle API's. Het beleid neemt ook geen beleidsregels over die zijn geconfigureerd voor andere scopes.
  • De gateway evalueert een resolver-specifiek beleid na eventuele geconfigureerde inbound- en backend-beleid in de pijplijn voor beleidsuitvoering.

Zie Een GraphQL-resolver configureren voor meer informatie.

Hulp krijgen bij Copilot

U kunt AI-hulp krijgen van Copilot om uw API Management-beleidsdefinities te maken en te bewerken. U kunt Copilot gebruiken om beleidsregels te maken en bij te werken die voldoen aan uw specifieke vereisten zonder dat u de XML-syntaxis hoeft te kennen. U kunt ook uitleg krijgen over bestaande beleidsregels. Copilot kan u helpen bij het vertalen van beleidsregels die u mogelijk hebt geconfigureerd in andere API Management-oplossingen.

Voorbeeldprompt:

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

Copilot wordt mogelijk gemaakt door AI, dus verrassingen en fouten zijn mogelijk. Zie voor meer informatie de veelgestelde vragen over algemeen gebruik van Copilot.

Voorbeelden

Beleidsregels toepassen die zijn opgegeven in verschillende bereiken

Als u een beleid hebt op globaal niveau en een beleid dat is geconfigureerd voor een API, kunnen beide beleidsregels worden toegepast wanneer die specifieke API wordt gebruikt. API Management maakt het mogelijk om deterministische volgorde van gecombineerde beleidsinstructies via het base element te ordenen.

Voorbeeld van beleidsdefinitie bij API-bereik:

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

In de voorgaande voorbeeldbeleidsdefinitie:

  • De cross-domain instructie wordt eerst uitgevoerd.
  • Het find-and-replace beleid wordt uitgevoerd na beleidsregels met een bredere reikwijdte.

Opmerking

Als u het base element in het API-bereik verwijdert, worden alleen beleidsregels toegepast die zijn geconfigureerd in het API-bereik. Beleidsregels die zijn geconfigureerd op het product en bredere omvang, worden niet toegepast.

Beleidsexpressies gebruiken om aanvragen te wijzigen

In het volgende voorbeeld worden beleidsexpressies en het set-header beleid gebruikt om gebruikersgegevens toe te voegen aan binnenkomende aanvragen. De toegevoegde header bevat de gebruikers-id die is gekoppeld aan de abonnementssleutel in de aanvraag en de regio waar de gateway die de aanvraag verwerkt, wordt gehost.

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

Verwante inhoud

Zie voor meer informatie over het werken met beleid: