Importera ett WebSocket-API

Med API Managements WebSocket API-lösning kan API-utgivare snabbt lägga till ett WebSocket-API i API Management via Azure-portalen, Azure CLI, Azure PowerShell och andra Azure-verktyg.

Du kan skydda WebSocket-API:er genom att tillämpa befintliga principer för åtkomstkontroll, till exempel JWT-validering. Du kan också testa WebSocket-API:er med hjälp av API-testkonsolerna i både Azure-portalen och utvecklarportalen. API Management bygger på befintliga observerbarhetsfunktioner och tillhandahåller mått och loggar för övervakning och felsökning av WebSocket-API:er.

I den här artikeln kommer du att:

  • Förstå flödet för websocket-genomströmning.
  • Lägg till ett WebSocket-API i din API Management-instans.
  • Testa webSocket-API:et.
  • Visa mått och loggar för webSocket-API:et.
  • Lär dig begränsningarna för WebSocket API.

Förutsättningar

WebSocket-genomströmning

API Management stöder WebSocket-genomströmning.

Visual illustration of WebSocket passthrough flow

Under webSocket-genomströmningen upprättar klientprogrammet en WebSocket-anslutning med API Management Gateway, som sedan upprättar en anslutning till motsvarande serverdelstjänster. API Management proxyservrar sedan WebSocket klient-server meddelanden.

  1. Klientprogrammet skickar en WebSocket-handskakningsbegäran till APIM-gatewayen och anropar onHandshake-åtgärden.
  2. APIM-gatewayen skickar webSocket-handskakningsbegäran till motsvarande serverdelstjänst.
  3. Serverdelstjänsten uppgraderar en anslutning till WebSocket.
  4. APIM-gatewayen uppgraderar motsvarande anslutning till WebSocket.
  5. När anslutningsparet har upprättats förmedlar APIM meddelanden fram och tillbaka mellan klientprogrammet och serverdelstjänsten.
  6. Klientprogrammet skickar ett meddelande till APIM-gatewayen.
  7. APIM-gatewayen vidarebefordrar meddelandet till serverdelstjänsten.
  8. Serverdelstjänsten skickar ett meddelande till APIM-gatewayen.
  9. APIM-gatewayen vidarebefordrar meddelandet till klientprogrammet.
  10. När någon av sidorna kopplas från avslutar APIM motsvarande anslutning.

Kommentar

Anslutningarna på klientsidan och serverdelen består av en-till-en-mappning.

onHandshake-åtgärd

När ett klientprogram försöker upprätta en WebSocket-anslutning med en serverdelstjänst skickar det först en inledande handskakningsbegäran enligt WebSocket-protokollet. Varje WebSocket-API i API Management har en onHandshake-åtgärd. onHandshake är en oföränderlig, oåterkallelig, automatiskt skapad systemåtgärd. Med onHandshake-åtgärden kan API-utgivare fånga upp dessa handskakningsbegäranden och tillämpa API Management-principer på dem.

onHandshake screen example

Lägga till ett WebSocket-API

    1. I Azure-portalen går du till din API Management-instans.
  1. I den vänstra menyn väljer du API:er>+ Lägg till API.

  2. Under Definiera ett nytt API väljer du WebSocket.

  3. I dialogrutan väljer du Fullständig och slutför de obligatoriska formulärfälten.

    Fält Beskrivning
    Visningsnamn Namnet som webSocket-API:et ska visas med.
    Name Rånamn för WebSocket-API:et. Fylls i automatiskt när du skriver visningsnamnet.
    WebSocket URL Bas-URL:en med namnet på din websocket. Till exempel: ws://example.com/your-socket-name
    URL-schema Acceptera standardvärdet
    API:ets webbadressuffix Lägg till ett URL-suffix för att identifiera det här specifika API:et i den här API Management-instansen. Det måste vara unikt i den här APIM-instansen.
    Produkter Associera ditt WebSocket-API med en produkt för att publicera det.
    Gateways Associera ditt WebSocket-API med befintliga gatewayer.
  4. Klicka på Skapa.

Testa webSocket-API:et

  1. Gå till websocket-API:et.

  2. I webSocket-API:et väljer du åtgärden onHandshake.

  3. Välj fliken Test för att komma åt testkonsolen.

  4. Du kan också ange frågesträngsparametrar som krävs för webSocket-handskakningen.

    test API example

  5. Klicka på Anslut.

  6. Visa anslutningsstatus i Utdata.

  7. Ange värde i Nyttolast.

  8. Klicka på Skicka.

  9. Visa mottagna meddelanden i Utdata.

  10. Upprepa föregående steg för att testa olika nyttolaster.

  11. När testningen är klar väljer du Koppla från.

Visa mått och loggar

Använd standardfunktionerna API Management och Azure Monitor för att övervaka WebSocket-API:er:

  • Visa API-mått i Azure Monitor
  • Du kan också aktivera diagnostikinställningar för att samla in och visa API Management-gatewayloggar, som omfattar WebSocket API-åtgärder

Följande skärmbild visar till exempel de senaste svaren från WebSocket API med kod 101 från tabellen ApiManagementGatewayLogs . Dessa resultat indikerar att begäranden från TCP har växlats till WebSocket-protokollet.

Query logs for WebSocket API requests

Begränsningar

Nedan visas de aktuella begränsningarna för WebSocket-stöd i API Management:

  • WebSocket-API:er stöds inte ännu på förbrukningsnivån.
  • WebSocket-API:er stöder följande giltiga bufferttyper för meddelanden: Close, BinaryFragment, BinaryMessage, UTF8Fragment och UTF8Message.
  • För närvarande stöder inte principen för set-header att ändra vissa välkända rubriker, inklusive Host rubriker, i onHandshake-begäranden.
  • Under TLS-handskakningen med en WebSocket-serverdel verifierar API Management att servercertifikatet är betrott och att dess ämnesnamn matchar värdnamnet. Med HTTP-API:er verifierar API Management att certifikatet är betrott men validerar inte värdnamnet och ämnesmatchningen.

För Anslutningsgränser för WebSocket, se API Management-gränser.

Principer som inte stöds

Följande principer stöds inte av och kan inte tillämpas på onHandshake-åtgärden:

  • Mock-svar
  • Hämta från cache
  • Lagra till cache
  • Tillåt korsdomänanrop
  • CORS
  • JSONP
  • Ange metod för begäran
  • Ange brödtext
  • Konvertera XML till JSON
  • Konvertera JSON till XML
  • Transformera XML med XSLT
  • Verifiera innehåll
  • Verifiera parametrar
  • Verifiera rubriker
  • Verifiera statuskod

Kommentar

Om du tillämpade principerna i högre omfång (dvs. global eller produkt) och de ärvdes av ett WebSocket-API via principen, hoppas de över vid körning.

Nästa steg