Delen via

Een WebSocket-API importeren

VAN TOEPASSING OP: Ontwikkelaar | Basic | Basic v2 | Standaard | Standard v2 | Premium | Premium v2

Met de WebSocket-API-oplossing van API Management kunnen API-uitgevers snel een WebSocket-API toevoegen in API Management via Azure Portal, Azure CLI, Azure PowerShell en andere Azure-hulpprogramma's.

WebSocket-API's kunnen worden beveiligd door het toegangsbeheerbeleid van API Management toe te passen op de eerste handshake-bewerking. U kunt webSocket-API's ook testen met behulp van de API-testconsoles in zowel de Azure-portal als de ontwikkelaarsportal. Api Management bouwt voort op bestaande waarneembaarheidsmogelijkheden en biedt metrische gegevens en logboeken voor het bewaken en oplossen van problemen met WebSocket-API's.

In dit artikel leert u het volgende:

  • Begrijp de WebSocket-doorstroom.
  • Voeg een WebSocket-API toe aan uw API Management-exemplaar.
  • Test uw WebSocket-API.
  • Bekijk de metrische gegevens en logboeken voor uw WebSocket-API.
  • Meer informatie over de beperkingen van WebSocket-API.

Vereiste voorwaarden

WebSocket passthrough

API Management ondersteunt WebSocket Passthrough.

Visuele illustratie van de Passthrough-stroom van WebSocket

Tijdens de WebSocket-passthrough brengt de clienttoepassing een WebSocket-verbinding tot stand met de API Management-gateway, die vervolgens een verbinding tot stand brengt met de bijbehorende back-endservices. API Management proxyt vervolgens WebSocket client-server berichten.

  1. De clienttoepassing verzendt een WebSocket-handshake-aanvraag naar de gateway, die de onHandshake-bewerking aanroept
  2. De API Management-gateway past geconfigureerd beleid toe en verzendt WebSocket-handshake-aanvragen naar de bijbehorende back-endservice.
  3. De back-endservice werkt een verbinding met WebSocket bij.
  4. De gateway werkt de bijbehorende verbinding met WebSocket bij.
  5. Nadat het verbindingspaar tot stand is gebracht, bemiddelt API Management berichten tussen de clienttoepassing en de back-endservice.
  6. De clienttoepassing verzendt een bericht naar de gateway.
  7. De gateway stuurt het bericht door naar de back-endservice.
  8. De back-endservice verzendt een bericht naar de gateway.
  9. De gateway stuurt het bericht door naar de clienttoepassing.
  10. Wanneer de verbinding met een van beide zijden wordt verbroken, beëindigt API Management de bijbehorende verbinding.

Notitie

De verbindingen aan de client- en back-endzijde bestaan uit een-op-een-toewijzing.

onHandshake-actie

Wanneer een clienttoepassing probeert een WebSocket-verbinding tot stand te brengen met een back-endservice, wordt volgens het WebSocket-protocol eerst een open handshake-aanvraag verzonden. Elke WebSocket-API in API Management heeft een onHandshake-bewerking. onHandshake is een onveranderbare, onverwijdbare, automatisch gemaakte systeembewerking. Met de onHandshake-bewerking kunnen API-uitgevers deze handshake-aanvragen onderscheppen en API Management-beleid hierop toepassen.

voorbeeld van onHandshake-scherm

Een WebSocket-API toevoegen

    1. Blader in Azure Portal naar uw API Management-exemplaar.

  2. Selecteer API's>+ API toevoegen in het linkermenu.

  3. Selecteer WebSocket onder Een nieuwe API definiëren.

  4. Selecteer in het dialoogvenster Volledig en vul de vereiste formuliervelden in.

    Veld Omschrijving
    Weergavenaam De naam waarmee uw WebSocket-API wordt weergegeven.
    Naam Onbewerkte naam van de WebSocket-API. Wordt automatisch ingevuld terwijl u de weergavenaam typt.
    WebSocket-URL De basis-URL met de naam van uw websocket. Bijvoorbeeld: ws://example.com/your-socket-name
    URL-schema De standaardwaarde accepteren
    API-URL-achtervoegsel Voeg een URL-achtervoegsel toe om deze specifieke API in dit API Management-exemplaar te identificeren. Het moet uniek zijn in dit API Management-exemplaar.
    Producten Koppel uw WebSocket-API aan een product om deze te publiceren.
    Toegangspoorten Koppel uw WebSocket-API aan bestaande gateways.

  5. Klik op Create.

