Policies in Azure API Management (Richtlinien in Azure API Management)

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In Azure API Management können API-Herausgeber das API-Verhalten über eine Konfiguration mithilfe von Richtlinien ändern. Richtlinien sind eine Sammlung von Anweisungen, die bei Anfragen oder Antworten einer API nacheinander ausgeführt werden. Die API-Verwaltung bietet mehr als 50 Richtlinien an, die Sie konfigurieren können, um allgemeine API-Szenarien wie Authentifizierung, Ratenbeschränkung, Zwischenspeicherung und Transformation von Anforderungen oder Antworten zu behandeln. Eine vollständige Liste finden Sie unter Informationen zu API Management-Richtlinien.

Beliebte Richtlinien umfassen:

  • Formatumwandlung von XML in JSON
  • Beschränken der Aufrufrate zum Begrenzen der Anzahl eingehender Aufrufe von einem Entwickler
  • Filtern von Anforderungen von bestimmten IP-Adressen

Richtlinien werden im Gateway angewendet, das sich zwischen API-Consumer und der verwalteten API befindet. Während das Gateway Anforderungen empfängt und diese unverändert an die zugrunde liegende API weiterleitet, kann eine Richtlinie sowohl auf die eingehende Anforderung als auch auf die ausgehende Antwort Änderungen anwenden.

Grundlegendes zur Richtlinienkonfiguration

Richtliniendefinitionen sind einfache XML-Dokumente, die eine Abfolge von Anweisungen beschreiben, die auf Anforderungen und Antworten angewendet werden sollen. Das Portal bietet folgende Optionen, die Ihnen das Konfigurieren von Richtliniendefinitionen erleichtern:

  • Einen angeleiteten, formularbasierten Editor zum Vereinfachen der Konfiguration beliebter Richtlinien ohne Schreiben von XML-Code
  • Einen Code-Editor, in dem Sie XML-Codeschnipsel einfügen oder XML direkt bearbeiten können

Weitere Informationen zum Konfigurieren von Richtlinien finden Sie unter Festlegen oder Bearbeiten von Richtlinien.

Die XML-Konfiguration der Richtlinie ist in die Abschnitte inbound, backend, outbound und on-error unterteilt. Die Richtlinienanweisungen werden für eine Anforderung und eine Antwort nacheinander ausgeführt.

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

XML-Beispiele für Richtlinien finden Sie im Repository für API Management-Richtliniencodeausschnitte.

Fehlerbehandlung

Wenn es während der Verarbeitung einer Anforderung zu einem Fehler kommt, gilt Folgendes:

  • Alle verbleibenden Schritte in den Abschnitten inbound, backend oder outbound werden übersprungen.
  • Die Ausführung wechselt zu den Anweisungen im Abschnitt on-error.

Das Platzieren von Richtlinienanweisungen im Abschnitt on-error ermöglicht Ihnen Folgendes:

  • Sie können den Fehler mithilfe der Eigenschaft context.LastError überprüfen.
  • Sie können die Fehlerantwort mithilfe der Richtlinie set-body untersuchen und anpassen.
  • Sie können konfigurieren, was bei Auftreten eines Fehlers passiert.

Weitere Informationen finden Sie unter Error handling in API Management policies(in englischer Sprache).

Richtlinienausdrücke

Sofern in der Richtlinie nicht anders angegeben, können Richtlinienausdrücke als Attribut- oder Textwerte in allen API Management-Richtlinien verwendet werden. Bei einem Richtlinienausdruck ist entweder:

  • eine einzelne, in @(expression) eingeschlossene C#-Anweisung oder
  • ein in @{expression} eingeschlossener C#-Codeblock mit mehreren Anweisungen, der einen Wert zurückgibt

Jeder Ausdruck hat Zugriff auf die implizit bereitgestellte context-Variable und eine zulässige Teilmenge von .NET Framework-Typen.

Richtlinienausdrücke bieten eine fortgeschrittene Möglichkeit zum Steuern des Datenverkehrs und zum Ändern des API-Verhaltens, ohne dass Sie speziellen Code schreiben oder Back-End-Dienste ändern müssen. Einige Richtlinien, z. B. Ablaufsteuerung und Variable festlegen, basieren auf Richtlinienausdrücken.

Bereiche

Durch API Management können Sie Richtlinien für die folgenden, mit absteigender Größe aufgeführten Bereiche definieren:

  • Global (alle APIs)
  • Arbeitsbereich (alle APIs, die einem ausgewählten Arbeitsbereich zugeordnet sind)
  • Produkt (alle APIs, die einem ausgewählten Produkt zugeordnet sind)
  • API (alle Vorgänge in einer API)
  • Vorgang (einzelner Vorgang in einer API)

Beim Konfigurieren einer Richtlinie müssen Sie zunächst ihren Geltungsbereich auswählen.

Richtlinienbereiche

