WebSocket API 가져오기

  • 아티클

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄

API Management의 WebSocket API 솔루션을 사용하면 API 게시자는 Azure Portal, Azure CLI, Azure PowerShell 및 기타 Azure 도구를 통해 API Management에서 WebSocket API를 빠르게 추가할 수 있습니다.

참고 항목

현재 이 기능은 작업 영역에서 사용할 수 없습니다.

JWT 유효성 검사와 같은 기존 액세스 제어 정책을 적용하여 WebSocket API를 보호할 수 있습니다. Azure Portal 및 개발자 포털 모두에서 API 테스트 콘솔을 사용하여 WebSocket API를 테스트할 수도 있습니다. 기존 가시성 기능을 기반으로 하는 API Management는 WebSocket API 모니터링과 문제 해결을 위한 메트릭 및 로그를 제공합니다.

이 문서에서는 다음에 대해 알아봅니다.

  • Websocket 통과 흐름을 이해합니다.
  • API Management 인스턴스에 WebSocket API를 추가합니다.
  • WebSocket API를 테스트합니다.
  • WebSocket API에 대한 메트릭 및 로그를 봅니다.
  • WebSocket API의 제한에 대해 알아봅니다.

필수 조건

  • 기존 API Management 인스턴스. 구독이 아직 없다면 하나를 만듭니다.
  • WebSocket API.
  • Azure CLI

WebSocket 통과

API Management는 WebSocket 통과를 지원합니다.

WebSocket 통과 흐름의 시각 자료

WebSocket 통과 중에 클라이언트 애플리케이션은 API Management 게이트웨이와 WebSocket 연결을 설정합니다. 그러면 해당 백 엔드 서비스와의 연결이 설정됩니다. 그런 다음 API Management는 WebSocket 클라이언트-서버 메시지를 프록시합니다.

  1. 클라이언트 애플리케이션은 OnHandshake 작업을 호출하여 APIM 게이트웨이에 WebSocket 핸드셰이크 요청을 보냅니다.
  2. APIM 게이트웨이는 해당 백 엔드 서비스에 WebSocket 핸드셰이크 요청을 보냅니다.
  3. 백 엔드 서비스는 WebSocket에 대한 연결을 업그레이드합니다.
  4. APIM 게이트웨이는 해당하는 연결을 WebSocket으로 업그레이드합니다.
  5. 연결 쌍이 설정되면, APIM은 클라이언트 애플리케이션과 백 엔드 서비스 간에 메시지를 중개합니다.
  6. 클라이언트 애플리케이션이 APIM 게이트웨이로 메시지를 보냅니다.
  7. APIM 게이트웨이가 메시지를 백 엔드 서비스로 전달합니다.
  8. 백 엔드 서비스에서 APIM 게이트웨이로 메시지를 보냅니다.
  9. APIM 게이트웨이가 메시지를 클라이언트 애플리케이션으로 전달합니다.
  10. 양쪽 연결이 끊어지면 APIM은 해당 연결을 종료합니다.

참고 항목

클라이언트 쪽 및 백 엔드 쪽 연결은 일 대 일 매핑으로 구성됩니다.

onHandshake 작업

Websocket 프로토콜마다, 클라이언트 애플리케이션은 백 엔드 서비스와 WebSocket 연결을 설정하려고 할 때 먼저 핸드셰이크 요청 열기를 보냅니다. API Management의 각 WebSocket API에는 onHandshake 작업이 있습니다. onHandshake는 변경할 수 없고 제거할 수 없는, 자동으로 생성된 시스템 작업입니다. onHandshake 작업을 통해 API 게시자는 이러한 핸드셰이크 요청을 가로채 API Management 정책을 적용할 수 있습니다.

onHandshake 화면 예제

