Importieren einer WebSocket-API

GILT FÜR: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium

Mit der WebSocket-API-Lösung von API Management können API-Herausgeber über das Azure-Portal, die Azure CLI, Azure PowerShell und andere Azure-Tools schnell eine WebSocket-API zu API Management hinzufügen.

Sie können WebSocket-APIs schützen, indem Sie vorhandene Zugriffssteuerungsrichtlinien wie JWT-Validierung anwenden. Sie können die WebSocket-APIs auch mithilfe der API-Testkonsolen im Azure-Portal und im Entwicklerportal testen. Auf der Grundlage vorhandener Beobachtungsfunktionen stellt das API Management Metriken und Protokolle für die Überwachung und die Problembehandlung von WebSocket-APIs bereit.

In diesem Artikel werden die folgenden Themen behandelt:

• Das Verstehen des Websocket-Passthrough-Flusses.
• Das Hinzufügen einer WebSocket-API in Ihre API Management-Instanz.
• Testen der WebSocket-API
• Anzeigen der Metriken und Protokolle für die WebSocket-API
• Erfahren Sie mehr über die WebSocket-API-Einschränkungen.

Voraussetzungen

• Eine bestehende API Management-Instanz. Erstellen Sie eine, falls nicht schon geschehen.
• Eine WebSocket-API.
• Azure CLI

WebSocket-Passthrough

Das API Management unterstützt den WebSocket-Passthrough.

Während des WebSocket-Passthrough stellt die Clientanwendung eine WebSocket-Verbindung mit dem API Management-Gateway her. Das API Management-Gateway stellt dann eine Verbindung mit den entsprechenden Back-End-Diensten her. Das API Management vermittelt dann die WebSocket Client-Server-Nachrichten.

1. Die Clientanwendung sendet eine WebSocket Handshake-Anforderung an das APIM-Gateway, die den OnHandshake-Vorgang aufruft.
2. Das APIM-Gateway sendet eine WebSocket-Handshake-Anforderung an den entsprechenden Back-End-Dienst.
3. Der Back-End-Dienst aktualisiert eine Verbindung mit WebSocket.
4. Das APIM-Gateway aktualisiert die entsprechende Verbindung mit WebSocket.
5. Nachdem das Verbindungspaar eingerichtet wurde, vermittelt das APIM die Nachrichten zwischen der Clientanwendung und dem Back-End-Dienst hin und her.
6. Die Clientanwendung sendet eine Nachricht an das APIM-Gateway.
7. Das APIM-Gateway leitet die Nachricht an den Back-End-Dienst weiter.
8. Der Back-End-Dienst sendet eine Nachricht an das APIM-Gateway.
9. Das APIM-Gateway leitet die Nachricht an die Clientanwendung.
10. Wenn eine der beiden Seiten sich abmeldet, trennt das APIM die entsprechende Verbindung.

Hinweis

Die clientseitigen und backend-seitigen Verbindungen bestehen aus einer 1:1-Zuordnung.

Der OnHandshake-Vorgang

Wenn eine Clientanwendung versucht, eine WebSocket-Verbindung mit einem Back-End-Dienst herzustellen, sendet sie per WebSocket-Protokollzunächst eine öffnende Handshake-Anforderung. Jede WebSocket-API in dem API Management verfügt über einen OnHandshake-Vorgang. Der OnHandshake ist ein unveränderlicher, nicht entfernbarer, automatisch erstellter Systemvorgang. Mit dem OnHandshake-Vorgang können die API-Herausgeber diese Handshake-Anforderungen abfangen und die API Management-Richtlinien auf sie anwenden.

Das Hinzufügen einer WebSocket-API

Portal

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

2. Wählen Sie im linken Menü APIs>+ API hinzufügen aus.

3. Wählen Sie unter Neue API definierendie Option WebSocket aus.

4. Wählen Sie im Dialogfeld Vollständig aus, und füllen Sie die erforderlichen Formularfelder aus.

   Feld	Beschreibung
   Anzeigename	Das ist der Name, mit dem Ihre WebSocket-API angezeigt wird.
   Name	Das ist der Rohname der WebSocket-API. Er wird automatisch ausgefüllt, wenn Sie den Anzeigenamen eingeben.
   Die WebSocket-URL	Die Basis-URL mit ihrem Websocket-Namen. Beispiel: ws://example.com/your-socket-name
   URL-Schema	Übernehmen Sie die Standardeinstellung.
   API-URL-Suffix	Fügen Sie ein URL-Suffix hinzu, um diese spezifische API in dieser API Management-Instanz zu identifizieren. Es muss in dieser APIM-Instanz eindeutig sein.
   Produkte	Ordnen Sie Ihre WebSocket-API einem Produkt zu, um es zu veröffentlichen.
   Gateways	Ordnen Sie Ihre WebSocket-API den vorhandenen Gateways zu.

