Freigeben über

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

GILT FÜR: Alle API Management-Ebenen

In Azure API Management können API-Herausgeber das API-Verhalten mithilfe von Richtlinien ändern. In diesem Artikel wird beschrieben, wie Richtlinien verwendet werden.

Richtlinien sind eine Sammlung von Anweisungen, die bei Anfragen oder Antworten einer API nacheinander ausgeführt werden. Die API-Verwaltung bietet mehr als 75 Richtlinien sofort, die Sie konfigurieren können, um allgemeine API-Szenarien wie Authentifizierung, Ratelimitierung, Zwischenspeicherung und Transformation von Anforderungen oder Antworten zu behandeln. Eine vollständige Liste finden Sie unter Informationen zu API Management-Richtlinien.

Beliebte Richtlinien umfassen:

  • Formatkonvertierung von XML in JSON.
  • Anrufratenbeschränkung, um die Anzahl eingehender Anrufe von einem Entwickler einzuschränken.
  • Filtern von Anforderungen, die aus bestimmten IP-Adressen stammen.

Richtlinien werden im Gateway angewendet, das sich zwischen API-Consumer und der verwalteten API befindet. Obwohl das Gateway Anforderungen empfängt und sie unverändert an die zugrunde liegende API weiterleitet, kann eine Richtlinie Änderungen sowohl auf die eingehende Anforderung als auch auf die ausgehende Antwort 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 in der angegebenen Reihenfolge für eine Anforderung und eine Antwort ausgeführt. So sieht es aus:

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

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:

  • Überprüfen Sie den Fehler mithilfe der context.LastError Eigenschaft.
  • 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. Ein Richtlinienausdruck ist wie folgt:

  • Eine einzelne C#-Anweisung, die in @(expression) eingeschlossen ist
  • Ein mehrzeiliger C#-Codeblock, der in @{expression} eingeschlossen ist und 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

Mit der API-Verwaltung können Sie Richtlinien in den folgenden Bereichen definieren, die hier von der breitesten bis zur schmalsten dargestellt werden:

  • 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 (ein einzelner Vorgang in einer API)

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

Diagramm, das die fünf Richtlinienbereiche veranschaulicht.

Wichtige Hinweise

  • Zur fein abgestimmten Kontrolle für verschiedene API-Verbraucher können Sie Richtliniendefinitionen auf mehr als einen Bereich konfigurieren.

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

  • Beim Konfigurieren von Richtliniendefinitionen auf mehr als einem Bereich steuern Sie die Richtlinienvererbung und die Richtlinienauswertungsreihenfolge in jedem Richtlinienabschnitt, indem Sie das base Element platzieren.

  • 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 der API-Verwaltung wird ein GraphQL-Resolver mit Richtlinien konfiguriert, die auf einen bestimmten Vorgangstyp und ein Feld in einem GraphQL-Schema ausgelegt sind.

  • Derzeit unterstützt API-Verwaltung GraphQL-Resolver, die entweder HTTP-API, Azure Cosmos DB oder Azure SQL-Datenquellen angeben. Sie können z. B. eine einzelne http-data-source Richtlinie mit Elementen konfigurieren, um eine Anforderung an eine HTTP-Datenquelle anzugeben (und optional darauf zu antworten).
  • Sie können keine Resolverrichtlinie in Richtliniendefinitionen in anderen Bereichen einschließen, z. B. API, Produkt oder alle APIs. Die Richtlinie 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 Pipeline zur Richtlinienausführung aus.

Weitere Informationen finden Sie unter Konfigurieren eines GraphQL-Resolvers.

Copilot-Unterstützung erhalten

Sie können KI-Unterstützung von Copilot erhalten, um Ihre API-Verwaltungsrichtliniendefinitionen zu erstellen und zu bearbeiten. Sie können Copilot verwenden, um Richtlinien zu erstellen und zu aktualisieren, die Ihren spezifischen Anforderungen entsprechen, ohne die XML-Syntax kennen zu müssen. Sie können auch Erläuterungen zu vorhandenen Richtlinien erhalten. Und Copilot kann Ihnen dabei helfen, Richtlinien zu übersetzen, die Sie möglicherweise in anderen API-Verwaltungslösungen konfiguriert haben.

  • Microsoft Copilot in Azure bietet Unterstützung bei der Richtlinienerstellung mit Anweisungen in natürlicher Sprache im Azure-Portal. Sie können Richtlinien im API-Verwaltungsrichtlinien-Editor erstellen und Copilot bitten, Richtlinienabschnitte zu erläutern.
  • GitHub Copilot für Azure in Visual Studio Code bietet Unterstützung bei der Richtlinienerstellung in Visual Studio Code, und Sie können die Azure API-Verwaltungserweiterung für Visual Studio Code verwenden, um die Richtlinienkonfiguration zu beschleunigen. Sie können Copilot Chat oder Copilot Edits mithilfe natürlicher Sprache verwenden, um Richtliniendefinitionen an Ort und Stelle zu erstellen und zu verfeinern.

Beispielaufforderung:

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

Copilot wird von KI unterstützt, so dass Überraschungen und Fehler möglich sind. Weitere Informationen finden Sie in den häufig gestellten Fragen zur allgemeinen Verwendung von Copilot.

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>

In der vorherigen Beispielrichtliniendefinition:

  • Die cross-domain-Anweisung wird zuerst ausgeführt.
  • Die find-and-replace-Richtlinie wird nach allen Richtlinien in einem umfangreicheren Geltungsbereich ausgeführt.

Hinweis

Wenn Sie das Element base im API-Bereich entfernen, werden nur Richtlinien angewendet, die für den API-Bereich konfiguriert sind. Richtlinien, die für ein Produkt oder umfassendere Geltungsbereiche konfiguriert sind, werden nicht angewendet.

Verwenden von Richtlinienausdrücken zum Ändern von Anforderungen

Im folgenden Beispiel werden Richtlinienausdrücke und die set-header Richtlinie zum Hinzufügen von Benutzerdaten zu eingehenden Anforderungen verwendet. Der hinzugefügte Header enthält die Benutzer-ID, die dem Abonnementschlüssel in der Anforderung zugeordnet ist, und die Region, in der das Gateway, das die Anforderung verarbeitet, gehostet wird.

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