Wiederverwenden von Richtlinienkonfigurationen in Ihren API Management-Richtliniendefinitionen

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel erfahren Sie, wie Sie Richtlinienfragmente in Ihren API Management-Richtliniendefinitionen erstellen und verwenden. Richtlinienfragmente sind zentral verwaltete, wiederverwendbare XML-Codeausschnitte, die mindestens eine API Management-Richtlinienkonfiguration enthalten. (Weitere Informationen finden Sie unter Richtlinien in Azure API Management.)

Richtlinienfragmente helfen Ihnen, Richtlinien konsistent zu konfigurieren und Richtliniendefinitionen zu verwalten, ohne XML-Code wiederholen oder neu eingeben zu müssen.

Für ein Richtlinienfragment gilt Folgendes:

  • Es muss sich um gültigen XML-Code mit mindestens einer Richtlinienkonfiguration handeln.
  • Es kann Richtlinienausdrücke enthalten, wenn diese von einer referenzierten Richtlinie unterstützt werden.
  • Es wird unter Verwendung der Richtlinie include-fragment ohne Anpassungen in eine Richtliniendefinition eingefügt.

Einschränkungen:

  • Ein Richtlinienfragment darf weder einen Richtlinienabschnittsbezeichner (<inbound>, <outbound> usw.) noch das Element <base/> enthalten.
  • Derzeit ist keine Schachtelung von Richtlinienfragmenten möglich.
  • Die maximale Größe eines Richtlinienfragments beträgt 32 KB.

Voraussetzungen

Wenn Sie noch keine API Management-Instanz und Back-End-API haben, lesen Sie:

Es empfiehlt sich gegebenenfalls, eine oder mehrere Richtliniendefinitionen zu konfigurieren. Dies ist jedoch nicht erforderlich. Sie können Richtlinienelemente aus diesen Definitionen kopieren, wenn Sie Richtlinienfragmente erstellen.

Navigieren zur API Management-Instanz

  1. Suchen Sie im Azure-Portal nach API Management-Dienste, und wählen Sie diese Option aus.

    Auswählen von API Management-Dienste

  2. Wählen Sie auf der Seite API Management-Dienste Ihre API Management-Instanz aus.

    Auswählen Ihrer API Management-Instanz

Erstellen eines Richtlinienfragments

  1. Wählen Sie im linken Navigationsbereich Ihrer API Management-Instanz unter APIs die Optionen Richtlinienfragmente>+ Erstellen aus.

  2. Geben Sie im Fenster Neues Richtlinienfragment erstellen unter Name einen Namen und unter Beschreibung eine optionale Beschreibung für das Richtlinienfragment ein. Der Name muss innerhalb Ihrer API Management-Instanz eindeutig sein.

    Beispielname: ForwardContext

  3. Geben oder fügen Sie im Editor XML-Richtlinienfragment mindestens ein XML-Richtlinienelement zwischen den Tags <fragment> und </fragment> ein.

    Screenshot: Formular zum Erstellen eines neuen Richtlinienfragments

    Das folgende Fragment enthält beispielsweise eine Richtlinienkonfiguration vom Typ set-header, um Kontextinformationen an einen Back-End-Dienst weiterzuleiten. Dieses Fragment würde sich in einem Abschnitt mit Richtlinien für eingehenden Datenverkehr befinden. Die Richtlinienausdrücke in diesem Beispiel greifen auf die integrierte Variable context zu.

    <fragment>
    <set-header name="x-request-context-data" exists-action="override">
      <value>@(context.User.Id)</value>
      <value>@(context.Deployment.Region)</value>
    </set-header>
</fragment>

  4. Klicken Sie auf Erstellen. Das Fragment wird der Liste der Richtlinienfragmente hinzugefügt.

Einschließen eines Fragments in eine Richtliniendefinition

Konfigurieren Sie die Richtlinie include-fragment, um ein Richtlinienfragment in eine Richtliniendefinition einzufügen. Weitere Informationen zu Richtliniendefinitionen finden Sie unter Festlegen oder Bearbeiten von Azure API Management-Richtlinien.

  • Sie können ein Fragment in einen beliebigen Bereich und in einen beliebigen Richtlinienabschnitt einschließen, solange die zugrunde liegende Richtlinie bzw. die zugrunde liegenden Richtlinien im Fragment diese Verwendung unterstützen.
  • In eine Richtliniendefinition können mehrere Richtlinienfragmente eingeschlossen werden.

Fügen Sie beispielsweise das Richtlinienfragment namens ForwardContext in den Abschnitt mit Richtlinien für eingehenden Datenverkehr ein:

<policies>
    <inbound>
        <include-fragment fragment-id="ForwardContext" />
        <base />
    </inbound>
[...]

Tipp

Wählen Sie im Richtlinieneditor die Option Effektive Richtlinie berechnen aus, um den Inhalt eines eingeschlossenen Fragments in der Richtliniendefinition anzuzeigen.

Verwalten von Richtlinienfragmenten

Nachdem Sie ein Richtlinienfragment erstellt haben, können Sie Richtlinieneigenschaften anzeigen und aktualisieren oder die Richtlinie jederzeit löschen.

So zeigen Sie Eigenschaften eines Richtlinienfragments an:

  1. Wählen Sie im linken Navigationsbereich Ihrer API Management-Instanz unter APIs die Option Richtlinienfragmente aus. Wählen Sie den Namen Ihres Fragments aus.
  2. Überprüfen Sie auf der Seite Übersicht die Richtliniendokumentverweise, um die Richtliniendefinitionen anzuzeigen, die das Fragment enthalten.
  3. Überprüfen Sie auf der Seite Eigenschaften den Namen und die Beschreibung des Richtlinienfragments. Der Name kann nicht geändert werden.

So bearbeiten Sie ein Richtlinienfragment

  1. Wählen Sie im linken Navigationsbereich Ihrer API Management-Instanz unter APIs die Option Richtlinienfragmente aus. Wählen Sie den Namen Ihres Fragments aus.
  2. Wählen Sie Richtlinieneditor aus.
  3. Aktualisieren Sie die Anweisungen im Fragment, und wählen Sie anschließend Anwenden aus.

Hinweis

Die Aktualisierung wirkt sich auf alle Richtliniendefinitionen aus, in denen das Fragment enthalten ist.

So löschen Sie ein Richtlinienfragment

  1. Wählen Sie im linken Navigationsbereich Ihrer API Management-Instanz unter APIs die Option Richtlinienfragmente aus. Wählen Sie den Namen Ihres Fragments aus.
  2. Überprüfen Sie Richtliniendokumentverweise auf Richtliniendefinitionen, die das Fragment enthalten. Bevor ein Fragment gelöscht werden kann, müssen die Fragmentverweise aus allen Richtliniendefinitionen entfernt werden.
  3. Wählen Sie nach dem Entfernen aller Verweise Löschen aus.

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: