Importare un'API WebSocket

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium

Con la soluzione API WebSocket di Gestione API, gli autori di API possono aggiungere rapidamente un'API WebSocket in Gestione API tramite portale di Azure, interfaccia della riga di comando di Azure, Azure PowerShell e altri strumenti di Azure.

È possibile proteggere le API WebSocket applicando criteri di controllo di accesso esistenti, ad esempio la convalida JWT. È anche possibile testare le API WebSocket usando le console di test dell'API sia in portale di Azure che nel portale per sviluppatori. Basandosi sulle funzionalità di osservabilità esistenti, Gestione API fornisce metriche e 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 all'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 Gestione API 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 Gestione API, che stabilisce quindi una connessione con i servizi back-end corrispondenti. Gestione API quindi esegue il proxy dei messaggi client-server WebSocket.

1. L'applicazione client invia una richiesta handshake WebSocket al gateway di Gestione API, richiamando l'operazione onHandshake.
2. Il gateway gestione API invia una richiesta handshake WebSocket al servizio back-end corrispondente.
3. Il servizio back-end aggiorna una connessione a WebSocket.
4. Il gateway gestione API aggiorna la connessione corrispondente a WebSocket.
5. Dopo aver stabilito la coppia di connessioni, Gestione API brokererà i messaggi tra l'applicazione client e il servizio back-end.
6. L'applicazione client invia un messaggio al gateway di Gestione API.
7. Il gateway gestione API inoltra il messaggio al servizio back-end.
8. Il servizio back-end invia un messaggio al gateway di Gestione API.
9. Il gateway gestione API inoltra il messaggio all'applicazione client.
10. Quando uno dei due lati 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, invia prima una richiesta di handshake di apertura. Ogni API WebSocket in Gestione API ha 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 queste richieste di handshake e di applicare criteri di Gestione API.

Aggiungere un'API WebSocket

Portale

1. 1. Nel portale di Azure accedere all'istanza di Gestione API.

2. Nel menu a sinistra selezionare API >+ Aggiungi API.

3. In Definisci una nuova API selezionare WebSocket.

4. Nella finestra di dialogo selezionare Completo e completare i campi modulo richiesti.

   Campo	Descrzione
   Display name	Nome in base al quale verrà visualizzata l'API WebSocket.
   Nome	Nome non elaborato dell'API WebSocket. Si popola automaticamente durante la digitazione del nome visualizzato.
   WebSocket URL	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 pubblicarla.
   Gateway	Associare l'API WebSocket ai gateway esistenti.

5. Fai clic su Crea.

Testare l'API WebSocket

1. Passare all'API WebSocket.

2. Nell'API WebSocket selezionare l'operazione onHandshake.

3. Selezionare la scheda Test per accedere alla console di test.

4. Facoltativamente, specificare i parametri della stringa di query necessari per l'handshake WebSocket.

   

5. Fare clic su Connetti.

6. Visualizzare lo stato della connessione in Output.

7. Immettere il valore in Payload.

8. Fare clic su Invia.

9. Visualizzare i messaggi ricevuti nell'output.

10. Ripetere i passaggi precedenti per testare payload diversi.

11. Al termine del test, selezionare Disconnetti.

Visualizzare metriche e log

Usare le funzionalità standard Gestione API e Monitoraggio di Azure per monitorare le API WebSocket:

• Visualizzare le metriche dell'API in Monitoraggio di Azure
• Facoltativamente, abilitare le impostazioni di diagnostica per raccogliere e visualizzare i log del gateway Gestione API, che includono operazioni API WebSocket

Ad esempio, lo screenshot seguente mostra le risposte recenti dell'API WebSocket con codice 101 della tabella ApiManagementGatewayLogs . Questi risultati indicano il passaggio corretto 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.
• Attualmente, il criterio set-header non supporta la modifica di determinate intestazioni note, incluse Host le intestazioni, 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 nome soggetto corrisponda al nome host. Con le API HTTP, Gestione API convalida che il certificato sia attendibile, ma non convalida la corrispondenza tra nome host e soggetto.

Per i limiti di connessione WebSocket, vedere limiti Gestione API.

Criteri non supportati

I criteri seguenti non sono supportati da e non possono essere applicati all'operazione onHandshake:

• Simulazione risposta
• Recupera dalla cache
• cache-lookup
• Permetti chiamate tra i domini
• CORS
• JSONP
• Impostare il metodo di richiesta
• Set body (Imposta corpo)
• Convert XML to JSON (Converti da XML a JSON)
• Convert JSON to XML (Converti da JSON a XML)
• Trasformare XML con XSLT
• Convalidare il contenuto
• Convalidare i parametri
• Convalidare le intestazioni
• Convalidare il codice di stato

Nota

Se i criteri sono stati applicati a 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 OData
• Importare metadati OData SAP
• Importare un'API gRPC
• Modificare un'API

Passaggi successivi

Trasformare e proteggere un'API pubblicata