Azure Functions에 대한 Azure Web PubSub 트리거 및 바인딩

이 참조에서는 Azure Functions에서 Web PubSub 이벤트를 처리하는 방법을 설명합니다.

Web PubSub는 개발자가 실시간 기능 및 게시-구독 패턴을 사용하여 웹 애플리케이션을 쉽게 빌드할 수 있도록 도와주는 Azure 관리형 서비스입니다.

작업	Type
서비스에서 메시지가 제공되는 경우 함수 실행	트리거 바인딩
협상 및 업스트림 요청을 위해 Http 트리거에서 대상 개체에 요청을 바인딩합니다.	입력 바인딩
서비스 실행 작업 호출	출력 바인딩

소스 코드 | 패키지 | API 참조 설명서 | 제품 설명서 | 샘플

Functions 앱 추가

트리거 및 바인딩을 사용하려면 적절한 패키지를 참조해야 합니다. NuGet 패키지는 .NET 클래스 라이브러리에 사용되는 반면, 확장 번들은 다른 모든 애플리케이션 형식에 사용됩니다.

언어	추가 방법...	설명
C#	NuGet 패키지, 시험판 버전 설치
C# 스크립트, JavaScript, Python, PowerShell	확장을 명시적으로 설치, 확장 번들 사용	Azure Tools 확장은 Visual Studio Code와 함께 사용하는 것이 좋습니다.
C# 스크립트(Azure Portal에서 온라인으로만)	바인딩 추가	함수 앱을 다시 게시하지 않고 기존 바인딩 확장을 업데이트하려면 확장 업데이트를 참조하세요.

주요 개념

(1)-(2) 클라이언트 연결을 생성하기 위한 HttpTrigger를 사용한 WebPubSubConnection 입력 바인딩입니다.

(3)-(4) 서비스 요청을 처리하기 위한 HttpTrigger를 사용한 WebPubSubTrigger 트리거 바인딩 또는 WebPubSubContext 입력 바인딩입니다.

(5)-(6) 서비스에 작업을 요청하기 위한 WebPubSub 출력 바인딩입니다.

트리거 바인딩

함수 트리거를 사용하여 Azure Web PubSub 서비스의 요청을 처리합니다.

WebPubSubTrigger는 서비스 쪽에서 요청을 처리해야 할 때 사용됩니다. 트리거 엔드포인트 패턴은 아래와 같으며 Web PubSub 서비스 쪽에서 설정해야 합니다(Portal: 설정 -> 이벤트 처리기 -> URL 템플릿). 엔드포인트 패턴에서 쿼리 부분 code=<API_KEY>는 보안상의 이유로 Azure 함수 앱을 사용할 때 필수입니다. 키는 Azure Portal에서 찾을 수 있습니다. 함수 앱 리소스를 찾고, Azure에 함수 앱을 배포한 후에 함수 ->앱 키 ->시스템 키 ->webpubsub_extension으로 이동합니다. 그러나 로컬 함수를 사용할 때는 이 키가 필요하지 않습니다.

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

예시

C#

[FunctionName("WebPubSubTrigger")]
public static void Run(
    [WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

또한 WebPubSubTrigger 바인딩은 서버가 클라이언트 요청을 확인 및 거부하거나 호출자에 직접 메시지를 보낼 수 있는 경우 Connect 시스템 및 사용자 이벤트와 같은 일부 시나리오의 반환 값도 지원합니다. Connect 이벤트는 ConnectEventResponse 및 EventErrorResponse를 준수하고, 사용자 이벤트는 UserEventResponse 및 EventErrorResponse를 준수하며, 현재 시나리오와 일치하지 않는 rest 유형은 무시됩니다. 또한 EventErrorResponse가 반환되면 서비스에서 클라이언트 연결을 삭제합니다.

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

JavaScript 모델 v4

다음 예제에서는 Web PubSub 트리거 JavaScript 함수를 보여 줍니다.

const { app, trigger } = require('@azure/functions');

const wpsTrigger = trigger.generic({
    type: 'webPubSubTrigger',
    name: 'request',
    hub: '<hub>',
    eventName: 'message',
    eventType: 'user'
});

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
        context.log('Request from: ', request.connectionContext.userId);
        context.log('Request message data: ', request.data);
        context.log('Request message dataType: ', request.dataType);
    }
});