WebSocket API 추가

    1. Azure Portal에서 API Management 인스턴스로 이동합니다.

  2. 왼쪽 메뉴에서 API>+ API 추가를 선택합니다.

  3. 새 API 정의에서 WebSocket을 선택합니다.

  4. 대화 상자에서 전체를 선택하고 필요한 양식 필드를 작성합니다.

    필드 Description
    표시 이름 WebSocket API가 표시되는 이름입니다.
    이름 WebSocket API의 원시 이름입니다. 표시 이름을 입력하면 자동으로 채워집니다.
    WebSocket URL websocket 이름을 가진 기본 URL입니다. 예: ws://example.com/your-socket-name
    URL 구성표 기본값을 그대로 적용
    API URL 접미사 URL 접미사를 추가하여 이 API Management 인스턴스에서 이 API를 식별합니다. 이 APIM 인스턴스 내에서 고유해야 합니다.
    제품 WebSocket API를 제품과 연결하여 게시합니다.
    게이트웨이 WebSocket API를 기존 게이트웨이와 연결합니다.

  5. 만들기를 클릭합니다.

WebSocket API 테스트

  1. WebSocket API로 이동합니다.

  2. WebSocket API 내에서 onHandshake 작업을 선택합니다.

  3. 테스트 탭을 선택하여 테스트 콘솔에 액세스합니다.

  4. 필요에 따라 WebSocket 핸드셰이크에 필요한 쿼리 문자열 매개 변수를 제공합니다.

    테스트 API 예제

  5. 연결을 클릭합니다.

  6. 출력에서 연결 상태를 봅니다.

  7. 페이로드에 값을 입력합니다.

  8. 보내기를 클릭합니다.

  9. 출력에서 수신된 메시지를 봅니다.

  10. 이전 단계를 반복하여 다른 페이로드를 테스트합니다.

  11. 테스트가 완료되면 연결 끊기를 선택합니다.

메트릭 및 로그 보기

표준 API Management 및 Azure Monitor 기능을 사용하여 WebSocket API를 모니터링합니다.

  • Azure Monitor의 API 메트릭 보기
  • 선택 사항으로, 진단 설정을 사용하도록 설정하여 WebSocket API 작업을 포함하는 API Management 게이트웨이 로그를 수집 및 확인

예를 들어 다음 스크린샷에서는 ApiManagementGatewayLogs 테이블의 코드 101을 사용하는 최신 WebSocket API 리소스를 확인할 수 있습니다. 이러한 결과는 요청이 TCP에서 WebSocket 프로토콜로 성공적으로 전환되었음을 나타냅니다.

WebSocket API 요청에 대한 쿼리 로그

제한 사항

다음은 API Management의 WebSocket 지원의 현재 제한 사항입니다.

  • WebSocket API는 아직 사용량 계층에서 지원되지 않습니다.
  • WebSocket API는 Close, BinaryFragment, BinaryMessage, UTF8Fragment 및 UTF8Message와 같은 메시지에 대해 유효한 버퍼 형식을 지원합니다.
  • 현재 집합 헤더 정책은 onHandshake 요청에서 Host 헤더를 포함하여 잘 알려진 특정 헤더 변경을 지원하지 않습니다.
  • WebSocket 백 엔드와의 TLS 핸드셰이크 중에 API Management는 서버 인증서가 신뢰할 수 있고 해당 주체 이름이 호스트 이름과 일치하는지 유효성을 검사합니다. HTTP API를 사용하여 API Management는 인증서가 신뢰할 수 있는지 유효성을 검사하지만 해당 호스트 이름과 제목 일치는 유효성 검사하지 않습니다.

WebSocket 연결 제한은 API Management 제한을 참조하세요.

지원되지 않는 정책

다음 정책은 지원되지 않으며 onHandshake 작업에 적용할 수 없습니다.

  • 모의 응답
  • 캐시에서 가져오기
  • 캐시에 저장
  • 도메인 간 호출 허용
  • CORS
  • JSONP
  • 요청 메서드 설정
  • 본문 설정
  • XML을 JSON으로 변환
  • JSON을 XML로 변환
  • XSLT를 사용하여 XML 변환
  • 콘텐츠 유효성 검사
  • 매개 변수 유효성 검사
  • 헤더 유효성 검사
  • 상태 코드 유효성 검사

참고 항목

더 높은 범위(즉, 전체 또는 제품)에서 정책을 적용하고 정책을 통해 WebSocket API에 상속된 경우 런타임에서 건너뜁니다.

다음 단계

게시된 API 변환 및 보호