다음을 통해 공유

Azure SignalR Service 데이터 평면 REST API 참조

  • 아티클

클래식 클라이언트/서버 패턴 외에도 Azure SignalR Service는 실시간 기능을 서버리스 아키텍처에 통합하는 데 도움이 되는 REST API 집합을 제공합니다.

참고 항목

Azure SignalR Service는 REST API만 사용하여 ASP.NET Core SignalR을 통해 연결된 클라이언트를 관리하도록 지원합니다. ASP.NET SignalR을 통해 연결된 클라이언트는 현재 지원되지 않는 다른 데이터 프로토콜을 사용합니다.

Azure Functions를 사용하는 일반적인 서버리스 아키텍처

다음 다이어그램에서는 Azure Functions와 함께 Azure SignalR Service를 사용하는 일반적인 서버리스 아키텍처를 보여 줍니다.

Azure SignalR Service에 대한 일반적인 서버리스 아키텍처 다이어그램

  • 이 함수는 negotiate 협상 응답을 반환하고 모든 클라이언트를 Azure SignalR Service로 리디렉션합니다.
  • 이 함수는 broadcast Azure SignalR Service용 REST API를 호출합니다. Azure SignalR Service는 연결된 모든 클라이언트에 메시지를 브로드캐스트합니다.

서버리스 아키텍처에서 클라이언트는 Azure SignalR Service에 대한 영구 연결을 갖습니다. 트래픽을 처리할 애플리케이션 서버가 없으므로 클라이언트는 모드에 LISTEN 있습니다. 이 모드에서 클라이언트는 메시지를 받을 수 있지만 메시지를 보낼 수는 없습니다. Azure SignalR Service는 잘못된 작업이므로 메시지를 보내는 모든 클라이언트의 연결을 끊습니다.

이 GitHub 리포지토리에서 Azure Functions와 함께 Azure SignalR Service를 사용하는 전체 샘플을 찾을 수 있습니다.

협상 엔드포인트 구현

클라이언트가 negotiate 서비스에 연결할 수 있도록 리디렉션 협상 응답을 반환하는 함수를 구현해야 합니다.

일반적인 협상 응답 형식은 다음과 같습니다.

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

accessToken 이 값은 인증 섹션에 설명된 것과 동일한 알고리즘을 통해 생성됩니다. 유일한 차이점은 클레임이 aud 같아야 한다는 것입니다 url.

SignalR 클라이언트를 사용하여 허브 URL에 https://<hub_url>/negotiate 연결할 수 있도록 협상 API를 호스트해야 합니다. 클라이언트 연결에서 Azure SignalR Service로 클라이언트를 리디렉션하는 방법에 대해 자세히 알아보세요.

REST API 버전

다음 표에서는 지원되는 모든 REST API 버전을 보여 줍니다. 또한 각 API 버전에 대한 Swagger 파일을 제공합니다.

API 버전 상태 포트 설명서 규격
20220601 가장 늦은 날짜 Standard 아티클 Swagger 파일
1.0 안정 Standard 아티클 Swagger 파일
1.0-preview 사용되지 않음 Standard 아티클 Swagger 파일

다음 표에서는 사용 가능한 API를 나열합니다.

API Path
대상 허브에 연결된 모든 클라이언트에 메시지 브로드캐스트 POST /api/v1/hubs/{hub}
대상 사용자에 속한 모든 클라이언트에 메시지 브로드캐스트 POST /api/v1/hubs/{hub}/users/{id}
특정 연결에 메시지 보내기 POST /api/v1/hubs/{hub}/connections/{connectionId}
지정된 connectionId와의 연결이 있는지 확인합니다. GET /api/v1/hubs/{hub}/connections/{connectionId}
클라이언트 연결을 닫습니다. DELETE /api/v1/hubs/{hub}/connections/{connectionId}
대상 그룹 내의 모든 클라이언트에 메시지 브로드캐스트 POST /api/v1/hubs/{hub}/groups/{group}
지정된 그룹 내에 클라이언트 연결이 있는지 확인합니다. GET /api/v1/hubs/{hub}/groups/{group}
지정된 사용자에 대해 연결된 클라이언트 연결이 있는지 확인합니다. GET /api/v1/hubs/{hub}/users/{user}
대상 그룹에 연결 추가 PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
대상 그룹에서 연결 제거 DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
사용자가 대상 그룹에 있는지 확인 GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
대상 그룹에 사용자 추가 PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
대상 그룹에서 사용자 제거 DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
모든 그룹에서 사용자 제거 DELETE /api/v1/hubs/{hub}/users/{user}/groups

