APIs brauchen ein zentrales Gateway? API Management erstellen und eine API importieren

#api-management #apis #openapi #gateway

Azure API Management (APIM) bietet Clients einen zentralen Zugang zu deinen APIs. Stell dir eine App vor, die separate Dienste für Bestellungen, Zahlungen und Lagerbestände aufruft. APIM kann diese über ein gemeinsames Gateway bereitstellen. Dort verwaltest du Zugriffsregeln, Anfragelimits und Transformationen, statt jede Regel in jedem Dienst einzeln umzusetzen.

Client → API-Management-Gateway → Bestehende Backend-API
Client ← API-Management-Gateway ← Antwort des Backends

APIM führt den Anwendungscode des Backends nicht aus. Beim Import werden Routen und Beschreibung der API zum Gateway hinzugefügt; die eigentliche Anfrage verarbeitet weiterhin das ursprüngliche Backend.

Für dieses Lab verwenden wir die öffentlich gehostete Beispiel-API Swagger Petstore. Du benötigst weder App Service noch Logic App, Integration Account oder lokale Anwendung. Wir lesen ausschließlich Beispieldaten.

API Management erstellen

Suche im Azure-Portal nach API Management services → Create:

Subscription: CloudTrips TEST
Resource group: rg-cloudtrips-apim-test-weu
Region: West Europe
Resource name: apim-ctgateway-weu
Organization name: CloudTrips
Administrator email: deine E-Mail-Adresse
Pricing tier: Consumption

Ergänze einen eindeutigen Namenszusatz, falls der Ressourcenname vergeben ist. Der Name wird Teil deiner Gatewayadresse, beispielsweise https://apim-ctgateway-weu.azure-api.net.

Consumption wird nach API-Nutzung abgerechnet und reicht für dieses Lab mit einer öffentlichen HTTP-API aus. Ein Entwicklerportal und private Netzwerkanbindung sind nicht enthalten. Du benötigst ein Azure-Abonnement, keine separate Lizenz pro Benutzer. Prüfe die Kostenschätzung und lasse optionale Monitoring- und Sicherheitsdienste abgewählt. Verwende öffentlichen Netzwerkzugriff; VNet und Managed Identity werden hier nicht benötigt.

Wähle Review + create → Create. Die Bereitstellungsdauer variiert. Warte vor dem Import, bis die Bereitstellung abgeschlossen und die Instanz verfügbar ist.

API-Management-Übersicht mit Consumption-Tarif und Gateway-URL.

Bestehende API importieren

Öffne die Instanz → APIs → APIs → Add API → OpenAPI. Wenn die OpenAPI-Kachel bereits sichtbar ist, wähle sie direkt. Wähle Full, falls das Formular zwischen Basic und Full unterscheidet.

Ein OpenAPI-Dokument beschreibt eine API maschinenlesbar: ihre Pfade, Methoden, Parameter und Antwortformate. APIM erstellt daraus die Operationen, die du über das Gateway aufrufen kannst.

Trage ein:

OpenAPI specification: https://petstore3.swagger.io/api/v3/openapi.json
Display name: CloudTrips Petstore
Name: ct-petstore
URL scheme: HTTPS
API URL suffix: petstore
Products: leer lassen
Version this API: No

Warte, bis die Definition geladen ist, und passe die automatisch gesetzten Namen an die obigen Werte an. Behalte die übrigen Importoptionen bei und wähle Create.

Wähle CloudTrips Petstore → Settings. Prüfe diese Werte und speichere Änderungen:

Web service URL: https://petstore3.swagger.io/api/v3
API URL suffix: petstore
Subscription required: On

Die Web service URL ist die Backendadresse. Das API URL suffix identifiziert diese API auf deinem Gateway. Prüfe unter Design, ob GET /pet/findByStatus unter den importierten Operationen erscheint.

Products bündeln APIs für ihre Nutzer. Wir können Products leer lassen, weil das Portal die API mit dem integrierten Testabonnement der Instanz aufrufen kann.

Importierte CloudTrips-Petstore-API mit ihren Operationen, darunter GET /pet/findByStatus.

Gatewayschlüssel am Gateway behalten

Eine APIM-Subscription gewährt über einen Schlüssel Zugriff auf APIs. Sie ist etwas anderes als dein Azure-Abonnement für die Abrechnung. Wenn Subscription required aktiviert ist, benötigen Aufrufer einen gültigen Schlüssel für diese API.