또한 WebPubSubTrigger 바인딩은 서버가 클라이언트 요청을 확인 및 거부하거나 요청 클라이언트에 직접 메시지를 보낼 수 있는 경우 Connect 시스템 및 사용자 이벤트와 같은 일부 시나리오의 반환 값도 지원합니다. 약한 형식의 JavaScript 언어에서는 개체 키와 관련하여 역직렬화됩니다. 그리고 EventErrorResponse는 rest 개체에 비해 우선 순위가 가장 높으며 code가 반환 결과에 있는 경우 EventErrorResponse로 구문 분석되고 클라이언트 연결이 삭제됩니다.

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return { 
              "data": "ack",
              "dataType" : "text"
          };
    }
});

JavaScript 모델 v3

function.json에서 트리거 바인딩을 정의합니다.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSubTrigger",
      "direction": "in",
      "name": "data",
      "hub": "<hub>",
      "eventName": "message",
      "eventType": "user"
    }
  ]
}

index.js에서 함수를 정의합니다.

module.exports = function (context, data) {
  context.log('Request from: ', context.bindingData.request.connectionContext.userId);
  context.log('Request message data: ', data);
  context.log('Request message dataType: ', context.bindingData.request.dataType);
}

또한 WebPubSubTrigger 바인딩은 서버가 클라이언트 요청을 확인 및 거부하거나 요청 클라이언트에 직접 메시지를 보낼 수 있는 경우 Connect 시스템 및 사용자 이벤트와 같은 일부 시나리오의 반환 값도 지원합니다. 약한 형식의 JavaScript 언어에서는 개체 키와 관련하여 역직렬화됩니다. 그리고 EventErrorResponse는 rest 개체에 비해 우선 순위가 가장 높으며 code가 반환 결과에 있는 경우 EventErrorResponse로 구문 분석되고 클라이언트 연결이 삭제됩니다.

module.exports = async function (context) {
  return { 
    "data": "ack",
    "dataType" : "text"
  };
}

특성 및 주석

C# 클래스 라이브러리에서 WebPubSubTrigger 특성을 사용합니다.

다음은 메서드 서명의 WebPubSubTrigger 특성입니다.

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

전체 예제는 C# 예제를 참조하세요.

구성

다음 표에서는 function.json 파일에 설정된 바인딩 구성 속성을 설명합니다.

function.json 속성	특성 속성	설명
type	해당 없음	필수 - webPubSubTrigger으로 설정해야 합니다.
direction	해당 없음	필수 - in으로 설정해야 합니다.
이름	해당 없음	필수 - 이벤트 데이터를 수신하는 매개 변수에 대한 함수 코드에 사용되는 변수 이름입니다.
hub	허브	필수 - 함수가 트리거되려면 이 값을 반드시 Web PubSub 허브 이름으로 설정해야 합니다. 특성의 값을 더 높은 우선 순위로 설정하거나 앱 설정에서 전역 값으로 설정할 수 있습니다.
eventType	WebPubSubEventType	필수 - 함수가 트리거되려면 이 값을 반드시 메시지의 이벤트 유형으로 설정해야 합니다. 값은 user 또는 system이어야 합니다.
eventName	EventName	필수 - 함수가 트리거되려면 이 값을 반드시 메시지의 이벤트로 설정해야 합니다. system 이벤트 유형의 경우 이벤트 이름은 connect, connected, disconnected에 있어야 합니다. 사용자 정의 하위 프로토콜의 경우 이벤트 이름은 message입니다. 시스템 지원 하위 프로토콜json.webpubsub.azure.v1. 의 경우 이벤트 이름은 사용자 정의 이벤트 이름입니다.
connection	Connection	선택 사항 - 업스트림 Azure Web PubSub 서비스를 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 이 값은 서명 유효성 검사에 사용됩니다. 그리고 값은 기본적으로 앱 설정 “WebPubSubConnectionString”으로 자동 확인됩니다. 그리고 null은 유효성 검사가 필요하지 않으며 항상 성공한다는 것을 의미합니다.

