Azure Function 트리거 및 바인딩 Socket.IO(미리 보기)

이 문서에서는 Azure Functions와 Socket.IO 서버리스 통합을 사용하는 방법을 설명합니다.

작업	바인딩 유형
URL 및 액세스 토큰을 포함한 클라이언트 협상 결과 가져오기	입력 바인딩
서비스의 메시지에 의해 트리거됨	트리거 바인딩
메시지를 보내거나 클라이언트를 관리하는 서비스 호출	출력 바인딩

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

Important

Azure Function 바인딩은 서버리스 모드에서 Socket.IO Web PubSub와만 통합할 수 있습니다.

인증 및 연결 문자열

확장이 Socket.IO Web PubSub에서 작동하도록 하려면 서비스에 인증하기 위해 액세스 키 또는 ID 기반 구성을 제공해야 합니다.

액세스 키 기반 구성

구성 이름	설명
WebPubSubForSocketIOConnectionString	필수입니다. 서비스에 대한 키 기반 연결 문자열

Azure Portal에서 Socket.IO Web PubSub의 키 블레이드에서 연결 문자열 찾을 수 있습니다.

로컬 개발의 경우 파일을 사용하여 local.settings.json 연결 문자열 저장합니다. 이전 단계에서 복사한 연결 문자열 설정합니다WebPubSubForSocketIOConnectionString.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    `WebPubSubForSocketIOConnectionString`: "Endpoint=https://<webpubsub-name>.webpubsub.azure.com;AccessKey=<access-key>;Version=1.0;"
  }
}

배포되는 경우 애플리케이션 설정을 사용하여 연결 문자열 설정합니다.

ID 기반 구성

구성 이름	설명
WebPubSubForSocketIOConnectionString__endpoint	필수입니다. 서비스의 엔드포인트입니다. 예를 들어 https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	연결을 위해 토큰을 가져오는 방법을 정의합니다. 배포된 Azure Function이 관리 ID 인증을 사용하려는 경우 이 설정을 managedidentity로 설정해야 합니다. 이 값은 호스팅 환경에서 관리 ID를 사용할 수 있는 경우에만 유효합니다.
WebPubSubForSocketIOConnectionString__clientId	credential이 managedidentity로 설정된 경우 이 속성은 토큰을 가져올 때 사용할 사용자가 할당한 ID를 지정하도록 설정할 수 있습니다. 속성은 애플리케이션에 할당된 사용자가 할당한 ID에 해당하는 클라이언트 ID를 허용합니다. 지정하지 않으면 시스템 할당 ID가 사용됩니다.

함수 바인딩은 ID 기반 구성에 대한 공통 속성을 따릅니다. 더 많은 멘션되지 않은 속성은 ID 기반 연결에 대한 공통 속성을 참조하세요.

로컬 개발의 경우 파일을 사용하여 local.settings.json 연결 문자열 저장합니다. 이전 단계에서 복사한 연결 문자열 설정합니다WebPubSubForSocketIOConnectionString.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "WebPubSubForSocketIOConnectionString__endpoint": "https://<webpubsub-name>.webpubsub.azure.com",
    "WebPubSubForSocketIOConnectionString__tenant": "<tenant id you're in>",
  }
}

ID 기반 구성을 사용하고 온라인으로 AzureWebJobsStorage 실행하려면 ID를 사용하여 호스트 스토리지에 연결하는 것을 참조해야 합니다.

입력 바인딩

Socket.IO 입력 바인딩은 클라이언트 협상 요청에 대한 a SocketIONegotiationResult 를 생성합니다. Socket.IO 클라이언트가 서비스에 연결하려고 할 때 인증에 대해 알고 endpointpathaccess token 있어야 합니다. 이러한 데이터를 생성하는 서버를 갖는 것이 일반적이며 이를 협상이라고 합니다.

C#

