Een WebSocket-API importeren

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

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.

U kunt WebSocket-API's beveiligen door bestaand beleid voor toegangsbeheer toe te passen, zoals JWT-validatie. 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:

• Informatie over de passthroughstroom van Websocket.
• 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.

Vereisten

• Een bestaand API Management-exemplaar. Maak er een als u dat nog niet hebt gedaan.
• Een WebSocket-API.
• Azure-CLI

WebSocket passthrough

API Management ondersteunt WebSocket Passthrough.

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 proxy's vervolgens WebSocket-client-serverberichten.

1. De clienttoepassing verzendt een WebSocket-handshake-aanvraag naar de APIM-gateway, die onHandshake-bewerking aanroept.
2. APIM-gateway verzendt een WebSocket-handshake-aanvraag naar de bijbehorende back-endservice.
3. De back-endservice werkt een verbinding met WebSocket bij.
4. APIM-gateway werkt de bijbehorende verbinding met WebSocket bij.
5. Zodra het verbindingspaar tot stand is gebracht, zorgt APIM voor brokerberichten tussen de clienttoepassing en de back-endservice.
6. De clienttoepassing verzendt een bericht naar de APIM-gateway.
7. APIM-gateway stuurt het bericht door naar de back-endservice.
8. De back-endservice verzendt een bericht naar de APIM-gateway.
9. APIM-gateway stuurt het bericht door naar de clienttoepassing.
10. Wanneer de verbinding met een van beide zijden wordt verbroken, beëindigt APIM de bijbehorende verbinding.

Notitie

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

onHandshake-bewerking

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.

Een WebSocket-API toevoegen

Portal

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

2. Selecteer API's+ API's> 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
   Display name	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. Hij moet uniek zijn in dit APIM-exemplaar.
   Producten	Koppel uw WebSocket-API aan een product om deze te publiceren.
   Gateways	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.

   

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 nettoladingen 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

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.

Beperkingen

Hieronder ziet u de huidige beperkingen van WebSocket-ondersteuning in API Management:

• WebSocket-API's worden nog niet ondersteund in de laag Verbruik.
• 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

De volgende beleidsregels worden niet ondersteund en kunnen niet worden toegepast op de onHandshake-bewerking:

• Gesimuleerd antwoord
• Ophalen uit cache
• Opslaan in cache
• Aanroepen tussen domeinen toestaan
• CORS
• 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 bereiken (bijvoorbeeld globaal of product) en ze zijn overgenomen door een WebSocket-API via het beleid, worden ze tijdens runtime overgeslagen.

Verwante onderwerpen

• Beperkingen bij het importeren van API's
• Een OpenAPI-specificatie importeren
• Een SOAP-API importeren
• Een SOAP-API importeren en deze converteren naar REST
• Een App Service-API importeren
• Een Container App-API importeren
• Een WebSocket-API importeren
• Een GraphQL-API importeren
• Een GraphQL-schema importeren en veldoplossers instellen
• Een Azure-functie-app importeren
• Een logische Azure-app importeren
• Een Service Fabric-service importeren
• Een OData-API importeren
• SAP OData-metagegevens importeren
• Een gRPC-API importeren
• Een API bewerken

Volgende stappen

Een gepubliceerde API transformeren en beveiligen