API-Anfragen brauchen Kontrollen? API-Management-Policies anwenden und testen

#api-management #policies #security #transformation

APIM-Policies sind Regeln, die am Gateway vor oder nach einem Backendaufruf ausgeführt werden. Ein Gateway kann beispielsweise unvollständige Anfragen ablehnen, die Aufrufhäufigkeit eines Clients begrenzen oder eine Anfrage an das vom Backend erwartete Format anpassen. Dafür musst du die Backendanwendung nicht ändern.

Verwende apim-ctgateway-weu, den Consumption-Tarif und CloudTrips Petstore aus dem API-Import-Trip weiter. Du benötigst weder eine neue Azure-Ressource noch ein Upgrade auf einen anderen Tarif. Lasse Subscription required aktiviert.

Wir wenden Regeln nur auf GET /pet/findByStatus an:

Kontrolle	Sichtbares Ergebnis
Bestehende Anforderung eines Subscription-Schlüssels	Ohne gültigen APIM-Schlüssel kann ein Aufrufer die API nicht nutzen
Erforderlicher Labheader	Fehlender oder falscher Header → HTTP 400
Anfragelimit	Zu viele Aufrufe mit derselben APIM-Subscription → HTTP 429
Anfragetransformation	Der Client sendet `status=sold`; das Gateway sendet `status=available` an Petstore
Antworttransformation	Das Gateway ergänzt einen Header mit dem tatsächlich verwendeten Statuswert

Der Header X-CloudTrips-Client: lab-demo ist ein einfaches Beispiel für Anfragevalidierung. Jeder kann ihn kopieren; er ist keine Authentifizierung. Die Zugriffskontrolle erfolgt in diesem Lab über den Subscription-Schlüssel. Benutzeridentität und Berechtigungen erfordern ein passendes Authentifizierungs- und Autorisierungskonzept, etwa mit validierten OAuth-Zugriffstokens.

Operation als Geltungsbereich wählen

Öffne API Management → apim-ctgateway-weu → APIs → APIs → CloudTrips Petstore → Design.

Wähle Finds Pets by status, erkennbar an GET /pet/findByStatus. Öffne den Policy-Codeeditor (</>) unter Inbound processing.

Wende diese Policy auf die ausgewählte Operation an. Behalte die Policy zum Entfernen des Schlüssels aus dem vorherigen Trip unter All operations bei. Das folgende <base /> übernimmt sie, sodass dein APIM-Subscription-Schlüssel weiterhin entfernt wird, bevor die Anfrage das öffentliche Backend erreicht.

In diesem Lab hat die Operation noch keine eigene angepasste Policy. Ersetze ihr Policydokument durch:

<policies>
  <inbound>
    <base />
    <check-header name="X-CloudTrips-Client"
                  failed-check-httpcode="400"
                  failed-check-error-message="Send X-CloudTrips-Client: lab-demo."
                  ignore-case="false">
      <value>lab-demo</value>
    </check-header>
    <rate-limit calls="3" renewal-period="60" />
    <set-query-parameter name="status" exists-action="override">
      <value>available</value>
    </set-query-parameter>
    <set-header name="Accept" exists-action="override">
      <value>application/json</value>
    </set-header>
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-header name="X-CloudTrips-Effective-Status" exists-action="override">
      <value>@(context.Request.Url.Query.GetValueOrDefault("status", ""))</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Wähle Save und gib der Änderung kurz Zeit, das Gateway zu erreichen.

Inbound-Regeln laufen vor dem Backendaufruf; outbound-Regeln verändern die Antwort. Die Anweisungen werden der Reihe nach ausgeführt: Die Headerprüfung steht vor dem Anfragelimit. Dort abgelehnte Anfragen erreichen diese Rate-limit-Regel deshalb nicht. Der Ausdruck im Antwortheader liest den Abfrageparameter, nachdem die Inbound-Policy ihn geändert hat.

Das Limit beträgt drei Aufrufe pro 60 Sekunden je APIM-Subscription, nicht je Browser oder Azure-Abrechnungsabonnement. Wir verwenden rate-limit, das Consumption unterstützt. Die separate Policy rate-limit-by-key wird in diesem Tarif nicht unterstützt.

Test 1: Fehlenden Header ablehnen

Öffne Test → GET /pet/findByStatus. Behalte den automatisch gesetzten Ocp-Apim-Subscription-Key bei und verwende während aller Tests dieselbe ausgewählte APIM-Subscription. Lasse den Schlüssel ausgeblendet.

Setze status: sold. Füge X-CloudTrips-Client noch nicht hinzu. Wähle Send.

