Associação de gatilho do Azure Web PubSub para o Azure Functions

Use o gatilho do Azure Web PubSub para lidar com eventos de cliente do serviço Azure Web PubSub.

O padrão de ponto de extremidade do gatilho seria o seguinte, que deve ser definido no lado do serviço Web PubSub (Portal: configurações –> manipulador de eventos –> Modelo de URL). No padrão do ponto de extremidade, a parte de consulta code=<API_KEY> é NECESSÁRIA quando você está usando o Aplicativo de Funções do Azure por motivos desegurança. A chave pode ser encontrada no portal do Azure. Encontre o recurso do aplicativo de funções e navegue até Funções ->Chaves do Aplicativo ->Sistema de Chaves ->webpubsub_extension depois de implantar o aplicativo de funções no Azure. No entanto, essa chave não é necessária quando se está trabalhando com funções locais.

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

Exemplo

O exemplo a seguir mostra como lidar com eventos de usuário de clientes.

Modelo de trabalho isolado

[Function("Broadcast")]
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}");
}

Modelo em processo

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

A associação WebPubSubTrigger também dá suporte ao valor de retorno em cenários sincronizados, por exemplo, sistema Connect e evento de usuário, quando o servidor pode verificar e negar a solicitação do cliente ou enviar mensagens diretamente ao chamador. O evento Connect respeita ConnectEventResponse e EventErrorResponse, e o evento de usuário respeita UserEventResponse e EventErrorResponse, os tipos rest que não corresponderem ao cenário atual são ignorados.

Modelo de trabalho isolado

[Function("Broadcast")]
public static UserEventResponse Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return new UserEventResponse("[SYSTEM ACK] Received.");
}

Modelo em processo

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

Modelo v4

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

Modelo v3

Defina a associação do gatilho no function.json.

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

Defina a função em 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);
}

A associação WebPubSubTrigger também dá suporte ao valor de retorno em cenários sincronizados, por exemplo, sistema Connect e evento de usuário, quando o servidor pode verificar e negar a solicitação do cliente ou enviar mensagem diretamente à solicitação do cliente. Na linguagem em JavaScript com tipo fraco, ela é desserializada em relação às chaves de objeto. E EventErrorResponse tem a prioridade mais alta em comparação com objetos rest, que se code estiver no retorno, então é analisado para EventErrorResponse.

Modelo v4

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

Modelo v3

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

Observação

Amostras completas para este idioma estão pendentes.

Observação

As extensões Web PubSub para Java ainda não são suportadas.

Configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json	Propriedade de atributo	Descrição
tipo	N/D	Obrigatório – deve ser definido como webPubSubTrigger.
direção	N/D	Obrigatório – deve ser definido como in.
nome	N/D	Obrigatório - o nome da variável usado no código de função para o parâmetro que recebe os dados de eventos.
hub	Núcleo	Obrigatório – o valor deve ser definido como o nome do hub do Web PubSub para que a função seja acionada. Damos suporte para definir o valor no atributo como prioridade mais alta ou pode ser definido nas configurações do aplicativo como um valor global.
tipo de evento	WebPubSubEventType	Obrigatório – o valor deve ser definido como o tipo de evento das mensagens para que a função seja acionada. O valor deve ser user ou system.
eventName	Nome do Evento	Obrigatório – o valor deve ser definido como o evento das mensagens para que a função seja acionada. Para system o tipo de evento, o nome do evento deve estar em connect, connected, disconnected. Para subprotocolos definidos pelo usuário, o nome do evento é message. Para o subprotocolo json.webpubsub.azure.v1.suportado pelo sistema, o nome do evento é o nome do evento definido pelo usuário.
protocolos de cliente	Protocolos de cliente	Opcional – especifica qual protocolo de cliente pode disparar as funções de gatilho do Web PubSub. Os seguintes valores que não diferenciam maiúsculas de minúsculas são válidos: all: Aceita todos os protocolos de cliente. Valor padrão. webPubSub: aceita apenas protocolos Web PubSub. mqtt: Aceita apenas protocolos MQTT.
conexão	Conexão	Opcional - o nome de uma coleção de configurações de aplicativo ou de configuração que especifica o serviço do Azure Web PubSub upstream. O valor é usado para validação de assinatura. E o valor é resolvido automaticamente com as configurações WebPubSubConnectionString do aplicativo por padrão. E null significa que a validação não é necessária e sempre é bem-sucedida.

