Verwenden von benannten Werten in Azure API Management-Richtlinien

GILT FÜR: Alle API Management-Ebenen

API Management-Richtlinien sind eine leistungsfähige Funktion des Systems, mit der Herausgeber das Verhalten der API über eine Konfiguration ändern können. Richtlinien sind eine Sammlung von Anweisungen, die sequenziell bei Anfragen oder Antworten einer API ausgeführt werden. Richtlinienanweisungen können mithilfe von literalen Textwerten, Richtlinienausdrücken und benannten Werten erstellt werden.

Benannte Werte sind eine globale Sammlung von Name-Wert-Paaren in jeder API Management-Instanz. Sie können benannte Werte verwenden, um konstanten Zeichenfolgenwerte und geheime Schlüssel in allen API-Konfigurationen und Richtlinien zu verwalten.

Werttypen

type	BESCHREIBUNG
Plain	Literalzeichenfolge oder Richtlinienausdruck
`Secret`	Literale Zeichenfolge oder Richtlinienausdruck, der durch API-Verwaltung verschlüsselt wird
Schlüsseltresor	Bezeichner eines Geheimnisses, das in Azure Key Vault gespeichert ist.

Plain-Werte oder -Geheimnisse können Richtlinienausdrücke enthalten. Der Ausdruck @(DateTime.Now.ToString()) gibt z. B. eine Zeichenfolge zurück, die das aktuelle Datum und die Uhrzeit enthält.

Ausführliche Informationen zu den Attributen benannter Werte finden Sie in der REST-API-Referenz von API Management.

Key Vault-Geheimnisse

Geheimniswerte können entweder als verschlüsselte Zeichenfolgen in API Management (benutzerdefinierte Geheimnisse) oder durch Verweisen auf Geheimnisse in Azure Key Vault gespeichert werden.

Wir empfehlen die Verwendung von Key Vault-Geheimnissen, da sie die Sicherheit der API-Verwaltung verbessern.

Hinweis

Derzeit ist die Integration mit dem Schlüsseltresor für dieses Szenario in Arbeitsbereichen nicht verfügbar.

• Sie können geheime Schlüssel wiederverwenden, die in Schlüsseltresorn in allen Diensten gespeichert sind.
• Sie können präzise Zugriffsrichtlinien auf geheime Schlüssel anwenden.
• Wenn Geheimnisse im Schlüsseltresor aktualisiert werden, erfolgt in API Management automatisch eine Schlüsselrotation. Nach der Aktualisierung im Schlüsseltresor wird ein benannter Wert innerhalb von vier Stunden in API Management aktualisiert. Sie können das Geheimnis auch manuell im Azure-Portal oder über die Verwaltungs-REST-API aktualisieren.

Hinweis

Die geheimen Schlüssel, die in Azure Key Vault gespeichert sind, müssen zwischen 1 und 4096 Zeichen liegen, da die API-Verwaltung keine Werte abrufen kann, die diesen Grenzwert überschreiten.

Voraussetzungen

• Wenn Sie noch keine API-Verwaltungsdienstinstanz erstellt haben, lesen Sie die Schnellstartanleitung: Erstellen einer neuen Azure API Management-Instanz mithilfe des Azure-Portals.

Voraussetzungen für die Key Vault-Integration

Hinweis

Dieses Feature ist derzeit in Arbeitsbereichen nicht verfügbar.

• Wenn Sie noch nicht über einen Schlüsseltresor verfügen, erstellen Sie einen. Schritte zum Erstellen eines Schlüsseltresors finden Sie unter Schnellstart: Erstellen eines Schlüsseltresors über das Azure-Portal.

  Informationen zum Erstellen oder Importieren eines Geheimnisses in den Schlüsseltresor finden Sie unter Schnellstart: Festlegen und Abrufen eines Geheimnisses aus Azure Key Vault über das Azure-Portal.

• Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität in der API Management-Instanz.

Konfigurieren des Zugriffs auf den Schlüsseltresor

1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.
2. Wählen Sie im linken Menü die Konfiguration "Einstellungen>" aus. Beachten Sie das konfigurierte Berechtigungsmodell .
3. Konfigurieren Sie je nach Berechtigungsmodell entweder eine Schlüsseltresor-Zugriffsrichtlinie oder den Azure RBAC-Zugriff für eine verwaltete API Management-Identität.

Um eine Zugriffsrichtlinie für den Key Vault hinzuzufügen:

