Importowanie interfejsu API protokołu WebSocket

DOTYCZY: Developer | Podstawowa | Podstawowa wersja 2 | Standardowa | Standardowa, wersja 2 | Premium

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

Interfejsy API protokołu WebSocket można zabezpieczyć, stosując istniejące zasady kontroli dostępu, takie jak walidacja JWT. 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:

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

Wymagania wstępne

• Istniejące wystąpienie usługi API Management. Utwórz go, jeśli jeszcze tego nie zrobiono.
• Interfejs API protokołu WebSocket.
• Interfejs wiersza polecenia platformy Azure

Przekazywanie protokołu WebSocket

Usługa API Management obsługuje przekazywanie protokołu 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 serwery proxy Komunikaty protokołu WebSocket client-server.

1. Aplikacja kliencka wysyła żądanie uzgadniania protokołu WebSocket do bramy usługi APIM, wywołując operację onHandshake.
2. Brama usługi APIM wysyła żądanie uzgadniania protokołu WebSocket do odpowiedniej usługi zaplecza.
3. Usługa zaplecza uaktualnia połączenie z usługą WebSocket.
4. Brama usługi APIM uaktualnia odpowiednie połączenie z aplikacją WebSocket.
5. Po ustanowieniu pary połączeń usługa APIM będzie obsługiwać komunikaty między aplikacją kliencka a usługą zaplecza.
6. Aplikacja kliencka wysyła komunikat do bramy usługi APIM.
7. Brama usługi APIM przekazuje komunikat do usługi zaplecza.
8. Usługa zaplecza wysyła komunikat do bramy usługi APIM.
9. Brama usługi APIM przekazuje komunikat do aplikacji klienckiej.
10. Po rozłączeniu obu stron usługa APIM przerywa odpowiednie połączenie.

Uwaga

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

onHandshake, operacja

Na protokół WebSocket, gdy aplikacja kliencka próbuje ustanowić połączenie protokołu WebSocket z usługą zaplecza, najpierw wyśle żądanie uzgadniania otwierającego. Każdy interfejs API protokołu WebSocket w usłudze API Management ma operację onHandshake. onHandshake to niezmienna, niezmienialna, automatycznie utworzona operacja systemowa. Operacja onHandshake umożliwia wydawcom interfejsów API przechwytywanie tych żądań uzgadniania i stosowanie do nich zasad usługi API Management.

Dodawanie interfejsu API protokołu WebSocket

Portal

1. 1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.

2. W menu po lewej stronie wybierz pozycję Interfejsy> API+ Dodaj interfejs API.

3. W obszarze Definiowanie nowego interfejsu API wybierz pozycję WebSocket.

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

   Pole	opis
   Display name	Nazwa, za pomocą której zostanie wyświetlony interfejs API protokołu WebSocket.
   Nazwisko	Nieprzetworzona nazwa interfejsu API protokołu WebSocket. Automatycznie wypełniana podczas wpisywania nazwy wyświetlanej.
   WebSocket URL	Podstawowy adres URL z nazwą protokołu websocket. 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 ona być unikatowa w tym wystąpieniu usługi APIM.
   Produkty	Skojarz interfejs API protokołu WebSocket z produktem, aby go opublikować.
   Bramy	Skojarz interfejs API protokołu WebSocket z istniejącymi bramami.

5. Kliknij pozycję Utwórz.

Testowanie interfejsu API protokołu WebSocket

1. Przejdź do interfejsu API protokołu WebSocket.

2. W interfejsie API protokołu WebSocket wybierz operację onHandshake.

3. Wybierz kartę Test, aby uzyskać dostęp do konsoli testowej.

4. Opcjonalnie podaj parametry ciągu zapytania wymagane do uzgadniania protokołu WebSocket.

   

5. Kliknij Połącz.

6. Wyświetl stan połączenia w danych wyjściowych.

7. Wprowadź wartość w ładunku.

8. Kliknij opcję Wyślij.

9. Wyświetl odebrane komunikaty w danych wyjściowych.

10. Powtórz powyższe kroki, aby przetestować różne ładunki.

11. Po zakończeniu testowania wybierz pozycję Rozłącz.

Wyświetlanie metryk i dzienników

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

• Wyświetlanie metryk interfejsu API w usłudze Azure Monitor
• Opcjonalnie włącz ustawienia diagnostyczne, aby zbierać i wyświetlać dzienniki bramy usługi API Management, które obejmują operacje interfejsu API protokołu 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ą pomyślny przełącznik żądań z protokołu TCP do protokołu WebSocket.

Ograniczenia

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

• Interfejsy API protokołu WebSocket nie są jeszcze obsługiwane w warstwie Zużycie.
• Interfejsy API protokołu WebSocket obsługują następujące prawidłowe typy buforów dla komunikatów: Close, BinaryFragment, BinaryMessage, UTF8Fragment i UTF8Message.
• Obecnie zasady set-header nie obsługują zmiany niektórych dobrze znanych nagłówków, w tym Host nagłówków, w żądaniach onHandshake.
• Podczas uzgadniania protokołu TLS z zapleczem protokołu WebSocket usługa API Management sprawdza, czy certyfikat serwera jest zaufany i czy jego nazwa podmiotu jest zgodna z nazwą hosta. Za pomocą interfejsów API PROTOKOŁU HTTP usługa API Management sprawdza, czy certyfikat jest zaufany, ale nie sprawdza, czy nazwa hosta i temat są zgodne.

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 operację onHandshake i nie można ich zastosować:

• Pozorna odpowiedź
• Pobieranie z pamięci podręcznej
• Przechowywanie w pamięci podręcznej
• Zezwalaj na wywołania między domenami
• CORS
• JSONP
• Ustawianie metody żądania
• Ustaw treść
• 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 zasady zostały zastosowane w wyższych zakresach (tj. globalnym lub produkcie) i zostały odziedziczone przez interfejs API protokołu WebSocket za pośrednictwem zasad, zostaną pominięte w czasie wykonywania.

Powiązane tematy

• Ograniczenia importu interfejsu API
• Importowanie specyfikacji interfejsu OpenAPI
• Importowanie interfejsu API SOAP
• Importowanie interfejsu API SOAP i konwertowanie go na interfejs API REST
• Importowanie interfejsu API usługi App Service
• Importowanie interfejsu API aplikacji kontenera
• Importowanie interfejsu API protokołu WebSocket
• Importowanie interfejsu GraphQL API
• Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól
• Importowanie aplikacji funkcji platformy Azure
• Importowanie usługi Azure Logic App
• Importowanie usługi Service Fabric
• Importowanie interfejsu API usługi Azure OpenAI
• Importowanie interfejsu API OData
• Importowanie metadanych sap OData
• Importowanie interfejsu API gRPC
• Edytowanie interfejsu API

Następne kroki

Przekształcanie i ochrona opublikowanego interfejsu API