Beleidsregels in Azure API Management

In Azure API Management kunnen API-uitgevers het api-gedrag wijzigen via configuratie met behulp van beleidsregels. Beleidsregels zijn een verzameling instructies die opeenvolgend worden uitgevoerd op de aanvraag of het antwoord van een API. Populaire instructies zijn onder andere:

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

Veel meer beleidsregels zijn standaard beschikbaar. Zie API Management beleidsreferentie voor een volledige lijst.

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 moeten worden toegepast op aanvragen en antwoorden. De portal biedt de volgende opties om u te helpen bij het configureren van beleidsdefinities:

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

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

De XML-configuratie van het beleid is onderverdeeld in inboundsecties , backend, outbounden on-error . 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 API Management opslagplaats voor beleidsfragmenten voor xml-voorbeelden van beleid.

Foutafhandeling

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

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

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

• Controleer de fout met behulp van de context.LastError eigenschap.
• Controleer 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:

• een enkele C#-instructie tussen @(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 om verkeer te beheren en API-gedrag te wijzigen zonder dat u gespecialiseerde code hoeft te schrijven of back-endservices hoeft te wijzigen. Sommige beleidsregels zijn gebaseerd op beleidsexpressies, zoals de besturingsstroom en de variabele Set. Zie Geavanceerd beleid voor meer informatie.

Bereiken

met API Management kunt u beleidsregels definiëren in 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.

Dingen die u moet weten

• Voor fijnmazig beheer voor verschillende API-consumenten kunt u beleidsdefinities configureren voor meer dan één bereik
• Niet alle beleidsregels kunnen worden toegepast op elk bereik en elke beleidssectie
• Wanneer u beleidsdefinities configureert voor meer dan één bereik, bepaalt u de volgorde van de beleidsevaluatie in elke beleidssectie door het base element te plaatsen

Zie Beleid instellen of bewerken voor meer informatie.

GraphQL resolver-beleid

In API Management wordt een GraphQL-resolver geconfigureerd met behulp van beleidsregels die zijn 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 een antwoord van) een HTTP-gegevensbron.
• U kunt geen resolverbeleid opnemen in beleidsdefinities voor andere bereiken, zoals API, product of alle API's. Het neemt ook geen beleidsregels over die zijn geconfigureerd in andere bereiken.
• De gateway evalueert een beleid binnen het bereik van de resolver na alle geconfigureerde inbound beleidsregels en backend beleidsregels in de pijplijn voor beleidsuitvoering.

Zie Een GraphQL-resolver configureren 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 de deterministische volgorde van gecombineerde beleidsinstructies via het base -element mogelijk.

Voorbeeld van een beleidsdefinitie op 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 met een breder bereik.

Notitie

Als u het element in het base API-bereik verwijdert, worden alleen beleidsregels toegepast die zijn geconfigureerd op het API-bereik. Het beleid voor het product of het globale bereik zou niet worden 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> 

Volgende stappen

Zie voor meer informatie over het werken met beleid:

• Zelfstudie: Uw API transformeren en beveiligen
• Beleidsreferentie voor een volledige lijst met beleidsinstructies en hun instellingen
• Beleidsexpressies
• Beleid instellen of bewerken
• Beleidsconfiguraties opnieuw gebruiken
• Opslagplaats voor beleidsfragmenten