1. Wählen Sie im Menü auf der linken Seite Zugriffsrichtlinien aus.
2. Wählen Sie auf der Seite Zugriffsrichtlinien die Option + Erstellen aus.
3. Wählen Sie auf der Registerkarte "Berechtigungen " unter "Geheime Berechtigungen" die Option " Abrufen und Liste" und dann " Weiter" aus.
4. Suchen Sie auf der Registerkarte "Prinzipal " nach dem Ressourcennamen Ihrer verwalteten Identität, und wählen Sie dann "Weiter" aus. Wenn Sie eine systemseitig zugewiesene Identität verwenden, ist der Prinzipal der Name der API Management-Instanz.
5. Wählen Sie erneut Weiter aus. Wählen Sie auf der Registerkarte Überprüfen + erstellen die Option Erstellen aus.

So konfigurieren Sie Azure RBAC-Zugriff:

1. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus.
2. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Option Rollenzuweisung hinzufügen aus.
3. Wählen Sie die Registerkarte Rolle und dann die Option Key Vault-Geheimnisbenutzer, dann wählen Sie Weiter aus.
4. Wählen Sie auf der Registerkarte Mitglieder die Option Verwaltete Identität>+ Mitglieder auswählen aus.
5. Wählen Sie auf der Seite Verwaltete Identität auswählen die systemseitig zugewiesene verwaltete Identität oder eine benutzerseitig zugewiesene verwaltete Identität aus, die Ihrer API Management-Instanz zugeordnet ist, und wählen Sie dann Auswählen aus.
6. Wählen Sie Überprüfen und zuweisen aus.

Anforderungen an Key Vault-Firewall

Wenn die Key Vault-Firewall auf Ihrem Schlüsseltresor aktiviert ist, müssen Sie die folgenden Anforderungen erfüllen:

• Sie müssen die vom System zugewiesene verwaltete Identität der API-Verwaltungsinstanz verwenden, um auf den Schlüsseltresor zuzugreifen.

• Stellen Sie sicher, dass Ihre API-Verwaltungsinstanz über eine Netzwerklinie für den Schlüsseltresor verfügt. Konfigurieren Sie abhängig von Ihren Szenarien eine der folgenden Netzwerkzugriffsoptionen im Schlüsseltresor:

  • Zulassen des öffentlichen Zugriffs von allen Netzwerken.

  • Legen Sie eine Netzwerksicherheitsregel fest, um API-Management-Datenverkehr basierend auf der IP-Adresse oder virtueller Netzwerkkonnektivität zuzulassen.

  • Sichern des Datenverkehrs aus der API-Verwaltung mit Private Link-Konnektivität.

  • Verwenden Sie einen Netzwerksicherheitsperimeter, um Ihr Schlüsselvault zu sichern und Datenverkehr aus dem API-Management zuzulassen.

• Stellen Sie sicher, dass Ihre lokale Client-IP-Adresse vorübergehend auf den Schlüsseltresor zugreifen darf, während Sie ein Zertifikat oder Geheimnis auswählen, das Sie der Azure API Management-Instanz hinzufügen möchten. Weitere Informationen finden Sie unter Konfigurieren von Azure Key Vault-Netzwerkeinstellungen.

  Nach Abschluss der Konfiguration können Sie Ihre Clientadresse in der Firewall des Schlüsseltresors blockieren.

Wichtig

Ab März 2026 wird die vertrauenswürdige Dienstkonnektivität zu Azure Key Vault in der API-Verwaltung nicht mehr unterstützt, indem die Firewalleinstellung "Vertrauenswürdige Microsoft-Dienste zulassen" aktiviert wird, um die Firewall des Schlüsseltresors zu umgehen. Um key Vault nach dieser Änderung weiterhin mit der API-Verwaltung zu verwenden, stellen Sie sicher, dass Sie wie oben beschrieben eine unterstützte Netzwerkzugriffsoption auswählen. Erfahren Sie mehr.

Anforderungen für virtuelle Netzwerke

Wenn die API Management-Instanz in einem virtuellen Netzwerk bereitgestellt wird, müssen Sie darüber hinaus die folgenden Netzwerkeinstellungen konfigurieren:

• Aktivieren Sie einen Dienstendpunkt für Key Vault im API-Verwaltungssubnetz.
• Konfigurieren Sie eine Netzwerksicherheitsgruppen-Regel (NSG), um ausgehenden Datenverkehr an die Diensttags AzureKeyVault und AzureActiveDirectory zuzulassen.

Ausführliche Informationen finden Sie unter Netzwerkkonfiguration beim Einrichten der API-Verwaltung in einem virtuellen Netzwerk.