REST API 사용

Azure SignalR Service에서 AccessKey를 통한 인증

각 HTTP 요청에서 JWT(JSON Web Token)가 있는 권한 부여 헤더는 Azure SignalR Service를 사용하여 인증해야 합니다.

서명 알고리즘 및 서명

HS256, 즉 HMAC-SHA256이 서명 알고리즘으로 사용됩니다.

AccessKey Azure SignalR Service 인스턴스의 연결 문자열 값을 사용하여 생성된 JWT에 서명합니다.

클레임

다음 클레임은 JWT에 포함되어야 합니다.

클레임 유형 필수 설명
aud true 후행 슬래시 및 쿼리 매개 변수를 포함하지 않고 HTTP 요청 URL과 동일해야 합니다. 예를 들어 브로드캐스트 요청의 대상 그룹은 https://example.service.signalr.net/api/v1/hubs/myhub와 같습니다.
exp true 이 토큰이 만료되는 Epoch 시간입니다.

Microsoft Entra 토큰을 통한 인증

Microsoft Entra 토큰을 AccessKey사용하여 HTTP 요청을 인증하려면 JWT가 필요합니다.

차이점은 이 시나리오에서 Microsoft Entra ID가 JWT를 생성한다는 것입니다. 자세한 내용은 Microsoft Entra 토큰을 생성하는 방법을 참조하세요.

사용되는 자격 증명 범위는 https://signalr.azure.com/.default이어야 합니다.

RBAC(역할 기반 액세스 제어)를 사용하여 클라이언트 또는 서버에서 Azure SignalR Service로의 요청에 권한을 부여할 수도 있습니다. 자세한 내용은 Azure SignalR Service용 Microsoft Entra ID를 사용하여 액세스 권한 부여를 참조 하세요.

사용자 관련 REST API를 호출하려면 각 클라이언트가 Azure SignalR Service에 자신을 식별해야 합니다. 그렇지 않으면 Azure SignalR Service가 사용자 ID에서 대상 연결을 찾을 수 없습니다.

Azure SignalR Service에 연결할 때 각 클라이언트의 JWT에 클레임을 포함하여 nameid 클라이언트 식별을 달성할 수 있습니다. 그런 다음 Azure SignalR Service는 클레임 값을 nameid 각 클라이언트 연결의 사용자 ID로 사용합니다.

Sample

이 GitHub 리포지토리에서 Azure SignalR Service에서 REST API HTTP 요청을 수동으로 빌드하는 방법을 보여 주는 전체 콘솔 앱을 찾을 수 있습니다.

Microsoft.Azure.SignalR.Management를 사용하여 유사한 인터페이스를 사용하여 Azure SignalR Service에 메시지를 게시할 수도 있습니다IHubContext. 이 GitHub 리포지토리에서 샘플을 찾을 수 있습니다. 자세한 내용은 Azure SignalR Service Management SDK를 참조 하세요.

제한 사항

현재 REST API 요청에는 다음과 같은 제한 사항이 있습니다.

  • 헤더 크기는 최대 16KB입니다.
  • 본문 크기는 최대 1MB입니다.

1MB보다 큰 메시지를 보내려면 모드에서 서비스 관리 SDK를 persistent 사용합니다.