Auswählen der richtigen API Management-Richtlinie
Sie können API Management-Richtlinien ohne Umschreiben von Code zum Steuern des Verhaltens einer bereitgestellten API verwenden.
In Ihrem Unternehmen, das Brettspiele herstellt, verfügen Sie über mehrere APIs, die Partnerorganisationen zum Abrufen von Preisschätzungen, Mitarbeiter zum Überprüfen von Lagerbeständen und Kunden zum Aufgeben von Bestellungen verwenden können. Sie möchten ein bestimmtes Problem hinsichtlich der Leistung beheben und darüber hinaus untersuchen, inwieweit Sie die Richtlinien sonst noch nutzen können.
Dazu wird zunächst erläutert, wozu Richtlinien generell dienen.
Was sind Richtlinien?
In Azure API Management können Administratoren mithilfe bestimmter Konfigurationen Richtlinien zum Ändern des Verhaltens von APIs verwenden. Diese Hauptfunktionalität und dieses Hauptverhalten einer API werden von den Entwicklern entworfen, die den Code schreiben. Administratoren können jedoch mithilfe von Richtlinien Grenzwerte festlegen, Antwortformate konvertieren oder Sicherheitsanforderungen erzwingen. In diesem Modul konzentrieren wir uns auf die Verwendung von Richtlinien zum Einrichten und Steuern eines Caches.
Richtlinien bestehen aus einzelnen Anweisungen, die in einer bestimmten Reihenfolge ausgeführt werden. Die Richtliniendokumente bestehen aus XML-Strukturen, die Elemente enthalten, die Sie zum Steuern des Verhaltens der API verwenden können.
Wann werden Richtlinien ausgeführt?
In Azure API Management werden Richtlinien zu vier verschiedenen Zeitpunkten ausgeführt:
- inbound (eingehend): Diese Richtlinien werden ausgeführt, wenn eine Anforderung von einem Client empfangen wird.
- backend (Back-End): Diese Richtlinien werden ausgeführt bevor eine Anforderung an eine verwaltete API weitergeleitet wird.
- outbound (ausgehend): Diese Richtlinien werden ausgeführt, bevor eine Antwort an einen Client gesendet wird.
- on-error (bei Fehlern): Diese Richtlinien werden ausgeführt, wenn eine Ausnahme ausgelöst wird.
In der Richtlinien-XML-Datei gibt es für jede Ausführungszeit ein separates Tag.
<policies>
<inbound>
<base />
<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
</check-header>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
</outbound>
<on-error>
<base />
</on-error>
</policies>
In diesem Beispiel können Sie sehen, dass die Richtlinie eingehende Anforderungen auf einen Header namens Authorization (Autorisierung) überprüft. Wenn solch ein Header nicht vorhanden ist, zeigt die Richtlinie eine Fehlermeldung an.
Diese Richtlinie übersetzt alle ausgehenden Antworten im JSON-Format in XML.
Richtlinienbereiche
Der Richtlinienbereich bestimmt, inwieweit die Richtlinie angewendet wird. Im Folgenden finden Sie Richtlinienbereiche, aus denen Sie wählen können:
- Global
- Produkt
- API
- Vorgang
Global
Richtlinien, die auf den globalen Bereich angewendet werden, beeinflussen alle APIs innerhalb der API Management-Instanz.
Um den globalen Bereich zu verwenden, wählen Sie im Bereich des API Management-Diensts im linken Menübereich unter API Management die Option APIs und dann im mittleren Menübereich Alle APIs aus. Klicken Sie im Abschnitt Eingehende Verarbeitung oder Ausgehende Verarbeitung auf + Richtlinie hinzufügen, um Richtlinien anzuzeigen, die Sie in diesem Bereich hinzufügen können.
Wählen Sie eine der verfügbaren Optionen aus, um einen Assistenten zu starten, der Sie durch den Vorgang zum Hinzufügen der Richtlinie mit der richtigen Syntax führt:
Sie können den XML-Editor auch direkt öffnen, indem Sie im Abschnitt Eingehende Verarbeitung, Ausgehende Verarbeitung oder Back-Enddas Tagsymbol </> auswählen. Der angezeigte Richtlinien-Editor enthält XML-Standardinhalte. Klicken Sie rechts auf Codeschnipsel anzeigen, um Verknüpfungen anzuzeigen, mit denen Richtlinien hinzugefügt werden:
Produkt
In API Management können Sie eine oder mehrere APIs zu einem einzigen Produkt zusammenstellen und dann den Zugriff auf dieses Produkt als einzelne Entität verwalten. Richtlinien, die auf das Produkt angewendet werden, gelten für alle APIs in diesem Produkt. APIs in anderen Produkten werden nicht beeinflusst. Wenn Sie ein Produkt im Azure-Portal verwalten, wählen Sie den Bereich Richtlinien aus, um Richtlinien über einen Assistenten mit Anleitung oder mithilfe des XML-Richtlinien-Editors hinzuzufügen:
API
Richtlinien, die auf den API-Bereich angewendet werden, beeinflussen nur eine einzige API. Wählen Sie auf der API Management-Homepage die Option APIs und dann die API aus, die Sie verwalten möchten, um eine Richtlinie für den API-Bereich festzulegen. Wählen Sie abschließend auf der Registerkarte Entwurf die Option Alle Vorgänge aus. Sie können eingehende, ausgehende oder Back-End-Richtlinien festlegen, die für alle Vorgänge im Zusammenhang mit dieser API gelten:
Vorgang
Richtlinien, die auf den Vorgangsbereich angewendet werden, beeinflussen nur einen API-Vorgang. Im folgenden Beispiel hat der Administrator den GetSpeaker-Vorgang in der Demo Conference API ausgewählt und kann Richtlinien für eingehenden, ausgehenden oder Back-End-Datenverkehr festlegen, die nur auf diesen Vorgang angewendet werden:
In welcher Reihenfolge werden Richtlinien angewendet?
Sie können das <base />-Tag verwenden, um festzulegen, wann Richtlinien eines höheren Bereichs angewendet werden sollen. Betrachten Sie beispielsweise diese Richtlinie, die auf den API-Bereich angewendet wird:
<policies>
<inbound>
<base />
<find-and-replace from="game" to="board game" />
</inbound>
</policies>
Da das <base>-Tag über dem <find-and-replace>-Tag angezeigt wird, wendet Azure API Management zuerst Richtlinien auf den globalen Bereich und den Produktbereich an, und führt dann die find-and-replace-Richtlinie aus.
Häufig verwendete Richtlinien
Als Nächstes wird erläutert, wie Sie Richtlinien in API Management verwenden können: Es werden einige der am häufigsten verwendeten Richtlinien eingeführt, und Sie können die API Management-Dokumentation lesen, um eine vollständige Liste und Beispiele zu erhalten.
Richtlinien zum Einschränken des Zugriffs
Sie können mehrere Richtlinien verwenden, um den Zugriff auf eine API oder deren Vorgänge zu verhindern oder einzuschränken. Beispiel:
Verwenden Sie die Richtlinie HTTP-Header überprüfen, um einen HTTP-Header auf eine Eigenschaft zu überprüfen. Wenn die Eigenschaft nicht gefunden wird, löscht Azure API Management die Anforderung.
Die Richtlinie Limit call rate by subscription (Begrenzen der Aufrufrate nach Abonnement) schränkt die Anzahl der Aufrufe ein, die von einem einzelnen API-Abonnement stammen können. Diese Richtlinie kann sicherstellen, dass Benutzer eines Abonnements nicht Ihre gesamte Bandbreite verwenden.
Verwenden Sie die Richtlinie Limit call rate by key (Begrenzen der Aufrufrate nach Schlüssel), wenn Sie die Anzahl der Aufrufe eines einzelnen Zugriffsschlüssels einschränken möchten.
Verwenden Sie die Richtlinie Restrict caller IP's (Einschränken der IP-Adresse von Aufrufern), um Aufrufe von bestimmten IP-Adressen oder Bereichen von IP-Adressen zuzulassen oder zu verweigern. Diese Möglichkeit zum Einschränken des Zugriffs ähnelt den Einschränkungen für IP-Adressen, die Sie für Ihre Firewall anwenden können.
Richtlinien für die Authentifizierung
Bestimmte Richtlinien ermöglichen das Steuern der Authentifizierung. Beispiel:
Verwenden Sie die Richtlinie Standardauthentifizierung zum Aktivieren der Authentifizierung in Nur-Text-Elementen. Diese Form der Authentifizierung wird weitgehend unterstützt, sollte aber mit der SSL-Verschlüsselung geschützt werden, da die Anmeldeinformationen sonst bei einem böswilligen Angriff auf das Netzwerk abgefangen werden können.
Verwenden Sie die Richtlinie Authenticate with client certificate (Authentifizieren mit Clientzertifikat), um Clients die Authentifizierung mit einem Clientzertifikat zu ermöglichen.
Domänenübergreifende Richtlinien
Domänenübergreifende Anforderungen werden als Sicherheitsbedrohung angesehen und von Browsern und APIs abgelehnt. Da diese bei bestimmten Vorgängen aber erwünscht sein können, ermöglichen API Management-Richtlinien deren sichere Verwendung.
Verwenden Sie die Richtlinie Allow cross-domain calls (Domänenübergreifende Aufrufe zulassen), um Aufrufe von Adobe Flash und Silverlight zuzulassen. Verwenden Sie die CORS-Richtlinie, um Ihre API oder Client-Apps zuzulassen, wenn diese Cross-Origin Resource Sharing (CORS) benötigen.
Im Browser ausgeführter AJAX-Code verwendet JSON mit Padding, um domänenübergreifende Aufrufe sicher zu durchzuführen. Verwenden Sie die JSONP-Richtlinie, um Clients die Verwendung dieser Technik zu erlauben.
Transformationsrichtlinien
Oft hilft eine Änderung des Formats oder Inhalts der Antwort einer verwalteten API. Hierfür können Sie verschiedene Richtlinien verwenden. Beispiel:
Verwenden Sie die Richtlinien Convert JSON to XML (Konvertieren von JSON in XML) und Convert XML to JSON (Konvertieren von XML in JSON), um aus und in JSON bzw. XML zu konvertieren. Diese Richtlinien helfen häufig dabei, mehrere APIs in einem Produkt konsistent zu machen. Außerdem kann so die Notwendigkeit des Umschreibens des API-Codes vermieden werden, wenn eine App eine Antwort in einem bestimmten Format erwartet.
Manchmal möchten Sie vielleicht eine Antwort im XML-Format haben, das Schema aber ändern. Verwenden Sie in solchen Fällen die Richtlinie Transform XML (Transformieren von XML), um eine XSLT-Vorlage anzuwenden.
Verwenden Sie Zeichenfolge im Text suchen und ersetzen, um eine Zeichenfolge zu ersetzen. Wenn sich beispielsweise ein Markenname geändert hat, können Sie mithilfe dieser Richtlinie sicherstellen, dass die Änderung für alle Antworten übernommen wird, auch wenn die zugrunde liegenden Daten noch Verweise auf den alten Namen enthalten.
Die Richtlinie Mask URLs in content (URLs in Inhalt maskieren) kann alle Links im Antworttext erneut generieren, sodass diese auf einen anderen Speicherort verweisen. Diese Richtlinie ist besonders dann hilfreich, wenn eine Website oder Web-API umgezogen ist.
Verwenden Sie die Richtlinie Set body (Text festlegen), um den Nachrichtentext für eingehende und ausgehende Anforderungen festzulegen.
Wenn Sie eine eingehende HTTP-Anforderung oder ausgehende Antwort ändern möchten, können Sie verschiedene Richtlinien verwenden. Verwenden Sie die Richtlinie Set HTTP header (HTTP-Header festlegen), um einer vorhandenen Antwort oder einem Anforderungsheader Elemente hinzuzufügen. Verwenden Sie die Richtlinie Set query string parameter (Abfragezeichenfolgenparameter festlegen), wenn Sie die nach dem Fragezeichen in der URL angezeigten Abfragezeichenfolgen ändern möchten. Wenn eine öffentliche und vom Benutzer angeforderte URL einem anderen internen Ziel zugeordnet werden muss, kann die Richtlinie Rewrite URL (URL umschreiben) sowohl Anforderungen für eingehenden als auch für ausgehenden Datenverkehr verarbeiten.
Erweiterte Richtlinien
Diese Richtlinien können bei Szenarios für nicht standardmäßiges Verhalten verwendet werden.
Verwenden Sie beispielsweise die Richtlinie Control flow (Ablaufsteuerung), wenn Sie eine Richtlinie nur dann anwenden möchten, wenn die Antwort einen bestimmten Test besteht.
Verwenden Sie die Richtlinie Forward request (Anforderung weiterleiten) zum Weiterleiten einer Anforderung an einen Back-End-Server.
Verwenden Sie die Wiederholungsrichtlinie, um das Verhalten nach der fehlerhaften Ausführung einer Aktion zu steuern. In der Wiederholungsrichtlinie enthaltene Richtlinienanweisungen werden wiederholt ausgeführt, bis die Bedingung erfüllt ist. Die Ausführung wird in den angegebenen Zeitintervallen wiederholt, bis die Anzahl der Wiederholungsversuche erreicht ist.
Die Richtlinie Send one-way request (Unidirektionale Anforderung senden) kann eine Anforderung an eine URL senden, ohne auf die Antwort zu warten.
Verwenden Sie zum Speichern eines Werts in einer benannten Variable die Richtlinie Variable festlegen, wenn Sie einen Wert für eine spätere Berechnung oder einen späteren Test speichern möchten.