Dela via

Importera ett WebSocket-API

GÄLLER FÖR: Utvecklare | Grundläggande | Basic v2 | Standard | Standard v2 | Premium | Premium v2

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

WebSocket-API:er kan skyddas genom att tillämpa API Managements åtkomstkontrollprinciper på den första handskakningsåtgärden. Du kan också testa WebSocket-API:er med hjälp av API-testkonsolerna i både Azure Portal- 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

  • En befintlig API Management-instans. Skapa en om du inte redan har gjort det.
  • Ett WebSocket-API.
  • Azure CLI (kommandoradsgränssnittet för Azure)

WebSocket-genomströmning

API Management stöder WebSocket-genomströmning.

Visuell bild av webSocket-genomströmningsflöde

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

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

Anteckning

Klient- och backend-anslutningarna består av en-till-en-mappning.

onHandshake-funktion

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-skärmexempel

Lägga till ett WebSocket-API

    1. I Azure Portal navigerar du till din API Management-instans.

  2. I den vänstra menyn väljer du API:er>+ Lägg till API.

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

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

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

  5. 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-exempel

  5. Klicka på Anslut.

  6. Visa anslutningsstatus i Utdata.

  7. Ange värde i Payload.

  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 eller WebSocket-anslutningsloggar

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.

Frågeloggar för WebSocket API-begäranden

Begränsningar

Följande är 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 ett WebSocket-backend verifierar API Management att servercertifikatet är betrott och att dess subjectnamn 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:

  • Testsvar
  • Hämta från cache
  • Lagra till cache
  • Tillåt korsdomänanrop
  • CORS (Cross-Origin Resource Sharing)
  • JSONP
  • Ange metod för begäran
  • Ställ in kropp
  • Konvertera XML till JSON
  • Konvertera JSON till XML
  • Transformera XML med XSLT
  • Verifiera innehåll
  • Verifiera parametrar
  • Verifiera rubriker
  • Verifiera statuskod

Anteckning

Om du tillämpade principerna på högre nivåer (till exempel global eller produkt) och dessa principer ärvdes av ett WebSocket-API genom principmekanismen, hoppas de över vid körning.

Relaterat innehåll