사용

C#에서 WebPubSubEventRequest는 형식 인식 바인딩 매개 변수이고, rest 매개 변수는 매개 변수 이름으로 바인딩됩니다. 아래 표에서 사용 가능한 매개 변수 및 형식을 확인합니다.

JavaScript와 같은 약한 형식의 언어에서 function.json의 name은 아래 매핑 테이블과 관련된 트리거 개체를 바인딩하는 데 사용됩니다. 또한 name이 트리거 입력에 대한 바인딩 개체로서 data로 설정되면 그에 따라 function.json에서 dataType을 준수하여 메시지를 변환합니다. 모든 매개 변수는 context.bindingData.<BindingName>에서 읽을 수 있으며 JObject가 변환됩니다.

바인딩 이름	바인딩 유형	설명	속성
요청	WebPubSubEventRequest	업스트림 요청 설명	속성은 파생 클래스 ConnectEventRequest, ConnectedEventRequest, UserEventRequest, DisconnectedEventRequest를 비롯한 다양한 이벤트 유형에 따라 다릅니다.
connectionContext	WebPubSubConnectionContext	일반 요청 정보	EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
데이터	BinaryData,string,Stream,byte[]	사용자 message 이벤트의 클라이언트에서 메시지 데이터 요청	-
dataType	WebPubSubDataType	요청 메시지 dataType은 binary, text, json을 지원합니다.	-
claims	IDictionary<string, string[]>	시스템 connect 요청의 사용자 클레임	-
query	IDictionary<string, string[]>	시스템 connect 요청의 사용자 쿼리	-
subprotocols	IList<string>	시스템 connect 요청에서 사용 가능한 하위 프로토콜	-
clientCertificates	IList<ClientCertificate>	시스템 connect 요청에서 클라이언트의 인증서 지문 목록	-
reason	string	시스템 disconnected 요청의 이유	-

Important

C#에서는 지원되는 여러 형식의 매개 변수를 첫 번째 매개 변수에 배치해야 합니다. 즉, 함수 바인딩을 올바르게 만들려면 기본 BinaryData 형식 이외의 request 또는 data를 배치해야 합니다.

반환 응답

WebPubSubTrigger는 connect의 동기 이벤트 및 사용자 이벤트에 대해 고객이 반환한 응답을 준수합니다. 일치하는 응답만 서비스로 다시 전송되며, 그렇지 않으면 무시됩니다. 또한 WebPubSubTrigger return 개체는 사용자의 SetState() 및 ClearStates()를 지원하고 연결에 대한 메타데이터를 관리합니다. 또한 확장은 반환 값의 결과를 요청 WebPubSubConnectionContext.States의 원래 값과 병합합니다. 기존 키의 값은 덮어쓰고 새 키의 값이 추가됩니다.

반환 형식	설명	속성
ConnectEventResponse	connect 이벤트에 대한 응답	Groups, Roles, UserId, Subprotocol
UserEventResponse	사용자 이벤트에 대한 응답	DataType, Data
EventErrorResponse	동기화 이벤트에 대한 오류 응답	Code, ErrorMessage
*WebPubSubEventResponse	확실하지 않은 반환 사례에 사용되는 지원 응답의 기본 응답 형식	-

입력 바인딩

확장은 서로 다른 요구 사항을 대상으로 하는 2개의 입력 바인딩을 제공합니다.

• WebPubSubConnection

  클라이언트가 Azure Web PubSub Service에 연결할 수 있게 하려면 서비스 엔드포인트 URL 및 유효한 액세스 토큰을 알아야 합니다. WebPubSubConnection 입력 바인딩은 필요한 정보를 생성하므로 클라이언트는 이 토큰 생성 자체를 처리할 필요가 없습니다. 토큰은 시간 제한적이고 연결에 대해 특정 사용자를 인증하는 데 사용될 수 있으므로 토큰을 캐시하거나 클라이언트 간에 공유하지 않도록 합니다. 이 입력 바인딩을 사용하는 HTTP 트리거를 클라이언트에서 연결 정보를 검색하는 데 사용할 수 있습니다.