[FunctionName("SocketIONegotiate")]
public static IActionResult Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,
    [SocketIONegotiation(Hub = "hub", UserId = "userId")] SocketIONegotiationResult result)
{
    return new OkObjectResult(result);
}

attribute

입력 바인딩의 특성은 .입니다 [SocketIONegotiation].

특성 속성	설명
허브	클라이언트가 연결해야 하는 허브 이름입니다.
Connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).
UserId	연결의 userId입니다. 연결의 모든 소켓에 적용됩니다. 생성된 토큰의 sub 클레임이 됩니다.

JavaScript 모델 v4

import { app, HttpRequest, HttpResponseInit, InvocationContext, input, } from "@azure/functions";

const socketIONegotiate = input.generic({
    type: 'socketionegotiation',
    direction: 'in',
    name: 'result',
    hub: 'hub',
});

export async function negotiate(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    let result = context.extraInputs.get(socketIONegotiate);
    return { jsonBody: result };
};

// Negotiation
app.http('negotiate', {
    methods: ['GET'],
    authLevel: 'anonymous',
    extraInputs: [socketIONegotiate],
    handler: negotiate
});

구성

속성	설명
type	socketionegotiation이어야 합니다.
direction	in이어야 합니다.
name	입력 연결 바인딩 개체에 대한 함수 코드에 사용되는 변수 이름
hub	클라이언트가 연결해야 하는 허브 이름입니다.
connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).
userId	연결의 userId입니다. 연결의 모든 소켓에 적용됩니다. 생성된 토큰의 sub 클레임이 됩니다.

Python 모델 v2

함수에는 항상 트리거 바인딩이 필요합니다. 코드의 예로 HttpTrigger를 사용합니다.

import azure.functions as func
app = func.FunctionApp()

@app.function_name(name="negotiate")
@app.route(auth_level=func.AuthLevel.ANONYMOUS)
@app.generic_input_binding(arg_name="negotiate", type="socketionegotiation", hub="hub")
def negotiate(req: func.HttpRequest, negotiate) -> func.HttpResponse:
    return func.HttpResponse(negotiate)

주석

속성	설명
arg_name	입력 바인딩을 나타내는 함수 내 인수의 변수 이름입니다.
type	socketionegotiation이어야 합니다.
hub	클라이언트가 연결해야 하는 허브 이름입니다.
connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).
userId	연결의 userId입니다. 연결의 모든 소켓에 적용됩니다. 생성된 토큰의 sub 클레임이 됩니다.

트리거 바인딩

Azure Function은 트리거 바인딩을 사용하여 함수를 트리거하여 Socket.IO Web PubSub에서 이벤트를 처리합니다.

트리거 바인딩은 Azure Function 엔드포인트를 따르는 특정 경로를 노출합니다. URL은 서비스의 URL 템플릿으로 설정되어야 합니다(포털: 설정 -> 이벤트 처리기 -> URL 템플릿). 엔드포인트 패턴에서 쿼리 부분 code=<API_KEY>는 보안상의 이유로 Azure 함수 앱을 사용할 때 필수입니다. 키는 Azure Portal에서 찾을 수 있습니다. 함수 앱 리소스를 찾고 함수 앱을 Azure에 배포한 후 Functions ->App 키 ->시스템 키 ->socketio_extension 이동합니다. 그러나 로컬 함수를 사용할 때는 이 키가 필요하지 않습니다.

<Function_App_Endpoint>/runtime/webhooks/socketio?code=<API_KEY>

C#

소켓 연결 이벤트에 대한 함수 트리거입니다.

[FunctionName("SocketIOTriggerConnect")]
public static async Task<SocketIOEventHandlerResponse> Connect(
    [SocketIOTrigger("hub", "connect")] SocketIOConnectRequest request)
{
    return new SocketIOConnectResponse();
}

소켓 연결 이벤트에 대한 함수 트리거입니다.

[FunctionName("SocketIOTriggerConnected")]
public static async Task Connected(
    [SocketIOTrigger("hub", "connected")] SocketIOConnectedRequest request)
{
}