Hinzufügen oder Bearbeiten benannter Werte

Hinzufügen eines Schlüsseltresorgeheimnisses zu API Management

Weitere Informationen finden Sie unter Voraussetzungen für die Key Vault-Integration.

Wichtig

Wenn Sie Ihrer API Management-Instanz ein Schlüsseltresorgeheimins hinzufügen, müssen Sie über die Berechtigung verfügen, Geheimnisse aus dem Schlüsseltresor aufzulisten.

Vorsicht

Wenn Sie in API Management ein Geheimnis aus einem Schlüsseltresor verwenden, dürfen Sie auf keinen Fall das Geheimnis, den Schlüsseltresor oder die verwaltete Identität löschen, die für den Zugriff auf den Schlüsseltresor verwendet wird.

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

2. Wählen Sie unter "APIs" die Option "Benannte Werte>+ Hinzufügen" aus.

3. Geben Sie als Bezeichner einen Namen sowie einen Anzeigenamen ein, der zum Verweisen auf die Eigenschaft in Richtlinien verwendet wird.

4. Fügen Sie ein oder mehrere optionale Tags hinzu, um Ihre benannten Werte besser zu organisieren.

5. Wählen Sie in der Dropdownliste Typ die Option Key Vault aus.

6. Geben Sie den Bezeichner eines Schlüsseltresorgeheimnisses (ohne Version) ein, oder wählen Sie Auswählen aus, um ein Geheimnis aus einem Schlüsseltresor auszuwählen.

   Wichtig

   Wenn Sie selbst einen Bezeichner für ein Schlüsseltresorgeheimnis eingeben, stellen Sie sicher, dass dieser keine Versionsinformationen enthält. Andernfalls wird das Geheimnis nach einer Aktualisierung im Schlüsseltresor nicht automatisch in API Management rotiert.

7. Wählen Sie unter Clientidentität eine systemseitig zugewiesene oder eine vorhandene benutzerseitig zugewiesene verwaltete Identität aus. Erfahren Sie, wie Sie verwaltete Identitäten in Ihrem API Management-Dienst hinzufügen oder bearbeiten.

   Hinweis

   Die Identität benötigt Berechtigungen zum Abrufen und Auflisten von Geheimnissen im Schlüsseltresor. Wenn Sie den Zugriff auf den Schlüsseltresor noch nicht konfiguriert haben, werden Sie von API Management dazu aufgefordert. Der Dienst kann die Identität dann automatisch mit den erforderlichen Berechtigungen konfigurieren.

8. Wählen Sie "Speichern" und dann " Erstellen" aus.

   

Hinzufügen eines einfachen oder geheimen Werts zu API Management

Portal

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
2. Wählen Sie unter APIs die Optionen Benannte Werte>+ Hinzufügen aus.
3. Geben Sie als Bezeichner einen Namen sowie einen Anzeigenamen ein, der zum Verweisen auf die Eigenschaft in Richtlinien verwendet wird.
4. Wählen Sie in der Dropdownliste " Typ " die Option "Nur" oder "Geheim" aus.
5. Geben Sie unter Wert eine Zeichenfolge oder einen Richtlinienausdruck ein.
6. Fügen Sie ein (oder mehrere) optionales Tag hinzu, um die benannten Werte zu organisieren, und wählen Sie dann Speichern aus.
7. Klicken Sie auf Erstellen.

Nachdem der benannte Wert erstellt wurde, können Sie ihn bearbeiten, indem Sie den Namen auswählen. Wenn Sie den Anzeigenamen ändern, werden alle Richtlinien, die auf diesen benannten Wert verweisen, automatisch aktualisiert, sodass sie den neuen Anzeigenamen verwenden.

Azure-Befehlszeilenschnittstelle

So beginnen Sie mit der Verwendung der Azure CLI:

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter "Erste Schritte mit Azure Cloud Shell".

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

  • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Um den Authentifizierungsprozess abzuschließen, führen Sie die in Ihrem Terminal angezeigten Schritte aus. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe der Azure CLI.

  • Installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden und Verwalten von Erweiterungen mit der Azure CLI.

  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Verwenden Sie zum Hinzufügen eines benannten Werts den Befehl "az apim nv create ". Ersetzen Sie Ihren Ressourcengruppennamen und den API-Verwaltungsinstanznamen durch die Werte resource-group und service-name.

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Nachdem Sie einen benannten Wert erstellt haben, können Sie ihn mithilfe des Befehls az apim nv update aktualisieren. Wenn Sie alle benannten Werte anzeigen möchten, führen Sie den Befehl az apim nv list aus:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Führen Sie den Befehl az apim nv show aus, um die Details des benannten Werts anzuzeigen, den Sie für dieses Beispiel erstellt haben:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Dieses Beispiel ist ein geheimer Wert. Der vorherige Befehl gibt den Wert nicht zurück. Um den Wert anzuzeigen, führen Sie den Befehl az apim nv show-secret aus:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Um einen benannten Wert zu löschen, verwenden Sie den Befehl az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Verwenden benannter Werte