• WebPubSubContext

  Static Web Apps를 사용하는 경우 HttpTrigger는 지원되는 유일한 트리거이며 Web PubSub 시나리오에서는 사용자가 Web PubSub 프로토콜 아래의 서비스 쪽에서 업스트림 http 요청을 역직렬화하도록 지원하는 WebPubSubContext 입력 바인딩을 제공합니다. 따라서 고객은 함수에서의 쉬운 처리 측면에서 WebPubSubTrigger와 비교할 때 유사한 결과를 얻을 수 있습니다. 아래의 예제를 참조하세요. HttpTrigger와 함께 사용하는 경우 고객은 이벤트 처리기에서 HttpTrigger 노출 URL을 구성해야 합니다.

예 - WebPubSubConnection

다음 예제에서는 입력 바인딩을 사용하여 Web PubSub 연결 정보를 획득하고 HTTP를 통해 해당 정보를 반환하는 C# 함수를 보여 줍니다. 아래 예제에서는 ?userid={User-A}와 같은 클라이언트 요청 쿼리 부분을 통해 UserId가 전달됩니다.

C#

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
    return connection;
}

JavaScript 모델 v4

const { app, input } = require('@azure/functions');

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{query.userId}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

JavaScript 모델 v3

function.json에서 입력 바인딩을 정의합니다.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

index.js에서 함수를 정의합니다.

module.exports = function (context, req, connection) {
  context.res = { body: connection };
  context.done();
};

인증된 토큰

인증된 클라이언트에서 함수를 트리거하는 경우 생성된 토큰에 사용자 ID 클레임을 추가할 수 있습니다. App Service 인증을 사용하여 함수 앱에 인증을 쉽게 추가할 수 있습니다.

App Service 인증은 x-ms-client-principal-id라는 HTTP 헤더 및 인증된 사용자의 클라이언트 보안 주체 ID 및 이름 각각을 포함하는 x-ms-client-principal-name을 설정합니다.

바인딩 식 {headers.x-ms-client-principal-id} 또는 {headers.x-ms-client-principal-name}을 사용하여 바인딩의 UserId 속성을 헤더 중 하나의 값으로 설정할 수 있습니다.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection)
{
    return connection;
}

C#

참고 항목

바인딩 매개 변수 형식으로 제한되어 목록이나 배열을 전달하는 방법이 지원되지 않으며, WebPubSubConnection은 서버 SDK가 가지고 있는 모든 매개 변수, 특히 roles를 완전히 지원하지 않으며 groups 및 expiresAfter도 포함합니다. 고객이 함수에서 역할을 추가하거나 액세스 토큰 빌드를 지연해야 하는 경우 C#용 서버 SDK를 사용하는 것이 좋습니다.

[FunctionName("WebPubSubConnectionCustomRoles")]
public static async Task<Uri> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
{
    var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "<hub>", "<web-pubsub-connection-string>");
    var userId = req.Query["userid"].FirstOrDefault();
    // your method to get custom roles.
    var roles = GetRoles(userId);
    return await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
}

JavaScript 모델 v4

참고 항목

바인딩 매개 변수 형식으로 제한되어 목록이나 배열을 전달하는 방법이 지원되지 않으며, WebPubSubConnection은 서버 SDK가 가지고 있는 모든 매개 변수, 특히 roles를 완전히 지원하지 않으며 groups 및 expiresAfter도 포함합니다. 고객이 함수에서 역할을 추가하거나 액세스 토큰 빌드를 지연해야 하는 경우 JavaScript용 서버 SDK를 사용하는 것이 좋습니다.

const { app } = require('@azure/functions');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
        let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
        return { body: token.url };
    },
});

JavaScript 모델 v3

참고 항목