소켓 연결 끊기 이벤트에 대한 함수 트리거입니다.

[FunctionName("SocketIOTriggerDisconnected")]
public static async Task Disconnected(
    [SocketIOTrigger("hub", "disconnected")] SocketIODisconnectedRequest request)
{
}

클라이언트의 일반 메시지에 대한 함수 트리거입니다.

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIOParameter] string arg)
{
}

특성

트리거 바인딩의 특성은 .입니다 [SocketIOTrigger].

특성 속성	설명
허브	클라이언트가 연결해야 하는 허브 이름입니다.
네임스페이스	소켓의 네임스페이스입니다. 기본값: "/"
EventName	함수가 트리거하는 이벤트 이름입니다. 소켓 연결 이벤트의 경우 일부 이벤트 이름이 미리 정의되어 connect 있습니다. connected 는 소켓 연결 이벤트에 대한 것입니다. disconnected 는 소켓 연결이 끊긴 이벤트에 대한 것입니다. 그리고 다른 이벤트는 사용자에 의해 정의되며 클라이언트 쪽에서 보낸 이벤트 이름과 일치해야 합니다.
ParameterNames	이벤트의 매개 변수 이름 목록입니다. 목록의 길이는 클라이언트에서 보낸 이벤트와 일치해야 합니다. 또한 이름은 바인딩 식을 사용하고 동일한 이름 함수 매개 변수로 액세스합니다.

데이터 바인딩

[SocketIOTrigger] 는 일부 변수를 바인딩 데이터에 바인딩합니다. Azure Functions 바인딩 식 패턴에서 자세히 알아볼 수 있습니다.

SocketIOAttribute

SocketIOAttribute 는 함수 정의를 간소화하는 대안 ParameterNames입니다. 예를 들어 다음 두 정의의 효과는 동일합니다.

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIOParameter] string arg)
{
}

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message", ParameterNames = new[] {"arg"})] SocketIOMessageRequest request,
    string arg)
{
}

함께 ParameterNames[SocketIOParameter] 사용할 수 없습니다.

JavaScript 모델 v4

소켓 연결 이벤트에 대한 함수 트리거입니다.

import { app, InvocationContext, input, trigger } from "@azure/functions";


export async function connect(request: any, context: InvocationContext): Promise<any> {
    return {};
}

// Trigger for connect
app.generic('connect', {
  trigger: trigger.generic({
    type: 'socketiotrigger',
    hub: 'hub',
    eventName: 'connect'
  }),
  handler: connect
});

소켓 연결 이벤트에 대한 함수 트리거입니다.

import { app, InvocationContext, trigger } from "@azure/functions";

export async function connected(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for connected
app.generic('connected', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'connected'
    }),
    handler: connected
});

소켓 연결이 끊긴 이벤트에 대한 함수 트리거입니다.

import { app, InvocationContext, trigger } from "@azure/functions";

export async function disconnected(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for connected
app.generic('disconnected', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'disconnected'
    }),
    handler: disconnected
});

클라이언트의 일반 메시지에 대한 함수 트리거입니다.

import { app, InvocationContext, trigger, output } from "@azure/functions";

export async function newMessage(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for new message
app.generic('newMessage', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'new message'
    }),
    handler: newMessage
});

구성

속성	설명
type	socketiotrigger이어야 합니다.
hub	클라이언트가 연결해야 하는 허브 이름입니다.
namespace	소켓의 네임스페이스입니다. 기본값: "/"
eventName	함수가 트리거하는 이벤트 이름입니다. 소켓 연결 이벤트의 경우 일부 이벤트 이름이 미리 정의되어 connect 있습니다. connected 는 소켓 연결 이벤트에 대한 것입니다. disconnected 는 소켓 연결이 끊긴 이벤트에 대한 것입니다. 그리고 다른 이벤트는 사용자에 의해 정의되며 클라이언트 쪽에서 보낸 이벤트 이름과 일치해야 합니다.
ParameterNames	이벤트의 매개 변수 이름 목록입니다. 목록의 길이는 클라이언트에서 보낸 이벤트와 일치해야 합니다. 또한 이 이름은 바인딩 식을 사용하고 다음을 통해 액세스context.bindings.<name>합니다.

