Skip to content

Files

Latest commit

mikeurnunmikeurnun
(Azure CXP) typo fix
Apr 19, 2022
650bffc · Apr 19, 2022

History

History
145 lines (109 loc) · 7.12 KB

websocket-api.md

File metadata and controls

145 lines (109 loc) · 7.12 KB
title titleSuffix description ms.service author ms.author ms.topic ms.date ms.custom
Import a WebSocket API using the Azure portal | Microsoft Docs
Learn how API Management supports WebSocket, add a WebSocket API, and WebSocket limitations.
api-management
dlepow
danlep
how-to
11/2/2021
template-how-to, ignite-fall-2021

Import a WebSocket API

With API Management’s WebSocket API solution, you can now manage, protect, observe, and expose both WebSocket and REST APIs with API Management and provide a central hub for discovering and consuming all APIs. API publishers can quickly add a WebSocket API in API Management via:

  • A simple gesture in the Azure portal, and
  • The Management API and Azure Resource Manager.

You can secure WebSocket APIs by applying existing access control policies, like JWT validation. You can also test WebSocket APIs using the API test consoles in both Azure portal and developer portal. Building on existing observability capabilities, API Management provides metrics and logs for monitoring and troubleshooting WebSocket APIs.

In this article, you will:

[!div class="checklist"]

  • Understand Websocket passthrough flow.
  • Add a WebSocket API to your API Management instance.
  • Test your WebSocket API.
  • View the metrics and logs for your WebSocket API.
  • Learn the limitations of WebSocket API.

Prerequisites

WebSocket passthrough

API Management supports WebSocket passthrough.

:::image type="content" source="./media/websocket-api/websocket-api-passthrough.png" alt-text="Visual illustration of WebSocket passthrough flow":::

During the WebSocket passthrough the client application establishes a WebSocket connection with the API Management Gateway, which then establishes a connection with the corresponding backend services. API Management then proxies WebSocket client-server messages.

  1. The client application sends a WebSocket handshake request to APIM gateway, invoking onHandshake operation.
  2. APIM gateway sends WebSocket handshake request to the corresponding backend service.
  3. The backend service upgrades a connection to WebSocket.
  4. APIM gateway upgrades the corresponding connection to WebSocket.
  5. Once the connection pair is established, APIM will broker messages back and forth between the client application and backend service.
  6. The client application sends message to APIM gateway.
  7. APIM gateway forwards the message to the backend service.
  8. The backend service sends a message to APIM gateway.
  9. APIM gateway forwards the message to the client application.
  10. When either side disconnects, APIM terminates the corresponding connection.

Note

The client-side and backend-side connections consist of one-to-one mapping.

onHandshake operation

Per the WebSocket protocol, when a client application tries to establish a WebSocket connection with a backend service, it will first send an opening handshake request. Each WebSocket API in API Management has an onHandshake operation. onHandshake is an immutable, unremovable, automatically created system operation. The onHandshake operation enables API publishers to intercept these handshake requests and apply API Management policies to them.

:::image type="content" source="./media/websocket-api/onhandshake-screen.png" alt-text="onHandshake screen example":::

Add a WebSocket API

  1. Navigate to your API Management instance.

  2. From the side navigation menu, under the APIs section, select APIs.

  3. Under Define a new API, select the WebSocket icon.

  4. In the dialog box, select Full and complete the required form fields.

    Field Description
    Display name The name by which your WebSocket API will be displayed.
    Name Raw name of the WebSocket API. Automatically populates as you type the display name.
    WebSocket URL The base URL with your websocket name. For example: ws://example.com/your-socket-name
    URL scheme Accept the default
    API URL suffix Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this APIM instance.
    Products Associate your WebSocket API with a product to publish it.
    Gateways Associate your WebSocket API with existing gateways.

  5. Click Create.

Test your WebSocket API

  1. Navigate to your WebSocket API.

  2. Within your WebSocket API, select the onHandshake operation.

  3. Select the Test tab to access the Test console.

  4. Optionally, provide query string parameters required for the WebSocket handshake.

    :::image type="content" source="./media/websocket-api/test-websocket-api.png" alt-text="test API example":::

  5. Click Connect.

  6. View connection status in Output.

  7. Enter value in Payload.

  8. Click Send.

  9. View received messages in Output.

  10. Repeat preceding steps to test different payloads.

  11. When testing is complete, select Disconnect.

View metrics and logs

Use standard API Management and Azure Monitor features to monitor WebSocket APIs:

  • View API metrics in Azure Monitor
  • Optionally enable diagnostic settings to collect and view API Management gateway logs, which include WebSocket API operations

For example, the following screenshot shows recent WebSocket API responses with code 101 from the ApiManagementGatewayLogs table. These results indicate the successful switch of the requests from TCP to the WebSocket protocol.

:::image type="content" source="./media/websocket-api/query-gateway-logs.png" alt-text="Query logs for WebSocket API requests":::

Limitations

Below are the current restrictions of WebSocket support in API Management:

  • WebSocket APIs are not supported yet in the Consumption tier.
  • WebSocket APIs are not supported yet in the self-hosted gateway.
  • Azure CLI, PowerShell, and SDK currently do not support management operations of WebSocket APIs.
  • 200 active connections limit per unit.
  • Websockets APIs support the following valid buffer types for messages: Close, BinaryFragment, BinaryMessage, UTF8Fragment, and UTF8Message.

Unsupported policies

The following policies are not supported by and cannot be applied to the onHandshake operation:

  • Mock response
  • Get from cache
  • Store to cache
  • Allow cross-domain calls
  • CORS
  • JSONP
  • Set request method
  • Set body
  • Convert XML to JSON
  • Convert JSON to XML
  • Transform XML using XSLT
  • Validate content
  • Validate parameters
  • Validate headers
  • Validate status code

Note

If you applied the policies at higher scopes (i.e., global or product) and they were inherited by a WebSocket API through the policy, they will be skipped at run time.

[!INCLUDE api-management-define-api-topics.md]

Next steps

[!div class="nextstepaction"] Transform and protect a published API