바인딩 매개 변수 형식으로 제한되어 목록이나 배열을 전달하는 방법이 지원되지 않으며, WebPubSubConnection은 서버 SDK가 가지고 있는 모든 매개 변수, 특히 roles를 완전히 지원하지 않으며 groups 및 expiresAfter도 포함합니다. 고객이 함수에서 역할을 추가하거나 액세스 토큰 빌드를 지연해야 하는 경우 JavaScript용 서버 SDK를 사용하는 것이 좋습니다.

function.json에서 입력 바인딩을 정의합니다.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

index.js에서 함수를 정의합니다.

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

module.exports = async function (context, req) {
  const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
  let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  context.res = { body: token.url };
  context.done();
};

예 - WebPubSubContext

다음 예제에서는 connect 이벤트 유형 아래의 입력 바인딩을 사용하여 Web PubSub 업스트림 정보를 획득하고 HTTP를 통해 해당 정보를 반환하는 C# 함수를 보여 줍니다.

C#

[FunctionName("WebPubSubContextInputBinding")]
public static object Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubContext] WebPubSubContext wpsContext)
{
    // in the case request is a preflight or invalid, directly return prebuild response by extension.
    if (wpsContext.IsPreflight || wpsContext.HasError)
    {
        return wpsContext.Response;
    }
    var request = wpsContext.Request as ConnectEventRequest;
    var response = new ConnectEventResponse
    {
        UserId = wpsContext.Request.ConnectionContext.UserId
    };
    return response;
}

JavaScript 모델 v4

const { app, input } = require('@azure/functions');

const wpsContext = input.generic({
    type: 'webPubSubContext',
    name: 'wpsContext'
});

app.http('connect', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [wpsContext],
    handler: async (request, context) => {
        var wpsRequest = context.extraInputs.get('wpsContext');

        return { "userId": wpsRequest.request.connectionContext.userId };
    }
});

JavaScript 모델 v3

function.json에서 입력 바인딩을 정의합니다.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubContext",
      "name": "wpsContext",
      "direction": "in"
    }
  ]
}

index.js에서 함수를 정의합니다.

module.exports = async function (context, req, wpsContext) {
  // in the case request is a preflight or invalid, directly return prebuild response by extension.
  if (wpsContext.hasError || wpsContext.isPreflight)
  {
    return wpsContext.response;
  }
  // return an http response with connect event response as body.
  return { body: {"userId": wpsContext.connectionContext.userId} };
};

구성

WebPubSubConnection

다음 테이블에서는 function.json 파일 및 WebPubSubConnection 특성에 설정된 바인딩 구성 속성을 설명합니다.

function.json 속성	특성 속성	설명
type	해당 없음	webPubSubConnection로 설정해야 합니다.
direction	해당 없음	in로 설정해야 합니다.
이름	해당 없음	입력 연결 바인딩 개체에 대한 함수 코드에 사용되는 변수 이름입니다.
hub	허브	필수 - 함수가 트리거되려면 이 값을 반드시 Web PubSub 허브 이름으로 설정해야 합니다. 특성의 값을 더 높은 우선 순위로 설정하거나 앱 설정에서 전역 값으로 설정할 수 있습니다.
userId	사용자 ID	선택 사항 - 액세스 키 토큰에서 설정될 사용자 식별자 클레임의 값입니다.
connection	Connection	필수 - Web PubSub Service 연결 문자열(기본값 "WebPubSubConnectionString")을 포함하는 앱 설정의 이름입니다.

WebPubSubContext

다음 테이블에서는 function.json 파일 및 WebPubSubContext 특성에 설정된 바인딩 구성 속성을 설명합니다.

function.json 속성	특성 속성	설명
type	해당 없음	webPubSubContext로 설정해야 합니다.
direction	해당 없음	in로 설정해야 합니다.
이름	해당 없음	입력 Web PubSub 요청에 대한 함수 코드에 사용되는 변수 이름입니다.
connection	Connection	선택 사항 - 업스트림 Azure Web PubSub 서비스를 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 이 값은 남용 방지 및 서명 유효성 검사에 사용됩니다. 이 값은 기본적으로 “WebPubSubConnectionString”으로 자동 확인됩니다. 그리고 null은 유효성 검사가 필요하지 않으며 항상 성공한다는 것을 의미합니다.

사용

WebPubSubConnection

C#

WebPubSubConnection는 아래 속성을 제공합니다.

바인딩 이름	바인딩 유형	설명
baseUri?	URI	Web PubSub 클라이언트 연결 uri
URI	URI	Web PubSub 연결의 절대 URI는 요청의 AccessToken 생성 기반을 포함합니다.
AccessToken	string	요청 UserId 및 서비스 정보를 기준으로 생성된 AccessToken입니다.

JavaScript 모델 v4

WebPubSubConnection는 아래 속성을 제공합니다.

바인딩 이름	설명
baseUrl	Web PubSub 클라이언트 연결 uri
URL	Web PubSub 연결의 절대 URI는 요청의 AccessToken 생성 기반을 포함합니다.
accessToken	요청 UserId 및 서비스 정보를 기준으로 생성된 AccessToken입니다.

JavaScript 모델 v3

WebPubSubConnection는 아래 속성을 제공합니다.

바인딩 이름	설명
baseUrl	Web PubSub 클라이언트 연결 uri
URL	Web PubSub 연결의 절대 URI는 요청의 AccessToken 생성 기반을 포함합니다.
accessToken	요청 UserId 및 서비스 정보를 기준으로 생성된 AccessToken입니다.

WebPubSubContext

WebPubSubContext는 아래 속성을 제공합니다.

바인딩 이름	바인딩 유형	설명	속성
요청	WebPubSubEventRequest	클라이언트의 요청, 자세한 내용은 아래 표를 참조하세요.	요청 헤더의 WebPubSubConnectionContext 및 요청 본문에서 역직렬화된 기타 속성에서 요청을 설명합니다(예 DisconnectedEventRequest에 대한 Reason).
응답	HttpResponseMessage	주로 AbuseProtection 및 오류 사례에 대한 확장 빌드 응답입니다.	-
errorMessage	string	업스트림 요청을 처리할 때 오류 세부 정보를 설명합니다.	-
hasError	bool	유효한 Web PubSub 업스트림 요청인지 여부를 나타내는 플래그입니다.	-
isPreflight	bool	AbuseProtection의 실행 전 요청인지 여부를 나타내는 플래그입니다.	-

WebPubSubEventRequest의 경우 요청 시나리오에 대한 다양한 정보를 제공하는 다른 클래스로 역직렬화됩니다. PreflightRequest의 경우 또는 유효하지 않은 경우 사용자는 IsPreflight 및 HasError 플래그를 확인하여 알 수 있습니다. 시스템 빌드 응답 WebPubSubContext.Response를 직접 반환하는 것이 좋습니다. 또는 고객이 필요에 따라 오류를 기록할 수 있습니다. 다른 시나리오에서 고객은 아래와 같이 요청 속성을 읽을 수 있습니다.

파생 클래스	설명	속성
PreflightRequest	IsPreflight가 true일 때 AbuseProtection에서 사용됩니다.	-
ConnectEventRequest	시스템 Connect 이벤트 유형에 사용됨	Claims, Query, Subprotocols, ClientCertificates
ConnectedEventRequest	시스템 Connected 이벤트 유형에 사용됨	-
UserEventRequest	사용자 이벤트 유형에 사용됨	Data, DataType
DisconnectedEventRequest	시스템 Disconnected 이벤트 유형에 사용됨	원인

참고 항목

WebPubSubContext는 HttpTrigger에서 입력 바인딩이 WebPubSubTrigger에 비해 유사한 요청 역직렬화 방법을 제공하지만 제한 사항이 있습니다. 즉, 연결 상태 사후 병합이 지원되지 않습니다. 반환 응답은 여전히 서비스 쪽에서 준수하지만 사용자는 직접 응답을 빌드해야 합니다. 사용자가 이벤트 응답을 설정해야 하는 경우 ConnectEventResponse 또는 사용자 이벤트에 대한 메시지를 응답 본문으로 포함하는 HttpResponseMessage를 반환하고 응답 헤더에서 ce-connectionstate 키를 사용하여 연결 상태를 설정해야 합니다.

