Importare un'API WebSocket
SI APPLICA A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium
Con la soluzione API WebSocket di Gestione API, gli editori di API possono aggiungere rapidamente un'API WebSocket a Gestione API tramite il portale di Azure, l'interfaccia della riga di comando di Azure, Azure PowerShell e altri strumenti di Azure.
Nota
Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.
È possibile proteggere le API WebSocket applicando criteri di controllo degli accessi esistenti, ad esempio convalida JWT. È anche possibile testare le API WebSocket con le console di test delle API sia nel portale di Azure che nel portale per sviluppatori. Basandosi sulle funzionalità di osservabilità esistenti, Gestione API fornisce le metriche e i log per il monitoraggio e la risoluzione dei problemi delle API WebSocket.
Contenuto dell'articolo:
- Informazioni sul flusso pass-through Websocket
- Aggiungere un'API WebSocket nella propria istanza di Gestione API.
- Testare l'API WebSocket.
- Visualizzare le metriche e i log per l'API WebSocket.
- Informazioni sulle limitazioni dell'API WebSocket.
Prerequisiti
- Un'istanza di API Management esistente. Crearne una se non è già stato fatto.
- API WebSocket.
- Interfaccia della riga di comando di Azure
Pass-through WebSocket
Gestione API supporta il pass-through WebSocket.
Durante il pass-through WebSocket l'applicazione client stabilisce una connessione WebSocket con il gateway di Gestione API, che stabilisce quindi una connessione con i servizi back-end corrispondenti. Gestione API quindi esegue il proxy dei messaggi client-server WebSocket.
- L'applicazione client invia una richiesta handshake WebSocket al gateway di Gestione API, richiamando l'operazione onHandshake.
- Il gateway di Gestione API invia una richiesta handshake WebSocket al servizio back-end corrispondente.
- Il servizio back-end aggiorna una connessione in WebSocket.
- Il gateway di Gestione API aggiorna la connessione corrispondente in WebSocket.
- Dopo aver stabilito la coppia di connessioni, Gestione API gestirà la coda broker dei messaggi tra l'applicazione client e il servizio back-end.
- L'applicazione client invia un messaggio al Gateway di Gestione API.
- Il gateway di Gestione API inoltra il messaggio al servizio back-end.
- Il servizio back-end invia un messaggio al gateway di Gestione API.
- Il gateway di Gestione API inoltra il messaggio all'applicazione client.
- Quando una delle due parti si disconnette, Gestione API termina la connessione corrispondente.
Nota
Le connessioni lato client e back-end sono costituite da mapping uno a uno.
Operazione onHandshake
In base al protocollo WebSocket, quando un'applicazione client tenta di stabilire una connessione WebSocket con un servizio back-end, invierà prima un richiesta di handshake di apertura. Ogni API WebSocket in Gestione API dispone di un'operazione onHandshake. onHandshake è un'operazione di sistema non modificabile, non rimovibile e creata automaticamente. L'operazione onHandshake consente agli editori dell'API di intercettare le richieste di handshake e di applicare criteri di Gestione API.
Aggiungere un'API WebSocket
-
- Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra, selezionare API >+ Aggiungi API.
In Definisci nuova API, selezionare WebSocket.
Nella finestra di dialogo, selezionare Completo e completare i campi modulo richiesti.
Campo Descrzione Display name Nome con cui verrà visualizzata l'API WebSocket. Nome Nome non elaborato dell'API WebSocket. Si popola automaticamente durante la digitazione del nome visualizzato. URL WebSocket URL di base con il nome Websocket. Ad esempio: ws://example.com/your-socket-name Schema URL Accettare l'impostazione predefinita Suffisso dell'URL dell'API Aggiungere un suffisso URL per identificare l’API specifica in questa istanza di Gestione API. Deve essere univoco nell'istanza di Gestione API. Prodotti Associare l'API WebSocket a un prodotto per pubblicarlo. Gateway Associare l'API WebSocket a gateway esistenti. Fai clic su Crea.
Testare l'API WebSocket
Passare all'API WebSocket.
Nell'API WebSocket, selezionare l'operazione onHandshake.
Selezionare la scheda Test per accedere alla console di test.
In modo facoltativo, specificare i parametri della stringa di query necessari per l'handshake WebSocket.
Fare clic su Connetti.
Visualizzare lo stato della connessione in Output.
Inserire il valore Payload.
Fare clic su Invia.
Visualizzare i messaggi ricevuti in Output.
Ripetere i passaggi precedenti per testare altri payload.
Quando il test è completo, selezionare Disconnetti.
Visualizzare metriche e log
Usare le funzionalità standard di Gestione API e Monitoraggio di Azure per monitorare le API WebSocket:
- Visualizzare le metriche dell'API in Monitoraggio di Azure
- In modo facoltativo, abilitare le impostazioni di diagnostica per raccogliere e visualizzare i log del gateway di Gestione API, che includono le operazioni API WebSocket
Ad esempio, lo screenshot seguente mostra le risposte dell'API WebSocket recenti con codice 101 dalla tabella ApiManagementGatewayLogs. Questi risultati indicano il completamento del passaggio delle richieste da TCP al protocollo WebSocket.
Limiti
Di seguito sono riportate le restrizioni correnti del supporto WebSocket in Gestione API:
- Le API WebSocket non sono ancora supportate nel livello A consumo.
- Le API WebSocket supportano i tipi di buffer validi seguenti per i messaggi: Close, BinaryFragment, BinaryMessage, UTF8Fragment e UTF8Message.
- Al momento, il criterio set-header non supporta la modifica di determinate intestazioni note, incluse le intestazioni
Host, nelle richieste onHandshake. - Durante l'handshake TLS con un back-end WebSocket, Gestione API verifica che il certificato del server sia attendibile e che il relativo nome soggetto corrisponda al nome host. Con le API HTTP, Gestione API verifica che il certificato sia attendibile ma non convalida la corrispondenza tra nome host e soggetto.
Per i limiti di connessione WebSocket, vedere limiti di Gestione API.
Criteri non supportati
I criteri seguenti non sono supportati dall'operazione onHandshakee e non possono esservi applicati:
- Simulazione risposta
- Recupera dalla cache
- cache-lookup
- Permetti chiamate tra i domini
- CORS
- JSONP
- set-request-method
- Set body (Imposta corpo)
- Convert XML to JSON (Converti da XML a JSON)
- Convert JSON to XML (Converti da JSON a XML)
- Trasforma XML usando XSLT
- Convalidare il contenuto
- Convalidare i parametri
- Convalidare le intestazioni
- Convalidare il codice di stato
Nota
Se i criteri sono stati applicati ad ambiti più elevati (ad esempio globali o prodotti) e sono stati ereditati da un'API WebSocket tramite i criteri, verranno ignorati in fase di esecuzione.
Argomenti correlati
- Limitazioni relative all'importazione di API
- Importare una specifica OpenAPI
- Importare un'API SOAP
- Importare un'API SOAP e convertirla in REST
- Importare un'API del servizio app
- Importare un'API dell'app contenitore
- Importare un'API WebSocket
- Importare un'API GraphQL
- Importare uno schema di GraphQL e configurare resolver di campo
- Importare un'app per le funzioni di Azure
- Importare un'app per la logica di Azure
- Importare un servizio Service Fabric
- Importare un'API di OpenAI di Azure
- Importare un'API OData
- Importare metadati OData SAP
- Importare un'API gRPC
- Modificare un'API