Python 모델 v2

소켓 연결 이벤트에 대한 함수 트리거입니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="connect")
def connect(sio: str) -> str:
    return json.dumps({'statusCode': 200})

소켓 연결 이벤트에 대한 함수 트리거입니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="connected")
def connected(sio: str) -> None:
    print("connected")

소켓 연결이 끊긴 이벤트에 대한 함수 트리거입니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="disconnected")
def connected(sio: str) -> None:
    print("disconnected")

클라이언트의 일반 메시지에 대한 함수 트리거입니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="chat")
def chat(sio: str) -> None:
    # do something else

콜백을 사용하는 일반 메시지에 대한 함수 트리거입니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="chat")
def chat(sio: str) -> str:
    return json.dumps({'ack': ["param1"]})

주석

속성	설명
arg_name	트리거 바인딩을 나타내는 함수 내 인수의 변수 이름입니다.
type	socketiotrigger이어야 합니다.
hub	클라이언트가 연결해야 하는 허브 이름입니다.
data_type	DataType.STRING이어야 합니다.
namespace	소켓의 네임스페이스입니다. 기본값: "/"
eventName	함수가 트리거하는 이벤트 이름입니다. 소켓 연결 이벤트의 경우 일부 이벤트 이름이 미리 정의되어 connect 있습니다. connected 는 소켓 연결 이벤트에 대한 것입니다. disconnected 는 소켓 연결이 끊긴 이벤트에 대한 것입니다. 그리고 다른 이벤트는 사용자에 의해 정의되며 클라이언트 쪽에서 보낸 이벤트 이름과 일치해야 합니다.

입력 바인딩 요청

입력 바인딩 인수의 데이터 구조는 메시지 유형에 따라 달라집니다.

연결

{
    "namespace": "",
    "socketId": "",
    "claims": {
        "<claim-type>": [ "<claim-value>" ]
    },
    "query": {
        "<query-key>": [ "<query-value>" ]
    },
    "headers":{
        "<header-name>": [ "<header-value>" ]
    },
    "clientCertificates":{
        {
            "thumbprint": "",
            "content": ""
        }
    }
}

속성	설명
namespace	소켓의 네임스페이스입니다.
socketId	소켓의 고유 ID입니다.
claims	클라이언트 연결의 JWT 클레임입니다. 서비스에서 함수를 요청할 때 JWT가 아니라 Engine.IO 클라이언트가 서비스에 연결할 때 JWT입니다.
query	클라이언트 연결의 쿼리입니다. 서비스에서 함수를 요청할 때 쿼리가 아니라 Engine.IO 클라이언트가 서비스에 연결할 때의 쿼리입니다.
헤더	클라이언트 연결의 헤더입니다. 서비스에서 함수를 요청할 때 헤더가 아니라 Engine.IO 클라이언트가 서비스에 연결할 때 헤더입니다.
clientCertificates	클라이언트 인증서가 사용하도록 설정된 경우

연결됨

{
    "namespace": "",
    "socketId": "",
}

속성	설명
namespace	소켓의 네임스페이스입니다.
socketId	소켓의 고유 ID입니다.

연결 끊김

{
    "namespace": "",
    "socketId": "",
    "reason": ""
}

속성	설명
namespace	소켓의 네임스페이스입니다.
socketId	소켓의 고유 ID입니다.
reason	연결 닫기 이유 설명입니다.

일반 이벤트

{
    "namespace": "",
    "socketId": "",
    "payload": "",
    "eventName": "",
    "parameters": []
}