출력 바인딩

Web PubSub 출력 바인딩을 사용하여 Azure Web PubSub 서비스를 호출한 후 작업을 수행합니다. 다음으로 메시지를 브로드캐스트할 수 있습니다.

• 연결된 모든 클라이언트
• 특정 사용자에게 인증된 연결된 클라이언트
• 특정 그룹에 조인된 연결된 클라이언트
• 특정 클라이언트 연결

출력 바인딩을 사용하여 그룹과 클라이언트를 관리하고, 그룹을 사용하여 특정 connectionId를 대상으로 하는 권한을 부여/취소할 수 있습니다.

• 그룹에 연결 추가
• 그룹에 사용자 추가
• 그룹에서 연결 제거
• 그룹에서 사용자 제거
• 모든 그룹에서 사용자 제거
• 모든 클라이언트 연결 닫기
• 특정 클라이언트 연결 닫기
• 그룹에서 연결 닫기
• 연결 권한 부여
• 연결 권한 취소

설정 및 구성 세부 정보에 대한 자세한 내용은 개요를 참조하세요.

예시

C#

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

JavaScript 모델 v4

const { app, output } = require('@azure/functions');
const wpsMsg = output.generic({
    type: 'webPubSub',
    name: 'actions',
    hub: '<hub>',
});

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [wpsMsg],
    handler: async (request, context) => {
        context.extraOutputs.set(wpsMsg, [{
            "actionName": "sendToAll",
            "data": `Hello world`,
            "dataType": `text`
        }]);
    }
});

JavaScript 모델 v3

functions.json에서 바인딩을 정의합니다.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

index.js에서 함수를 정의합니다.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "hello",
    "dataType": "text"
  };
  context.done();
}

WebPubSubAction

WebPubSubAction은 출력 바인딩의 기본 추상 형식입니다. 파생 형식은 서비스에서 호출할 작업 서버를 나타냅니다.

C#

C# 언어에서는 WebPubSubAction에서 사용 가능한 작업을 검색하는 데 도움이 되는 몇 가지 정적 메서드를 제공합니다. 예를 들어 사용자는 WebPubSubAction.CreateSendToAllAction()를 호출하여 SendToAllAction를 만들 수 있습니다.

파생 클래스	속성
SendToAllAction	Data, DataType, Excluded
SendToGroupAction	Group, Data, DataType, Excluded
SendToUserAction	UserId, Data, DataType
SendToConnectionAction	ConnectionId, Data, DataType
AddUserToGroupAction	UserId, Group
RemoveUserFromGroupAction	UserId, Group
RemoveUserFromAllGroupsAction	사용자 ID
AddConnectionToGroupAction	ConnectionId, Group
RemoveConnectionFromGroupAction	ConnectionId, Group
CloseAllConnectionsAction	Excluded, Reason
CloseClientConnectionAction	ConnectionId, Reason
CloseGroupConnectionsAction	Group, Excluded, Reason
GrantPermissionAction	ConnectionId, Permission, TargetName
RevokePermissionAction	ConnectionId, Permission, TargetName

JavaScript 모델 v4

javascript, actionName과 같이 형식이 약한 언어에서는 형식을 확인하는 주요 매개 변수이며 사용 가능한 작업은 아래와 같습니다.

ActionName	속성
sendToAll	Data, DataType, Excluded
sendToGroup	Group, Data, DataType, Excluded
sendToUser	UserId, Data, DataType
sendToConnection	ConnectionId, Data, DataType
addUserToGroup	UserId, Group
removeUserFromGroup	UserId, Group
removeUserFromAllGroups	사용자 ID
addConnectionToGroup	ConnectionId, Group
removeConnectionFromGroup	ConnectionId, Group
closeAllConnections	Excluded, Reason
closeClientConnection	ConnectionId, Reason
closeGroupConnections	Group, Excluded, Reason
grantPermission	ConnectionId, Permission, TargetName
revokePermission	ConnectionId, Permission, TargetName