Importante

Para obter a segurança ideal, seu aplicativo de funções deve usar identidades gerenciadas ao se conectar ao serviço Web PubSub em vez de usar uma cadeia de conexão, que contém uma chave secreta compartilhada. Para obter mais informações, consulte Autorizar uma solicitação de identidade gerenciada usando a ID do Microsoft Entra.

Usos

No C#, WebPubSubEventRequest é o tipo de parâmetro de associação reconhecido, os parâmetros rest são limitados pelo nome do parâmetro. Verifique a tabela a seguir para obter os parâmetros e tipos disponíveis.

Em linguagem fracamente tipada como JavaScript, name in function.json é usado para vincular o objeto de gatilho em relação à tabela de mapeamento a seguir. E respeita dataType emfunction.json para converter a mensagem de acordo quando name for definido como data o objeto de associação para entrada de gatilho. Todos os parâmetros podem ser lidos de context.bindingData.<BindingName> e são convertidos para JObject.

Nome da associação	Tipo de associação	Descrição	Propriedades
solicitação	WebPubSubEventRequest	Descreve a solicitação upstream	A propriedade difere por diferentes tipos de evento, incluindo classes ConnectEventRequestderivadas , MqttConnectEventRequest, ConnectedEventRequest, MqttConnectedEventRequestUserEventRequest, , DisconnectedEventRequest, e MqttDisconnectedEventRequest.
connectionContext	WebPubSubConnectionContext	Informações comuns de solicitação	TipoDeEvento, NomeDoEvento, Hub, IdDeConexao, IdDoUsuario, Cabecalhos, Origem, Assinatura, Estados
dados	BinaryData,string,Streambyte[]	Dados da mensagem de solicitação do cliente no evento message de usuário	-
Datatype	WebPubSubDataType	Solicitar dataType de mensagem, que dá suporte a binary, text, json	-
declarações	IDictionary<string, string[]>	Declarações de usuário na solicitação connect de sistema	-
consulta	IDictionary<string, string[]>	Consulta de usuário na solicitação connect de sistema	-
subprotocolos	IList<string>	Subprotocolos disponíveis na solicitação connect de sistema	-
clientCertificates	IList<ClientCertificate>	Uma lista de impressão digital do certificado de clientes na solicitação connect de sistema	-
razão	string	Motivo na solicitação disconnected de sistema	-

Importante

No C#, vários tipos de parâmetro com suporte DEVEM ser colocados no primeiro, ou seja, request ou data diferente do tipo padrão BinaryData para fazer a associação de função corretamente.

Retorno de resposta

WebPubSubTrigger respeita a resposta retornada pelo cliente para eventos síncronos do connect e do evento de usuário. Somente a resposta correspondente é enviada de volta ao serviço, caso contrário, ela é ignorada. Além disso, o objeto de retorno WebPubSubTrigger dá suporte a usuários para SetState() e ClearStates() gerenciar os metadados da conexão. E a extensão mescla os resultados do valor de retorno com os originais da solicitação WebPubSubConnectionContext.States. O valor na chave existente é substituído e o valor na nova chave é adicionado.

Tipo de retorno	Descrição	Propriedades
ConnectEventResponse	Resposta para evento connect	Grupos, Funções, UserId, Subprotocolo
UserEventResponse	Resposta para o evento do usuário	DataType, Data
EventErrorResponse	Resposta de erro para o evento de sincronização	Código, ErrorMessage
*WebPubSubEventResponse	Tipo de resposta base dos com suporte usados para casos de retorno incertos	-