Azure API Management에서 Azure SignalR Service를 사용하는 방법

아티클
12/31/2024

Azure API Management 서비스는 모든 환경에서 API를 위한 하이브리드 다중 클라우드 관리 플랫폼을 제공합니다. 이 문서에서는 Azure API Management 및 Azure SignalR Service를 사용하여 애플리케이션에 실시간 기능을 추가하는 방법을 보여 줍니다.

API Management에서 SignalR Service를 사용하는 아키텍처를 보여 주는 다이어그램

Important

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다.

연결 문자열 애플리케이션이 Azure SignalR Service에 액세스하는 데 필요한 권한 부여 정보를 포함합니다. 연결 문자열 내의 액세스 키는 서비스의 루트 암호와 비슷합니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호하고 Microsoft Entra ID 로 액세스 권한을 부여합니다.

액세스 키를 다른 사용자에게 배포하거나 하드 코딩하거나 다른 사용자가 액세스할 수 있는 일반 텍스트로 저장하지 않도록 합니다. 키가 손상되었다고 생각되면 키를 교체하세요.

리소스 만들기

빠른 시작: ARM 템플릿을 사용하여 Azure SignalR을 배포에 따라 SignalR Service 인스턴스 ASRS1을 만듭니다.
빠른 시작: ARM 템플릿을 사용하여 Azure API Management 배포에 따라 API Management 인스턴스 APIM1을 만듭니다.

API 구성

제한 사항

SignalR 클라이언트에 대해 다음과 같은 두 가지 유형의 요청이 있습니다.

협상 요청: <APIM-URL>/client/negotiate/에 대한 HTTP POST 요청
연결 요청: <APIM-URL>/client/에 대한 요청으로, WebSocket일 수 있으며 ServerSentEvent 또는 LongPolling은 SignalR 클라이언트의 전송 유형에 따라 다릅니다.

연결 요청 유형은 SignalR 클라이언트의 전송 유형에 따라 달라집니다. 현재 API Management는 아직 동일한 접미사에 대해 다른 유형의 API를 지원하지 않습니다. 이 제한 때문에 API Management를 사용하는 경우 SignalR 클라이언트는 WebSocket 전송 형식에서 다른 전송 형식으로 대체하는 것을 지원하지 않습니다. ServerSentEvent에서 LongPolling으로 대체하는 것은 지원될 수 있습니다. 아래 섹션에서는 다양한 전송 유형에 대한 자세한 구성을 설명합니다.

클라이언트가 `WebSocket` 전송에 연결할 때 API 구성

이 섹션에서는 SignalR 클라이언트가 WebSocket 전송을 통해 연결할 때 API Management를 구성하는 단계를 설명합니다. SignalR 클라이언트가 WebSocket 전송을 통해 연결되면 세 가지 유형의 요청이 진행됩니다.

OPTIONS: 협상에 대한 실행 전 HTTP 요청
POST: 협상에 대한 HTTP 요청
연결에 대한 WebSocket 요청

포털에서 API Management를 구성해 보겠습니다.

API Management 인스턴스 APIM1에 대한 포털의 API 탭으로 이동하여 API 추가를 선택하고 다음 매개 변수를 지정하여 HTTP, 만들기를 선택합니다.
- 표시 이름: SignalR negotiate
- 웹 서비스 URL: https://<your-signalr-service-url>/client/negotiate/
- API URL 접미사: client/negotiate/
만든 SignalR negotiate API를 선택하고 아래 설정을 사용하여 저장합니다.
1. 디자인 탭에서
  1. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: negotiate preflight
    - URL: OPTIONS /
  2. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: negotiate
    - URL: POST /
2. 설정 탭으로 전환하고 빠른 데모를 위해 구독 필요를 선택 취소합니다.
API 추가를 선택하고 WebSocket을 선택한 후 다음 매개 변수를 지정하여 만들기를 선택합니다.
- 표시 이름: SignalR connect
- WebSocket URL: wss://<your-signalr-service-url>/client/
- API URL 접미사: client/
만든 SignalR connect API를 선택하고 아래 설정을 사용하여 저장합니다.
1. 설정 탭으로 전환하고 빠른 데모를 위해 구독 필요를 선택 취소합니다.

이제 WebSocket 전송을 사용하여 SignalR 클라이언트를 지원하도록 API Management가 성공적으로 구성되었습니다.

클라이언트가 `ServerSentEvents` 또는 `LongPolling` 전송을 통해 연결할 때 API 구성

이 섹션에서는 SignalR 클라이언트가 ServerSentEvents 또는 LongPolling 전송 유형을 통해 연결할 때 API Management를 구성하는 단계를 설명합니다. SignalR 클라이언트가 ServerSentEvents 또는 LongPolling 전송을 통해 연결하는 경우 다음과 같은 5가지 유형의 요청이 진행됩니다.

OPTIONS: 협상에 대한 실행 전 HTTP 요청
POST: 협상에 대한 HTTP 요청
OPTIONS: 연결에 대한 실행 전 HTTP 요청
POST: 연결에 대한 HTTP 요청
GET: 연결에 대한 HTTP 요청

