Azure Functions에 대한 Azure Web PubSub 입력 바인딩

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

WebPubSubConnection

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

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

`WebPubSubConnection`

예시

다음 예제에서는 입력 바인딩을 사용하여 Web PubSub 연결 정보를 획득하고 HTTP를 통해 반환하는 HTTP 트리거 함수를 보여 줍니다. 다음 예제에서는 UserId 클라이언트 요청 쿼리 파트(예: ?userid={User-A}.)를 통해 전달됩니다.

격리된 작업자 모델
In Process 모델

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{query.userid}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

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

모델 v4
모델 v3

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')) };
    },
});

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();
};

협상 및 업데이트 협상/function.json 폴더를 만들고 다음 JSON 코드를 복사합니다.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

negotiate/init.py 함수를 정의합니다.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

참고 항목

이 언어에 대한 전체 샘플이 보류 중입니다.

참고 항목

Java용 Web PubSub 확장은 아직 지원되지 않습니다.

인증된 사용자 ID 가져오기

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

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

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

격리된 작업자 모델
In Process 모델

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{headers.x-ms-client-principal-id}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

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

모델 v4
모델 v3

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

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{headers.x-ms-client-principal-id}',
    hub: '<hub>'
});

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

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

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{headers.x-ms-client-principal-id}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

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

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

협상 및 업데이트 협상/function.json 폴더를 만들고 다음 JSON 코드를 복사합니다.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{headers.x-ms-client-principal-id}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

negotiate/init.py 함수를 정의합니다.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

참고 항목

이 언어에 대한 전체 샘플이 보류 중입니다.

참고 항목

Java용 Web PubSub 확장은 아직 지원되지 않습니다.

구성

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

function.json 속성	특성 속성	설명
유형	해당 없음	`webPubSubConnection`로 설정해야 합니다.
방향	해당 없음	`in`로 설정해야 합니다.
이름	해당 없음	입력 연결 바인딩 개체에 대한 함수 코드에 사용되는 변수 이름입니다.
허브	허브	필수 - 함수가 트리거되려면 이 값을 반드시 Web PubSub 허브 이름으로 설정해야 합니다. 특성의 값을 더 높은 우선 순위로 설정하거나 앱 설정에서 전역 값으로 설정할 수 있습니다.
userId	사용자 ID	선택 사항 - 액세스 키 토큰에서 설정될 사용자 식별자 클레임의 값입니다.
clientProtocol	ClientProtocol	선택 사항 - 클라이언트 프로토콜 유형입니다. 유효한 값은 `default` 및 `mqtt`이고 MQTT 클라이언트의 경우 이 클라이언트를 .로 `mqtt`설정해야 합니다. 다른 클라이언트의 경우 속성을 생략하거나 로 설정할 `default`수 있습니다.
연결	연결	필수 - Web PubSub Service 연결 문자열(기본값 "WebPubSubConnectionString")을 포함하는 앱 설정의 이름입니다.

사용

WebPubSubConnection 에서는 다음 속성을 제공합니다.

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

WebPubSubConnection 에서는 다음 속성을 제공합니다.

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

참고 항목

Java용 Web PubSub 확장은 아직 지원되지 않습니다.

생성된 토큰의 추가 사용자 지정

바인딩 매개 변수 형식으로 제한되면 목록이나 배열을 전달하는 방법이 지원되지 않으며, WebPubSubConnection SDK 서버의 모든 매개 변수 서버에서 완전히 지원되지는 않으며, 특히 roles포함 groups 및 포함됩니다 expiresAfter.

고객이 역할을 추가하거나 함수에서 액세스 토큰 빌드를 지연해야 하는 경우 C#용 서버 SDK를 사용하는 것이 좋습니다.

격리된 작업자 모델
In Process 모델

[Function("WebPubSubConnectionCustomRoles")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData 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);
    var url = await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteString(url.ToString());
    return response;
}

[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용 서버 SDK를 사용하는 것이 좋습니다.

모델 v4
모델 v3

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 };
    },
});

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();
};

참고 항목

이 언어에 대한 전체 샘플이 보류 중입니다.

참고 항목

Java용 Web PubSub 확장은 아직 지원되지 않습니다.

`WebPubSubContext`

// validate method when upstream set as http://<func-host>/api/{event}
[Function("validate")]
public static HttpResponseData Validate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req,
    [WebPubSubContextInput] WebPubSubContext wpsReq)
{
    return BuildHttpResponseData(req, wpsReq.Response);
}

// Respond AbuseProtection to put header correctly.
private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse)
{
    var response = request.CreateResponse();
    response.StatusCode = (HttpStatusCode)wpsResponse.Status;
    response.Body = response.Body;
    foreach (var header in wpsResponse.Headers)
    {
        response.Headers.Add(header.Key, header.Value);
    }
    return response;
}

[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;
}

모델 v4
모델 v3

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 };
    }
});

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 prebuilt 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} };
};

참고 항목

이 언어에 대한 전체 샘플이 보류 중입니다.

참고 항목

Java용 Web PubSub 확장은 아직 지원되지 않습니다.

구성

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

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

중요합니다

최적의 보안을 위해 함수 앱은 공유 비밀 키가 포함된 연결 문자열을 사용하는 대신 Web PubSub 서비스에 연결할 때 관리 ID를 사용해야 합니다. 자세한 내용은 Microsoft Entra ID를 사용하여 관리 ID 요청 권한 부여를 참조하세요.

사용

WebPubSubContext 에서는 다음 속성을 제공합니다.

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

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

파생 클래스	설명	속성
`PreflightRequest`	`AbuseProtection`가 `IsPreflight`일 때 에서 사용됩니다.	-
`ConnectEventRequest`	시스템 `Connect` 이벤트 유형에 사용됨	클레임, 쿼리, 하위 프로토콜, ClientCertificates
`ConnectedEventRequest`	시스템 `Connected` 이벤트 유형에 사용됨	-
`UserEventRequest`	사용자 이벤트 유형에 사용됨	데이터, 데이터 유형
`DisconnectedEventRequest`	시스템 `Disconnected` 이벤트 유형에 사용됨	원인

참고 항목

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-05-21

다음을 통해 공유

Azure Functions에 대한 Azure Web PubSub 입력 바인딩

WebPubSubConnection

예시

인증된 사용자 ID 가져오기

구성

사용

생성된 토큰의 추가 사용자 지정

WebPubSubContext

예시

구성

사용

피드백

추가 리소스

`WebPubSubConnection`

`WebPubSubContext`