Uw WebSocket-API testen

  1. Navigeer naar uw WebSocket-API.

  2. Selecteer in uw WebSocket-API de onHandshake-bewerking.

  3. Selecteer het tabblad Testen om toegang te krijgen tot de testconsole.

  4. Geef desgewenst queryreeksparameters op die vereist zijn voor de WebSocket-handshake.

    voorbeeld van test-API

  5. Klik op Verbinding maken.

  6. De verbindingsstatus weergeven in Uitvoer.

  7. Voer de waarde in Payload in.

  8. Klik op Verzenden.

  9. Ontvangen berichten weergeven in Uitvoer.

  10. Herhaal de voorgaande stappen om verschillende payloads te testen.

  11. Wanneer het testen is voltooid, selecteert u Verbinding verbreken.

Metrische gegevens en logboeken weergeven

Gebruik standaard-API Management- en Azure Monitor-functies om WebSocket-API's te bewaken :

  • Metrische API-gegevens weergeven in Azure Monitor
  • Schakel optioneel diagnostische instellingen in om API Management-gatewaylogboeken te verzamelen en weer te geven, waaronder WebSocket-API-bewerkingen of WebSocket-verbindingslogboeken

In de volgende schermopname ziet u bijvoorbeeld recente WebSocket-API-antwoorden met code 101 uit de tabel ApiManagementGatewayLogs . Deze resultaten geven de geslaagde switch aan van de aanvragen van TCP naar het WebSocket-protocol.

Querylogs voor WebSocket-API-aanvragen

Beperkingen

Hier volgen de huidige beperkingen van WebSocket-ondersteuning in API Management:

  • WebSocket-API's worden in de Consumptielaag nog niet ondersteund.
  • WebSocket-API's ondersteunen de volgende geldige buffertypen voor berichten: Sluiten, BinaryFragment, BinaryMessage, UTF8Fragment en UTF8Message.
  • Op dit moment biedt het beleid voor set-headers geen ondersteuning voor het wijzigen van bepaalde bekende headers, inclusief Host headers, in onHandshake-aanvragen.
  • Tijdens de TLS-handshake met een WebSocket-back-end valideert API Management dat het servercertificaat wordt vertrouwd en of de onderwerpnaam overeenkomt met de hostnaam. Met HTTP-API's valideert API Management dat het certificaat wordt vertrouwd, maar wordt niet gevalideerd of de hostnaam en het onderwerp overeenkomen.

Zie API Management-limieten voor WebSocket-verbindingen.

Niet ondersteund beleid

Het volgende beleid wordt niet ondersteund en kan niet worden toegepast op de onHandshake-bewerking:

  • Gesimuleerd antwoord
  • Ophalen uit cache
  • Opslaan in cache
  • Aanroepen tussen domeinen toestaan
  • CORS (Cross-Origin Resource Sharing)
  • JSONP
  • Aanvraagmethode instellen
  • Hoofdtekst instellen
  • XML converteren naar JSON
  • JSON converteren naar XML
  • XML transformeren met XSLT
  • Inhoud valideren
  • Parameters valideren
  • Kopteksten valideren
  • Statuscode valideren

Notitie

Als u het beleid hebt toegepast op hogere niveaus (bijvoorbeeld globale of productniveau) en ze worden overgenomen door een WebSocket-API via het beleid, worden ze tijdens de uitvoertijd overgeslagen.

Gerelateerde inhoud