Importieren einer WebSocket-API

  • Artikel

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.

Hinweis

Diese Funktion ist derzeit in Arbeitsbereichen nicht verfügbar.

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

WebSocket-Passthrough

Das API Management unterstützt den WebSocket-Passthrough.

Visuelle Darstellung des WebSocket-Passthrough-Flusses

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.

Ein Bildschirmbeispiel für einen „OnHandshake“

Das Hinzufügen einer WebSocket-API

    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.

    Beispiel zum Testen einer API

  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.

Abfrageprotokolle für WebSocket-API-Anforderungen

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.

Nächste Schritte

Transformieren und Schützen einer veröffentlichten API