Wichtige Hinweise

  • Um verschiedene API-Nutzer detailliert zu kontrollieren, können Sie Richtliniendefinitionen für mehr als einen Bereich konfigurieren.

  • Nicht alle Richtlinien werden in jedem Bereich und Richtlinienabschnitt unterstützt

  • Beim Konfigurieren von Richtliniendefinitionen für mehrere Bereiche steuern Sie die Reihenfolge der Steuerungsrichtlinienvererbrung und Richtlinienauswertung in jedem Richtlinienabschnitt durch Platzieren des base-Elements

  • Richtlinien, die auf API-Anforderungen angewendet werden, sind auch vom Anforderungskontext betroffen, einschließlich des Vorhandenseins oder Fehlens eines in der Anforderung verwendeten Abonnementschlüssels, der API oder des Produktumfangs des Abonnementschlüssels und ob die API oder das Produkt ein Abonnement erfordert.

    Hinweis

    Wenn Sie ein API-bezogenes Abonnement, ein All-APIs-Abonnement oder das integrierte All-Access-Abonnement verwenden, werden Richtlinien, die im Produktbereich konfiguriert sind, nicht auf Anforderungen dieses Abonnements angewendet.

Weitere Informationen finden Sie unter:

Richtlinien für GraphQL-Resolver

In API Management wird ein GraphQL-Auflöser mithilfe von Richtlinien konfiguriert, die auf einen bestimmten Vorgangstyp und ein bestimmtes Feld in einem GraphQL-Schema festgelegt sind.

  • Derzeit unterstützt API Management GraphQL Resolver, die entweder HTTP API-, Cosmos DB- oder Azure SQL-Datenquellen angeben. Beispielsweise können Sie eine einzelne http-data-source-Richtlinie mit Elementen konfigurieren, um eine Anforderung an eine HTTP-Datenquelle (und optional eine Antwort von ihr) anzugeben.
  • Sie können keine Auflöserrichtlinie in Richtliniendefinitionen in anderen Bereichen wie API, Produkt oder allen APIs einschließen. Sie erbt auch keine Richtlinien, die in anderen Bereichen konfiguriert sind.
  • Das Gateway wertet eine Richtlinie mit Auflöserbereich nach allen konfigurierten inbound- und backend-Richtlinien in der Richtlinienausführungspipeline aus.

Weitere Informationen finden Sie unter Konfigurieren eines GraphQL-Resolvers.

Erhalten Sie Unterstützung beim Erstellen von Richtlinien mithilfe von Microsoft Copilot in Azure (Vorschau)

Microsoft Copilot in Azure (Vorschau) bietet Funktionen zur Erstellung von Richtlinien für Azure API Management. Mithilfe von Copilot in Azure im Kontext des Richtlinien-Editors von API Management können Richtlinien erstellt werden, die Ihren genauen Anforderungen entsprechen, ohne die Syntax zu kennen oder bereits konfigurierte Richtlinien erklärt zu bekommen.

Sie können Copilot in Azure auffordern, Richtliniendefinitionen zu generieren, dann die Ergebnisse in den Richtlinien-Editor kopieren und alle notwendigen Anpassungen vornehmen. Stellen Sie Fragen, um Einblicke in verschiedene Optionen zu erhalten, um Ihre bereitgestellte Richtlinie zu bearbeiten oder Ihre bereits vorhandene Richtlinie zu klären. Weitere Informationen

Beispiele

Anwenden von Richtlinien, die für verschiedene Bereiche angegeben sind

Wenn Sie eine Richtlinie auf der globalen Ebene und eine Richtlinie für eine API konfiguriert haben, dann können bei jeder Verwendung dieser API immer beide Richtlinien angewendet werden. API Management ermöglicht eine deterministische Festlegung der Reihenfolge kombinierter Richtlinienanweisungen über das base-Element.

Beispiel für eine Richtliniendefinition im API-Bereich:

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

Für die oben gezeigte Beispielrichtliniendefinition gilt Folgendes:

  • Die Anweisung cross-domain wird zuerst ausgeführt.
  • Die Richtlinie find-and-replace wird nach allen für übergeordnete Bereiche geltenden Richtlinien ausgeführt.

Hinweis

Wenn Sie das Element base im API-Bereich entfernen, werden nur Richtlinien angewendet, die für den API-Bereich konfiguriert sind. Es werden weder Produktrichtlinien noch Richtlinien auf globaler Ebene angewendet.

Verwenden von Richtlinienausdrücken zum Ändern von Anforderungen

Im folgenden Beispiel werden Richtlinienausdrücke und die Richtlinie set-header verwendet, um der eingehenden Anforderung Benutzerdaten hinzuzufügen. Der hinzugefügte Header enthält die dem Abonnementschlüssel in der Anforderung zugehörige Benutzer-ID und die Region des Gateways, das die Anforderung verarbeitet.

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: