Condividi tramite

Importare un'API WebSocket

  • Articolo

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.

È 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 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.

Illustrazione visiva del flusso 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.

  1. L'applicazione client invia una richiesta handshake WebSocket al gateway di Gestione API, richiamando l'operazione onHandshake.
  2. Il gateway di Gestione API invia una richiesta handshake WebSocket al servizio back-end corrispondente.
  3. Il servizio back-end aggiorna una connessione in WebSocket.
  4. Il gateway di Gestione API aggiorna la connessione corrispondente in WebSocket.
  5. Dopo aver stabilito la coppia di connessioni, Gestione API gestirà la coda broker dei 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 di 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 di Gestione API inoltra il messaggio all'applicazione client.
  10. 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.

Esempio di schermata onHandshake

Aggiungere un'API WebSocket

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

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

  3. In Definisci nuova API, selezionare WebSocket.

  4. 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.

  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. In modo facoltativo, specificare i parametri della stringa di query necessari per l'handshake WebSocket.

    Esempio di API di test

  5. Fare clic su Connetti.

  6. Visualizzare lo stato della connessione in Output.

  7. Inserire il valore Payload.

  8. Fare clic su Invia.

  9. Visualizzare i messaggi ricevuti in Output.

  10. Ripetere i passaggi precedenti per testare altri payload.

  11. 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.

Eseguire query sui log per le richieste API 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.

Passaggi successivi

Trasformare e proteggere un'API pubblicata