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.
direction	N/D	Obrigatório – deve ser definido como in.
name	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	Hub	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.
eventType	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	EventName	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.
connection	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.

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	EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
data	BinaryData,string,Stream,byte[]	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	-
reason	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	-