APIM kann den Schlüssel standardmäßig an das Backend weiterleiten. Unser Backend ist ein öffentlicher Beispieldienst. Deshalb entfernen wir den Schlüssel vor der Weiterleitung. APIM prüft ihn weiterhin am Gateway.

Wähle unter CloudTrips Petstore → Design → All operations im Bereich Inbound processing den Policy-Codeeditor (</>). Ersetze für diese neu importierte Lab-API das Policydokument durch:

<policies>
  <inbound>
    <base />
    <set-header name="Ocp-Apim-Subscription-Key" exists-action="delete" />
    <set-query-parameter name="subscription-key" exists-action="delete" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Wähle Save. Die beiden Löschregeln entfernen den Subscription-Schlüssel aus dem weitergeleiteten Header beziehungsweise Querystring. Die <base />-Elemente erhalten das Verhalten geerbter Policies. Wende dies auf All operations an, nicht nur auf eine Operation.

Über das Gateway testen

Öffne CloudTrips Petstore → Test. Wähle Finds Pets by status oder suche die Operation anhand von GET /pet/findByStatus.

Setze:

Query parameter:
  status: available
Request header:
  Accept: application/json

Die Testkonsole des Portals befüllt Ocp-Apim-Subscription-Key normalerweise mit dem Schlüssel der integrierten all-access subscription. Falls eine Subscription-Auswahl erscheint, wähle dieses Abonnement für den Administratortest. Lasse den Schlüssel ausgeblendet und übernimm ihn weder in Screenshots noch in Clientanwendungen.

Wähle Send. Erwartet werden 200 OK und ein JSON-Array mit Tieren. Die Demo wird gemeinsam genutzt, deshalb können sich die Datensätze ändern. Auch ein leeres Array mit HTTP 200 ist eine gültige Antwort.

Prüfe, dass die Request URL den azure-api.net-Hostnamen deines Gateways verwendet. Mit dem Beispielnamen lautet die Anfrage:

https://apim-ctgateway-weu.azure-api.net/petstore/pet/findByStatus?status=available

APIM leitet sie weiter an:

https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available

petstore ist dein Gatewaysuffix; es wird nicht an die Backend-URL angehängt.

APIM-Testkonsole mit Anfrage an das Gateway und einer JSON-Antwort mit 200 OK; der Subscription-Schlüssel ist ausgeblendet.

Öffne zum Prüfen der Zugriffskontrolle die Gateway-Anfrage-URL in einem neuen Browsertab ohne Subscription-Schlüssel. Erwartet wird 401 mit einem Hinweis auf den fehlenden Schlüssel. Das ist beabsichtigt: Der Portaltest enthielt einen Schlüssel, die Browseranfrage nicht.

Das Petstore-Backend bleibt unter seiner eigenen Adresse öffentlich erreichbar. Der Schutz des Gateways verhindert nicht automatisch den direkten Backendzugriff. In einer echten Bereitstellung würdest du auch den Zugriff auf das Backend einschränken oder authentifizieren.

Falls der Test fehlschlägt

401 in der Testkonsole: Prüfe, ob der APIM-Subscription-Schlüssel gesetzt und das ausgewählte Abonnement aktiv ist. Deaktiviere Subscription required nicht, um einen fehlenden Schlüssel zu umgehen.
404: Prüfe Backend-URL, Gatewaysuffix und ausgewählte Operation. Trage /pet/findByStatus nicht in die Web service URL ein; der Pfad gehört bereits zur Operation.
Importfehler oder 5xx vom Backend: Der öffentliche Demodienst kann vorübergehend ausfallen. Versuche es später erneut; das Neuerstellen von APIM repariert dieses Backend nicht.

Abschluss

Du hast jetzt ein Gateway vor einer bestehenden API. Eine erfolgreiche Anfrage wird über APIM weitergeleitet, eine Anfrage ohne Schlüssel am Gateway abgewiesen.

Behalte rg-cloudtrips-apim-test-weu, wenn du mit API-Policies oder Versionierung weitermachst. Lösche andernfalls die Ressourcengruppe. Wenn du nur die importierte API löschst, bleibt die API-Management-Instanz bestehen.