Important

데이터 형식을 json 또는 text로 설정하여 데이터 변환 모호성을 방지하려면 메시지 보내기 관련 작업의 메시지 데이터 속성이 string여야 합니다. JSON.stringify()를 사용하여 필요한 json 개체를 변환하세요. 이는 메시지 속성(예 WebPubSubTrigger로 작동하는 UserEventResponse.Data)을 사용하여 모든 위치에 적용됩니다.

데이터 형식이 binary로 설정되면 function.json에서 binary로 구성된 대로 자연스럽게 지원되는 dataType 바인딩을 활용할 수 있습니다. 자세한 내용은 트리거 및 바인딩 정의를 참조하세요.

JavaScript 모델 v3

javascript, actionName과 같이 형식이 약한 언어에서는 형식을 확인하는 주요 매개 변수이며 사용 가능한 작업은 아래와 같습니다.

ActionName	속성
sendToAll	Data, DataType, Excluded
sendToGroup	Group, Data, DataType, Excluded
sendToUser	UserId, Data, DataType
sendToConnection	ConnectionId, Data, DataType
addUserToGroup	UserId, Group
removeUserFromGroup	UserId, Group
removeUserFromAllGroups	사용자 ID
addConnectionToGroup	ConnectionId, Group
removeConnectionFromGroup	ConnectionId, Group
closeAllConnections	Excluded, Reason
closeClientConnection	ConnectionId, Reason
closeGroupConnections	Group, Excluded, Reason
grantPermission	ConnectionId, Permission, TargetName
revokePermission	ConnectionId, Permission, TargetName

Important

데이터 형식을 json 또는 text로 설정하여 데이터 변환 모호성을 방지하려면 메시지 보내기 관련 작업의 메시지 데이터 속성이 string여야 합니다. JSON.stringify()를 사용하여 필요한 json 개체를 변환하세요. 이는 메시지 속성(예 WebPubSubTrigger로 작동하는 UserEventResponse.Data)을 사용하여 모든 위치에 적용됩니다.

데이터 형식이 binary로 설정되면 function.json에서 binary로 구성된 대로 자연스럽게 지원되는 dataType 바인딩을 활용할 수 있습니다. 자세한 내용은 트리거 및 바인딩 정의를 참조하세요.

구성

WebPubSub

다음 테이블에서는 function.json 파일 및 WebPubSub 특성에 설정된 바인딩 구성 속성을 설명합니다.

function.json 속성	특성 속성	설명
type	해당 없음	webPubSub로 설정해야 합니다.
direction	해당 없음	out로 설정해야 합니다.
이름	해당 없음	출력 바인딩 개체에 대한 함수 코드에 사용되는 변수 이름입니다.
hub	허브	함수가 트리거되려면 이 값을 반드시 Web PubSub 허브 이름으로 설정해야 합니다. 특성의 값을 더 높은 우선 순위로 설정하거나 앱 설정에서 전역 값으로 설정할 수 있습니다.
connection	Connection	Web PubSub Service 연결 문자열(기본값 “WebPubSubConnectionString”)을 포함하는 앱 설정의 이름입니다.

문제 해결

콘솔 로깅 설정

서비스에 대해 수행하는 요청을 더 자세히 알아보려면 쉽게 콘솔 로깅을 사용하도록 설정할 수도 있습니다.

다음 단계

다음 리소스를 사용하여 사용자 고유의 애플리케이션 빌드를 시작합니다.

자습서: Azure Web PubSub에서 메시지 게시 및 구독

자습서: Azure Web PubSub를 사용하여 간단한 채팅방 만들기

자습서: 클라이언트 스트리밍에 서비스 지원 하위 프로토콜 사용

자습서: Azure Functions 및 Web PubSub를 사용하여 서버리스 채팅 빌드

자습서: 이벤트 수신기 구성

라이브 데모로 재생

Azure Web PubSub 샘플 자세히 살펴보기