Importowanie interfejsu API protokołu WebSocket

2025-05-20

Dzięki rozwiązaniu API WebSocket usługi API Management wydawcy interfejsu API mogą szybko dodawać interfejs API WebSocket w usłudze API Management za pośrednictwem portalu Azure, interfejsu wiersza polecenia Azure, programu Azure PowerShell i innych narzędzi Azure.

Interfejsy API protokołu WebSocket można zabezpieczyć, stosując zasady kontroli dostępu usługi API Management do początkowej operacji uzgadniania. Możesz również przetestować interfejsy API protokołu WebSocket przy użyciu konsol testowych interfejsu API zarówno w witrynie Azure Portal, jak i w portalu dla deweloperów. Korzystając z istniejących możliwości obserwacji, usługa API Management udostępnia metryki i dzienniki na potrzeby monitorowania i rozwiązywania problemów z interfejsami API protokołu WebSocket.

W tym artykule dowiesz się:

Omówienie przepływu przekazywania protokołu WebSocket.
Dodaj interfejs API protokołu WebSocket do wystąpienia usługi API Management.
Przetestuj API WebSocket.
Wyświetl metryki i dzienniki dla interfejsu WebSocket API.
Poznaj ograniczenia interfejsu API protokołu WebSocket.

Wymagania wstępne

Istniejąca instancja API Management. Utwórz go, jeśli jeszcze tego nie zrobiono.
API WebSocket.
Interfejs wiersza polecenia platformy Azure

Przekazywanie protokołu WebSocket

Usługa API Management obsługuje przechodzenie przez protokół WebSocket.

Wizualizacja przepływu przekazowego WebSocket

Podczas przekazywania protokołu WebSocket aplikacja kliencka ustanawia połączenie protokołu WebSocket z bramą usługi API Management, która następnie nawiązuje połączenie z odpowiednimi usługami zaplecza. Usługa API Management następnie pośredniczy w komunikacji klient-serwer za pośrednictwem protokołu WebSocket.

Aplikacja kliencka wysyła żądanie handshake WebSocket do bramy, wywołując operację onHandshake.
Bramka zarządzania API stosuje skonfigurowane zasady i wysyła żądania uzgadniania protokołu WebSocket do odpowiedniej usługi backendowej.
Usługa zaplecza uaktualnia połączenie z usługą WebSocket.
Brama uaktualnia odpowiednie połączenie do protokołu WebSocket.
Po ustanowieniu połączenia, API Management pośredniczy w wymianie komunikatów tam i z powrotem między aplikacją kliencką a usługą zaplecza.
Aplikacja kliencka wysyła komunikat do bramy.
Brama przekazuje komunikat do usługi zaplecza.
Usługa zaplecza wysyła komunikat do bramy.
Brama przekazuje komunikat do aplikacji klienckiej.
Po rozłączeniu obu stron usługa API Management kończy odpowiednie połączenie.

Uwaga

Połączenia po stronie klienta i serwera składają się z mapowania jeden do jednego.

operacja onHandshake

Zgodnie z protokołem WebSocket, gdy aplikacja kliencka próbuje ustanowić połączenie WebSocket z serwerem zaplecza, najpierw wysyła żądanie otwierającego uścisku dłoni. Każdy interfejs WebSocket API w usłudze API Management ma operację onHandshake. onHandshake to niezmienna, niezmienialna, automatycznie utworzona operacja systemowa. Operacja onHandshake umożliwia wydawcom API przechwytywanie tych żądań uzgadniania i stosowanie zasad zarządzania API do nich.

przykład ekranu onHandshake

Dodawanie interfejsu API protokołu WebSocket

Portal

1. W portalu Azure przejdź do instancji usługi Zarządzanie API.
W menu po lewej stronie wybierz API>+ Dodaj API.
W obszarze Definiowanie nowego interfejsu API wybierz pozycję WebSocket.

W oknie dialogowym wybierz pozycję Pełne i wypełnij wymagane pola formularza.