Erwartet wird 400 Bad Request mit einer Meldung, die Folgendes enthält:

Send X-CloudTrips-Client: lab-demo.

Das Gateway hat die Anfrage vor dem Aufruf von Petstore abgelehnt. Bei 401 fehlt der APIM-Subscription-Schlüssel oder ist ungültig. Behebe zuerst diesen Fehler; eine Änderung des Labheaders löst kein Schlüsselproblem.

APIM-Testkonsole mit HTTP 400 wegen des fehlenden erforderlichen Labheaders.

Test 2: Anfrage annehmen und transformieren

Behalte status: sold bei und ergänze unter Request headers:

X-CloudTrips-Client: lab-demo

Wähle Send. Erwartet wird 200 OK mit einem JSON-Array. Suche unter HTTP response → Headers nach:

X-CloudTrips-Effective-Status: available

HTTP-Headernamen können in Kleinbuchstaben erscheinen; das ist gleichwertig.

Du hast beim Gateway Tiere mit Status sold angefragt. Die Policy hat den Status jedoch vor der Weiterleitung durch available ersetzt. Der Antwortheader zeigt den tatsächlich verwendeten Abfragewert. Zurückgegebene Tiere sollten status: available haben. Die Daten der öffentlichen Demo können sich ändern. Ist das Array leer, zeigt der Antwortheader weiterhin den vom Gateway verwendeten Abfragewert.

Außerdem setzt das Gateway Accept: application/json für die Backendanfrage. Den Antwortheader hat APIM ergänzt; der Petstore-Code wurde nicht geändert. Wir ändern den angefragten Filter bewusst, um eine Transformation zu zeigen. Solche Überschreibungen sollten in echten APIs zum vorgesehenen Verhalten der Schnittstelle passen.

Erfolgreicher Gatewayaufruf mit status sold in der Anfrage und X-CloudTrips-Effective-Status available in den Antwortheadern.

Test 3: Anfragelimit auslösen

Behalte den gültigen Labheader, den Subscription-Schlüssel und status: sold bei. Klicke innerhalb von 60 Sekunden mehrmals auf Send. Der erfolgreiche Aufruf aus Test 2 zählt bereits zum Limit.

Sobald das Kontingent erschöpft ist, wird 429 Too Many Requests erwartet. Der Antwortheader Retry-After enthält die empfohlene Wartezeit in Sekunden. Die Begrenzung wird verteilt umgesetzt; verlasse dich daher nicht darauf, dass genau der vierte Klick blockiert wird.

APIM-Testkonsole mit HTTP 429 Too Many Requests und dem Retry-After-Header.

Sende keine weiteren Anfragen, warte mindestens das angegebene Intervall und versuche es erneut. Falls du weiter gedrosselt wirst, warte volle 60 Sekunden ohne Anfragen. Ein erfolgreicher Aufruf sollte wieder 200 zurückgeben.

Bei 400 und 429 kann der eigene Outbound-Header fehlen, weil diese Anfragen bereits in der Inbound-Verarbeitung enden. Das ist erwartetes Verhalten.

Falls die Ergebnisse abweichen

200 ohne erforderlichen Header: Prüfe, ob die Policy auf derselben Operation gespeichert ist, die du testest, und ob die Anfrage deine APIM-Gateway-URL verwendet.
400 trotz Header: Verwende genau X-CloudTrips-Client: lab-demo. Der konfigurierte Wertevergleich unterscheidet Groß- und Kleinschreibung.
429 schon bei Test 2: Frühere Aufrufe haben das Kontingent verbraucht. Warte ohne weitere Anfragen und versuche es erneut.
Kein 429: Behalte dieselbe APIM-Subscription bei und sende die Aufrufe innerhalb einer Minute. Prüfe, ob rate-limit auf der getesteten Operation gespeichert ist.
5xx vom Backend: Der öffentliche Petstore-Dienst kann vorübergehend ausfallen. Versuche es später erneut, statt die Gatewayprüfungen zu entfernen.

Abschluss

Um die Operation für den nächsten Trip zurückzusetzen, ersetze die Policy dieser Operation durch:

<policies>
  <inbound><base /></inbound>
  <backend><base /></backend>
  <outbound><base /></outbound>
  <on-error><base /></on-error>
</policies>

Speichere. Dadurch entfernst du die Labheader-Anforderung, das Anfragelimit und die Transformationen. Die geerbten Regeln zum Entfernen des Schlüssels unter All operations bleiben erhalten. Lasse Subscription required aktiviert.

Behalte rg-cloudtrips-apim-test-weu für den nächsten API-Trip. Wenn du mit APIM fertig bist, lösche stattdessen die Ressourcengruppe.