속성	설명
namespace	소켓의 네임스페이스입니다.
socketId	소켓의 고유 ID입니다.
payload	Engine.IO 프로토콜의 메시지 페이로드
eventName	요청의 이벤트 이름입니다.
매개 변수	메시지의 매개 변수 목록입니다.

출력 바인딩

출력 바인딩은 현재 다음 기능을 지원합니다.

• 방에 소켓 추가
• 회의실에서 소켓 제거
• 소켓에 메시지 보내기
• 채팅방에 메시지 보내기
• 네임스페이스에 메시지 보내기
• 소켓 연결 끊기

C#

[FunctionName("SocketIOOutput")]
public static async Task<IActionResult> SocketIOOutput(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIO(Hub = "hub")] IAsyncCollector<SocketIOAction> collector)
{
    await collector.AddAsync(SocketIOAction.CreateSendToNamespaceAction("new message", new[] { "arguments" }));
}

attribute

입력 바인딩의 특성은 .입니다 [SocketIO].

특성 속성	설명
허브	클라이언트가 연결해야 하는 허브 이름입니다.
Connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).

JavaScript 모델 v4

import { app, InvocationContext, trigger, output } from "@azure/functions";

const socketio = output.generic({
  type: 'socketio',
  hub: 'hub',
})

export async function newMessage(request: any, context: InvocationContext): Promise<void> {
    context.extraOutputs.set(socketio, {
      actionName: 'sendToNamespace',
      namespace: '/',
      eventName: 'new message',
      parameters: [
        "argument"
      ]
    });
}

// Trigger for new message
app.generic('newMessage', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'new message'
    }),
    extraOutputs: [socketio],
    handler: newMessage
});

구성

특성 속성	설명
type	socketio이어야 합니다.
hub	클라이언트가 연결해야 하는 허브 이름입니다.
connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).

Python 모델 v2

함수에는 항상 트리거 바인딩이 필요합니다. 코드의 예로 TimerTrigger를 사용합니다.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json

app = func.FunctionApp()

@app.timer_trigger(schedule="* * * * * *", arg_name="myTimer", run_on_startup=False,
              use_monitor=False)
@app.generic_output_binding(arg_name="sio", type="socketio", data_type=DataType.STRING, hub="hub")
def new_message(myTimer: func.TimerRequest,
                 sio: func.Out[str]) -> None:
    sio.set(json.dumps({
        'actionName': 'sendToNamespace',
        'namespace': '/',
        'eventName': 'update',
        'parameters': [
            "message"
        ]
    }))

주석

특성 속성	설명
arg_name	출력 바인딩을 나타내는 함수 내 인수의 변수 이름입니다.
type	socketio이어야 합니다.
data_type	DataType.STRING 사용
hub	클라이언트가 연결해야 하는 허브 이름입니다.
connection	Socket.IO 연결 문자열 포함하는 앱 설정의 이름입니다(기본값은 WebPubSubForSocketIOConnectionString).

actions

출력 바인딩은 작업을 사용하여 작업을 수행합니다. 현재 다음 작업을 지원합니다.

AddSocketToRoomAction

{
    "type": "AddSocketToRoom",
    "socketId": "",
    "room": ""
}

RemoveSocketFromRoomAction

{
    "type": "RemoveSocketFromRoom",
    "socketId": "",
    "room": ""
}

SendToNamespaceAction

{
    "type": "SendToNamespace",
    "eventName": "",
    "parameters": [],
    "exceptRooms": []
}

SendToRoomsAction

{
    "type": "SendToRoom",
    "eventName": "",
    "parameters": [],
    "rooms": [],
    "exceptRooms": []
}

SendToSocketAction

{
    "type": "SendToSocket",
    "eventName": "",
    "parameters": [],
    "socketId": ""
}

DisconnectSocketsAction

{
    "type": "DisconnectSockets",
    "rooms": [],
    "closeUnderlyingConnection": false
}