Beleidsregels in Azure API Management

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

In Azure API Management kunnen API-uitgevers het API-gedrag wijzigen via configuratie met behulp van beleid. Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. API Management biedt meer dan 50 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:

  • Indelingsconversie van XML naar JSON
  • Aanroepfrequentie beperken om het aantal binnenkomende oproepen van een ontwikkelaar te beperken
  • Aanvragen filteren die afkomstig zijn van bepaalde IP-adressen

Beleidsregels worden toegepast in de gateway tussen de API-consument en de beheerde API. Terwijl de gateway aanvragen ontvangt en deze ongewijzigd 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.

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

Zie de opslagplaats api Management-beleidsfragmenten voor voorbeelden van BELEIDS-XML.

Foutafhandeling

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

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

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

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

Beleidsexpressies

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

  • één C#-instructie ingesloten in @(expression), of
  • 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.

Bereiken

Met API Management kunt u beleidsregels definiëren op de volgende bereiken, van de meest brede tot de meest smalle:

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

Beleidsbereiken

Goed om te 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 de plaatsing van het base element

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

    Notitie

    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.

Zie voor meer informatie:

GraphQL resolver-beleid

In API Management wordt een GraphQL-resolver geconfigureerd met behulp van beleid dat is gericht op een specifiek bewerkingstype en veld in een GraphQL-schema.

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

Zie Een GraphQL-resolver configureren voor meer informatie.

Hulp krijgen bij het maken van beleid met Behulp van Microsoft Copilot voor Azure (preview)

Microsoft Copilot voor Azure (preview) biedt mogelijkheden voor het ontwerpen van beleid voor Azure API Management. Gebruik Copilot voor Azure in de context van de beleidseditor van API Management om beleidsregels te maken die voldoen aan uw specifieke vereisten zonder dat u de syntaxis kent of al beleidsregels hebt geconfigureerd die aan u zijn uitgelegd.

U kunt Copilot vragen om beleidsdefinities te genereren en vervolgens de resultaten naar de beleidseditor te kopiëren en de benodigde aanpassingen aan te brengen. Stel vragen om inzicht te krijgen in verschillende opties, het geleverde beleid te wijzigen of het beleid te verduidelijken dat u al hebt. Meer informatie

Belangrijk

Microsoft Copilot voor Azure (preview) vereist registratie en is momenteel alleen beschikbaar voor goedgekeurde zakelijke klanten en partners. Zie Beperkte toegang tot Microsoft Copilot voor Azure (preview) voor meer informatie.

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 bovenstaande voorbeeldbeleidsdefinitie:

  • De cross-domain instructie wordt eerst uitgevoerd.
  • Het find-and-replace beleid wordt uitgevoerd na beleidsregels binnen een breder bereik.

Notitie

Als u het base element in het API-bereik verwijdert, worden alleen beleidsregels toegepast die zijn geconfigureerd in het API-bereik. Geen van beide beleidsregels voor product- of globaal bereik wordt 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 de binnenkomende aanvraag. 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>

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: