업스트림 엔드포인트

아티클
03/10/2024

업스트림 엔드포인트 기능을 사용하면 Azure SignalR Service에서 서버리스 모드의 엔드포인트 세트에 메시지 및 연결 이벤트를 보낼 수 있습니다. 업스트림 엔드포인트를 사용하여 서버리스 모드로 클라이언트에서 허브 메서드를 호출하고 클라이언트 연결이 연결되거나 연결이 끊어지면 엔드포인트에 알릴 수 있습니다.

참고 항목

업스트림 엔드포인트는 서버리스 모드에서만 구성할 수 있습니다.

업스트림 엔드포인트 설정

업스트림 엔드포인트의 설정은 주문에 민감한 항목의 목록으로 구성됩니다.

메시지가 전송되는 위치를 지정하는 URL 템플릿.
규칙 집합.
인증 구성.

이벤트가 발생하는 경우 항목의 규칙을 순서대로 하나씩 확인합니다. 첫 번째로 일치하는 항목의 업스트림 엔드포인트 URL로 메시지를 보냅니다.

URL 템플릿 설정

업스트림 엔드포인트 URL을 매개 변수화하여 다양한 패턴을 지원할 수 있습니다. 이 트리거에는 다음과 같은 세 가지 미리 정의된 매개 변수가 있습니다.

미리 정의된 매개 변수	설명
{hub}	허브는 Azure SignalR Service의 개념입니다. 허브는 격리 단위입니다. 사용자의 범위와 메시지 배달은 허브로 제한됩니다.
{category}	범주는 다음 값 중 하나가 될 수 있습니다. 연결: 연결 수명 이벤트입니다. 클라이언트 연결이 연결되거나 끊어진 경우에 발생합니다. 연결된 이벤트와 연결이 끊어진 이벤트를 포함합니다. 메시지: 클라이언트에서 허브 메서드를 호출할 때 발생합니다. 연결 범주에 있는 이벤트를 제외한 다른 모든 이벤트가 포함됩니다.
{event}	메시지 범주의 경우 이벤트는 클라이언트에서 보내는 호출 메시지의 대상입니다. 연결 범주에는 연결됨 및 연결 끊김만 사용됩니다.

이러한 미리 정의된 매개 변수는 URL 패턴에서 사용할 수 있습니다. 업스트림 엔드포인트 URL을 평가하는 경우 매개 변수가 지정된 값으로 대체됩니다. 예시:

http://host.com/{hub}/api/{category}/{event}

"채팅" 허브의 클라이언트 연결이 연결되면 다음 URL로 메시지가 전송됩니다.

http://host.com/chat/api/connections/connected

"채팅" 허브의 클라이언트가 허브 메서드 broadcast을 호출하면 다음 URL로 메시지가 전송됩니다.

http://host.com/chat/api/messages/broadcast

URL 템플릿 설정에서 Key Vault 비밀 참조

업스트림 엔드포인트 URL은 암호화되지 않습니다. Key Vault를 사용하여 중요한 업스트림 엔드포인트를 보호하고 관리 ID로 액세스할 수 있습니다.

SignalR 서비스 인스턴스에서 관리 ID를 사용하도록 설정하고 Key Vault 액세스 권한을 부여하려면 다음을 수행합니다.

시스템 할당 ID 또는 사용자 할당 ID를 추가합니다. Azure Portal에서 관리 ID를 추가하는 방법을 참조하세요.
Key Vault의 액세스 정책에서 관리 ID에 대한 비밀 읽기 권한을 부여합니다. Azure Portal을 사용하여 Key Vault 액세스 정책 할당 참조
업스트림 엔드포인트 URL 패턴에서 중요한 텍스트를 아래 구문으로 바꿉니다.
```
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
```
<secret-identity>는 Key Vault에 있는 비밀의 전체 데이터 영역 URI이며 선택적으로 버전(예: https://myvault.vault.azure.net/secrets/mysecret/ 또는 https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931)을 포함합니다.

예를 들어 전체 참조는 다음과 같습니다.
```
{@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
```
Azure 함수에 대한 업스트림 엔드포인트 URL은 다음과 같습니다.
```
https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
```

참고 항목

서비스는 30분마다 또는 업스트림 설정이나 관리 ID가 변경될 때마다 비밀 콘텐츠를 다시 읽습니다. 업스트림 엔드포인트 설정을 변경하여 업데이트를 즉시 트리거할 수 있습니다.

규칙 설정

허브 규칙, 범주 규칙 및 이벤트 규칙을 별도로 설정할 수 있습니다. 일치 규칙은 세 가지 형식을 지원합니다.

임의의 이벤트를 일치시키려면 별표(*)를 사용합니다.
여러 이벤트에 조인하려면 쉼표(,)를 사용합니다. 예를 들어 connected, disconnected은 연결된 이벤트와 연결이 끊어진 이벤트를 일치시킵니다.
전체 이벤트 이름을 사용하여 이벤트와 일치시킵니다. 예를 들어 connected은 연결된 이벤트와 일치합니다.

참고 항목

SignalR trigger와 함께 Azure Functions를 사용하는 경우 SignalR 트리거는 <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY> 형식으로 단일 엔드포인트를 노출합니다. URL 템플릿 설정을 이 URL로 구성하고 규칙 설정을 기본값으로 유지할 수 있습니다. <Function_App_URL> 및 <API_KEY>에 대한 자세한 내용 및 방법은 SignalR Service 통합을 참조하세요.

인증 설정

각 업스트림 엔드포인트 설정에 대해 별도로 인증을 구성할 수 있습니다. 인증을 구성하면 업스트림 메시지의 Authentication 헤더에 토큰이 설정됩니다. 현재 Azure SignalR Service 다음 인증 유형을 지원합니다.

None
ManagedIdentity

ManagedIdentity를 선택하는 경우 Azure SignalR Service에서 관리 ID를 사용하도록 설정하고 필요에 따라 리소스를 지정해야 합니다. 자세한 내용은 Azure SignalR Service용 관리 ID를 참조하세요.

Azure Portal을 통해 업스트림 엔드포인트 설정 구성

참고 항목

App Service Environment와의 통합은 현재 지원되지 않습니다.

Azure SignalR Service로 이동.
설정을 선택합니다.
서비스 모드를 서버리스로 전환합니다.
업스트림 URL 패턴 아래에 URL을 추가합니다.
Hub 규칙을 선택하여 업스트림 설정을 엽니다.
해당 필드에 규칙 값을 입력하여 Hub 규칙, 이벤트 규칙 및 범주 규칙을 변경합니다.
업스트림 인증에서 선택
관리 ID를 사용합니다. (관리 ID를 사용하도록 설정했는지 확인)
발급된 토큰의 대상 그룹 아래에서 옵션을 선택합니다. 자세한 내용은 Azure SignalR Service용 관리 ID를 참조하세요.

Resource Manager 템플릿을 통해 업스트림 엔드포인트 설정 구성

Azure Resource Manager 템플릿을 사용하여 업스트림 엔드포인트 설정을 구성하려면 properties 속성에서 upstream 속성을 설정합니다. 다음 코드 조각은 업스트림 엔드포인트 설정을 만들고 업데이트하기 위한 upstream 속성을 설정하는 방법을 보여줍니다.

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

서버리스 프로토콜

Azure SignalR Service는 다음 프로토콜을 따르는 엔드포인트로 메시지를 보냅니다. 이러한 프로토콜을 처리하는 함수 앱에서 SignalR Service 트리거 바인딩을 사용할 수 있습니다.

메서드

게시

요청 헤더

이름	설명
X ASRS-연결-Id	클라이언트 연결에 대한 연결 ID입니다.
X ASRS-허브	클라이언트 연결이 속한 허브입니다.
X ASRS-카테고리	메시지가 속한 범주입니다.
X ASRS-이벤트	메시지가 속한 이벤트입니다.
X ASRS-서명	유효성 검사에 사용되는 HMAC(해시 기반 메시지 인증 코드)입니다. 자세한 내용은 서명을 참조하십시오.
X ASRS-사용자-클레임	클라이언트 연결의 클레임 그룹입니다.
X ASRS-사용자-Id	메시지를 보내는 클라이언트의 사용자 ID입니다.
X ASRS-클라이언트-쿼리	클라이언트가 서비스에 연결하는 경우 요청에 대한 쿼리입니다.
인증	`ManagedIdentity`을 사용하는 경우 선택적 토큰입니다.

요청 본문

연결됨

Content-Type: application/json

연결 끊김

Content-Type: application/json

이름	형식	설명
오류	string	닫힌 연결에 대한 오류 메시지입니다. 연결이 오류 없이 닫히면 비어 있습니다.

호출 메시지

Content-Type: application/json 또는 application/x-msgpack

이름	형식	설명
InvocationId	string	호출 메시지를 나타내는 선택적 문자열입니다. 호출에서 세부 정보를 찾습니다.
대상	string	이벤트와 동일하고 호출 메시지의 대상과 동일합니다.
인수	개체의 배열	`Target`에서 참조되는 메서드에 적용할 인수를 포함하는 배열입니다.

서명

서비스는 X-ASRS-Connection-Id 기본 액세스 키와 보조 액세스 키를 키로 사용하여 값에 대한 HMAC SHA256 코드를 계산합니다. 서비스는 업스트림 엔드포인트에 대한 HTTP 요청을 수행할 때 X-ASRS-Signature 헤더에 설정합니다.

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

업스트림 엔드포인트

업스트림 엔드포인트 설정

URL 템플릿 설정

URL 템플릿 설정에서 Key Vault 비밀 참조

규칙 설정

인증 설정

Azure Portal을 통해 업스트림 엔드포인트 설정 구성

Resource Manager 템플릿을 통해 업스트림 엔드포인트 설정 구성

서버리스 프로토콜

메서드

요청 헤더

요청 본문

연결됨

연결 끊김

호출 메시지

서명

다음 단계

추가 리소스