Pole	opis
Nazwa wyświetlana	Nazwa, pod którą wyświetlany jest twój interfejs API WebSocket.
Nazwisko	Nazwa bazowa interfejsu API protokołu WebSocket. Automatycznie wypełniana podczas wpisywania nazwy wyświetlanej.
WebSocket URL	Podstawowy adres URL z nazwą twojego websocketu. Na przykład: ws://example.com/your-socket-name
Schemat adresu URL	Zaakceptuj wartość domyślną
Sufiks adresu URL interfejsu API	Dodaj sufiks adresu URL, aby zidentyfikować ten konkretny interfejs API w tym wystąpieniu usługi API Management. Musi być unikatowa w tej instancji API Management.
Produkty	Skojarz API WebSocket z produktem, aby je opublikować.
Bramki	Połącz interfejs API protokołu WebSocket z istniejącymi bramami.

Kliknij pozycję Utwórz.

Przetestuj API WebSocket

Przejdź do API WebSocket.
W interfejsie API protokołu WebSocket wybierz operację onHandshake.
Wybierz kartę Test, aby uzyskać dostęp do konsoli testowej.
Opcjonalnie podaj parametry ciągu zapytania wymagane do uzgadniania protokołu WebSocket.
Kliknij Połącz.
Wyświetl stan połączenia w danych wyjściowych.
Wprowadź wartość w Payload.
Kliknij opcję Wyślij.
Wyświetl odebrane komunikaty w danych wyjściowych.
Powtórz powyższe kroki, aby przetestować różne ładunki.
Po zakończeniu testowania wybierz pozycję Rozłącz.

Wyświetl metryki i dzienniki

Używanie standardowych funkcji usługi API Management i usługi Azure Monitor do monitorowania interfejsów API protokołu WebSocket:

Wyświetlanie metryk API w usłudze Azure Monitor
Opcjonalnie włącz ustawienia diagnostyczne, aby zbierać i wyświetlać logi bramy zarządzania API, które obejmują operacje WebSocket API lub logi połączeń WebSocket.

Na przykład poniższy zrzut ekranu przedstawia ostatnie odpowiedzi interfejsu API protokołu WebSocket z kodem 101 z tabeli ApiManagementGatewayLogs. Te wyniki wskazują na pomyślne przełączenie żądań z protokołu TCP do protokołu WebSocket.

Dzienniki zapytań dotyczących interfejsu WebSocket API

Ograniczenia

Poniżej przedstawiono bieżące ograniczenia obsługi protokołu WebSocket w usłudze API Management:

API WebSocket nie są jeszcze obsługiwane w warstwie konsumpcyjnej.
Interfejsy API protokołu WebSocket obsługują następujące dozwolone typy buforów dla komunikatów: Close, BinaryFragment, BinaryMessage, UTF8Fragment i UTF8Message.
Obecnie polityka set-header nie obsługuje zmiany niektórych dobrze znanych nagłówków, w tym także nagłówków takich jak Host, w żądaniach onHandshake.
Podczas nawiązywania połączenia TLS z backendem WebSocket, API Management sprawdza, czy certyfikat serwera jest zaufany i czy jego nazwa podmiotu jest zgodna z nazwą hosta. Za pomocą interfejsów API HTTP usługa API Management sprawdza, czy certyfikat jest zaufany, ale nie sprawdza zgodności nazwy hosta i podmiotu.

Aby uzyskać informacje o limitach połączeń protokołu WebSocket, zobacz Limity usługi API Management.

Nieobsługiwane zasady

Następujące zasady nie są obsługiwane przez program i nie można ich zastosować do operacji onHandshake:

Symulowana odpowiedź
Pobierz z pamięci podręcznej
Zapisz w pamięci podręcznej
Zezwalaj na wywołania między domenami
CORS (Cross-Origin Resource Sharing)
JSONP
Ustawianie metody żądania
Ustaw tekst
Konwertuj format XML na JSON
Konwertuj format JSON na XML
Przekształcanie kodu XML przy użyciu języka XSLT
Weryfikowanie zawartości
Weryfikowanie parametrów
Weryfikowanie nagłówków
Weryfikowanie kodu stanu

Uwaga

Jeśli zostały zastosowane zasady na wyższych poziomach (na przykład globalnym lub produktowym) i są one dziedziczone przez interfejs API WebSocket poprzez te zasady, to w czasie wykonywania są pominięte.

Udostępnij za pośrednictwem