5. Klicken Sie auf Erstellen.

Testen Ihrer WebSocket-API

1. Navigieren Sie zu Ihrer WebSocket-API.

2. Klicken Sie in Ihrer WebSocket-API auf den onHandshake-Vorgang.

3. Klicken Sie auf die Registerkarte Test, um auf die Testkonsole zuzugreifen.

4. Geben Sie optional Abfragezeichenfolgenparameter an, die für den WebSocket-Handshakevorgang benötigt werden.

   

5. Klicken Sie auf Verbinden.

6. Zeigen Sie den Verbindungsstatus unter Ausgabe an.

7. Geben Sie den Wert unter Nutzdaten ein.

8. Klicken Sie auf Senden.

9. Zeigen Sie empfangene Meldungen unter Ausgabe an.

10. Wiederholen Sie die vorherigen Schritte, um verschiedene Nutzdaten zu testen.

11. Wenn der Test abgeschlossen ist, klicken Sie auf Verbindung trennen.

Anzeigen von Metriken und Protokollen

Verwenden Sie Standardfunktionen für API Management und Azure Monitor zum Überwachen von WebSocket-APIs:

• Anzeigen von API-Metriken in Azure Monitor
• Aktivieren Sie optional Diagnoseeinstellungen, um API Management-Gatewayprotokolle zu erfassen und anzuzeigen, die WebSocket-API-Vorgänge enthalten.

Der folgende Screenshot zeigt beispielsweise aktuelle WebSocket-API-Antworten mit Code 101 aus der Tabelle ApiManagementGatewayLogs. Diese Ergebnisse zeigen den erfolgreichen Wechsel der Anforderungen vom TCP- zum WebSocket-Protokoll an.

Einschränkungen

Weiter unten finden Sie die aktuellen Einschränkungen der WebSocket-Unterstützung im API Management:

• Die WebSocket-APIs werden im Consumption-Tarif noch nicht unterstützt.
• WebSocket-APIs unterstützen die folgenden gültigen Puffertypen für Nachrichten: Close, BinaryFragment, BinaryMessage, UTF8Fragment und UTF8Message.
• Derzeit unterstützt die Set-Header-Richtlinie keine Änderung bestimmter bekannter Header, einschließlich Host Header, in onHandshake-Anforderungen.
• Während des TLS-Handshakes mit einem WebSocket-Back-End überprüft API Management, ob das Serverzertifikat vertrauenswürdig ist und ob sein Antragstellername mit dem Hostnamen übereinstimmt. Bei HTTP-APIs validiert API Management, dass das Zertifikat vertrauenswürdig ist, validiert jedoch nicht, dass Hostname und Betreff übereinstimmen.

Informationen zu WebSocket-Verbindungsgrenzwerten finden Sie unter API Management-Grenzwerte.

Nicht unterstützte Richtlinien

Die folgenden Richtlinien werden nicht von dem OnHandshake unterstützt und können nicht auf den OnHandshake-Vorgang angewendet werden:

• Modellantwort
• Aus Cache abrufen
• Store to cache
• Allow cross-domain calls
• CORS
• JSONP
• Anforderungsmethode festlegen
• Text festlegen
• XML zu JSON konvertieren
• Convert JSON to XML (Konvertieren von JSON in XML)
• Das Transformieren von XML mithilfe von XSLT
• Inhalt prüfen
• Validieren von Parametern
• Validieren von Headern
• Validieren von Statuscodes

Hinweis

Wenn Sie die Richtlinien in höheren Geltungsbereichen (d. h. global oder Produkt) angewendet haben und sie von einer WebSocket-API über die Richtlinie geerbt wurden, werden sie zur Laufzeit übersprungen.

Zugehörige Themen

• Einschränkungen beim API-Import
• Importieren einer OpenAPI-Spezifikation
• Importieren einer SOAP-API
• Importieren einer SOAP-API und Konvertieren dieser in REST
• Importieren einer App Service-API
• Importieren einer Container-App-API
• Importieren einer WebSocket-API
• Importieren einer GraphQL-API
• Importieren eines GraphQL-Schemas und Einrichten von Feldauflösern
• Importieren einer Azure Functions-App als API
• Importieren einer Logik-App als API
• Tutorial: Integrieren von API Management in Service Fabric in Azure
• Importieren einer OData-API
• Importieren von SAP OData-Metadaten
• Importieren einer gRPC-API
• Bearbeiten von APIs

Nächste Schritte

Transformieren und Schützen einer veröffentlichten API