이제 포털에서 API Management를 구성해 보겠습니다.

API Management 인스턴스 APIM1에 대한 포털의 API 탭으로 이동하여 API 추가를 선택하고 다음 매개 변수를 지정하여 HTTP, 만들기를 선택합니다.
- 표시 이름: SignalR
- 웹 서비스 URL: https://<your-signalr-service-url>/client/
- API URL 접미사: client/
만든 SignalR API를 선택하고 아래 설정을 사용하여 저장합니다.
1. 디자인 탭에서
  1. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: negotiate preflight
    - URL: OPTIONS /negotiate
  2. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: negotiate
    - URL: POST /negotiate
  3. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: connect preflight
    - URL: OPTIONS /
  4. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: connect
    - URL: POST /
  5. 작업 추가를 선택하고 다음 매개 변수를 사용하여 저장합니다.
    - 표시 이름: connect get
    - URL: GET /
  6. 새로 추가된 연결 가져오기 작업을 선택하고 백 엔드 정책을 편집하여 ServerSentEvents에 대한 버퍼링을 사용하지 않도록 설정합니다. 자세한 내용은 여기를 확인하세요.
```
<backend>
    <forward-request buffer-response="false" />
</backend>
```
2. 설정 탭으로 전환하고 빠른 데모를 위해 구독 필요를 선택 취소합니다.

이제 ServerSentEvents 또는 LongPolling 전송을 사용하여 SignalR 클라이언트를 지원하도록 API Management가 성공적으로 구성되었습니다.

채팅 실행

이제 트래픽이 API Management를 통해 SignalR Service에 도달할 수 있습니다. 이 채팅 애플리케이션을 예로 들어 보겠습니다. 먼저 로컬로 실행해 보겠습니다.

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호하고 Microsoft Entra ID 로 액세스 권한을 부여합니다.

먼저 ASRS1의 연결 문자열을 가져옵니다.
- ASRS1의 연결 문자열 탭에서
  - 클라이언트 엔드포인트: APIM1의 게이트웨이 URL을 사용하여 URL을 입력합니다(예: https://apim1.azure-api.net). 이는 역방향 프록시를 사용할 때 연결 문자열 생성기이며, 다음에 이 탭으로 돌아올 때까지 값이 유지되지 않습니다. 값을 입력하면 연결 문자열이 ClientEndpoint 섹션을 추가합니다.
  - 연결 문자열 복사
GitHub 리포지토리(https://github.com/aspnet/AzureSignalR-samples)를 복제합니다.
samples/Chatroom 폴더로 이동합니다.
복사한 연결 문자열을 설정하고 로컬에서 애플리케이션을 실행하면 ConnectionString에 ClientEndpoint 섹션이 있음을 확인할 수 있습니다.
```
cd samples/Chatroom
dotnet restore
dotnet user-secrets set Azure:SignalR:ConnectionString "<copied-connection-string-with-client-endpoint>"
dotnet run
```
클라이언트에 대한 전송 유형 구성

폴더 wwwroot 아래에서 index.html을 열고, connection을 만들 때 해당 코드를 찾아서 전송 유형을 지정하도록 업데이트합니다.

예를 들어 server-sent-events 또는 긴 폴링을 사용할 연결을 지정하려면 코드를 다음으로 업데이트합니다.
```
const connection = new signalR.HubConnectionBuilder()
  .withUrl(
    "/chat",
    signalR.HttpTransportType.ServerSentEvents |
      signalR.HttpTransportType.LongPolling
  )
  .build();
```
WebSocket을 사용할 연결을 지정하려면 코드를 다음으로 업데이트합니다.
```
const connection = new signalR.HubConnectionBuilder()
  .withUrl("/chat", signalR.HttpTransportType.WebSockets)
  .build();
```
브라우저에서 http://localhost:5000을 열고 F12 키를 사용하여 네트워크 추적을 확인합니다. APIM1을 통해 연결이 설정된 것을 볼 수 있습니다.

다음 단계

이제 Azure SignalR을 사용하여 API Management에 실시간 기능을 성공적으로 추가했습니다. SignalR Service에 대한 자세한 정보

다음을 통해 공유

Azure API Management에서 Azure SignalR Service를 사용하는 방법

리소스 만들기

API 구성

제한 사항

클라이언트가 `WebSocket` 전송에 연결할 때 API 구성

클라이언트가 `ServerSentEvents` 또는 `LongPolling` 전송을 통해 연결할 때 API 구성

채팅 실행

다음 단계

피드백

추가 리소스

다음을 통해 공유

Azure API Management에서 Azure SignalR Service를 사용하는 방법

리소스 만들기

API 구성

제한 사항

클라이언트가 WebSocket 전송에 연결할 때 API 구성

클라이언트가 ServerSentEvents 또는 LongPolling 전송을 통해 연결할 때 API 구성

채팅 실행

다음 단계

피드백

추가 리소스

클라이언트가 `WebSocket` 전송에 연결할 때 API 구성

클라이언트가 `ServerSentEvents` 또는 `LongPolling` 전송을 통해 연결할 때 API 구성