In den Beispielen in diesem Abschnitt werden benannte Werte aus der folgenden Tabelle verwendet.

Name	Wert	`Secret`
ContosoHeader	TrackingId	False
ContosoHeaderValue	••••••••••••••••••••••	Richtig
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

Um einen benannten Wert in einer Richtlinie zu verwenden, setzen Sie seinen Anzeigenamen in ein doppeltes Paar geschweifter Klammern (z. B. {{ContosoHeader}}), wie im folgenden Beispiel gezeigt:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

In diesem Beispiel dient ContosoHeader als Name eines Headers in einer set-header-Richtlinie und ContosoHeaderValue als Wert dieses Headers. Wenn diese Richtlinie in einer Anforderung oder Antwort an das API Management-Gateway ausgewertet wird, werden {{ContosoHeader}} und {{ContosoHeaderValue}} durch ihre jeweiligen Werte ersetzt.

Sie können benannte Werte wie im vorherigen Beispiel gezeigt als vollständige Attribut- oder Elementwerte verwenden, aber sie können auch in einen Literaltextausdruck eingefügt oder kombiniert werden, wie im folgenden Beispiel gezeigt:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Benannte Werte können auch Richtlinienausdrücke enthalten. Im folgenden Beispiel wird der Ausdruck ExpressionProperty verwendet.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Beim Auswerten dieser Richtlinie wird {{ExpressionProperty}} durch ihren Wert ersetzt: @(DateTime.Now.ToString()). Da der Wert ein Richtlinienausdruck ist, wird der Ausdruck ausgewertet, und die Richtlinie setzt ihre Ausführung fort.

Sie können dies im Azure-Portal oder im Entwicklerportal durch Aufrufen eines Vorgangs testen, der eine Richtlinie mit entsprechenden benannten Werten aufweist. Im folgenden Beispiel wird ein Vorgang mit den beiden vorherigen set-header-Beispielrichtlinien mit benannten Werten aufgerufen. Beachten Sie, dass die Antwort zwei benutzerdefinierte Header enthält, die mithilfe von Richtlinien mit benannten Werten konfiguriert wurden.

Beim Anzeigen der API-Ablaufverfolgung für einen Aufruf, der die beiden vorherigen Beispielrichtlinien mit benannten Werten enthält, sehen Sie beide set-header-Richtlinien mit den eingefügten benannten Werten und die Auswertung des Richtlinienausdrucks für den benannten Wert, der den Richtlinienausdruck enthält.

Sie können auch die Zeichenfolgeninterpolation mit benannten Werten verwenden.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Der Wert für CustomHeader wird zu The URL encoded value is This+is+a+header+value..

Vorsicht

Wenn eine Richtlinie auf einen geheimen Schlüssel im Azure Key Vault verweist, ist der Wert aus dem Schlüsseltresor für Benutzer sichtbar, die Zugriff auf Abonnements haben, die für die API-Anforderungsablaufverfolgung aktiviert sind.

Benannte Werte können zwar Richtlinienausdrücke, aber keine anderen benannten Werte enthalten. Wenn für einen Wert, z. B. Text: {{MyProperty}}, Text verwendet wird, der einen Verweis auf einen benannten Wert enthält, wird dieser Verweis nicht aufgelöst und ersetzt.

Löschen benannter Werte

Um einen benannten Wert zu löschen, wählen Sie den Namen aus, und wählen Sie dann im Kontextmenü (...) die Option "Löschen" aus.

Wichtig

Wenn Richtlinien in API Management auf den benannten Wert verweisen, können Sie ihn erst löschen, nachdem Sie den benannten Wert aus allen Richtlinien entfernt haben, die ihn verwenden.

Verwandte Inhalte

Weitere Informationen zum Arbeiten mit Richtlinien:

• Richtlinien in Azure API Management
• Gruppenrichtlinienreferenz
• Richtlinienausdrücke