Enlace de desencadenador de Azure Web PubSub para Azure Functions

Use el desencadenador azure Web PubSub para controlar eventos de cliente desde el servicio Azure Web PubSub.

El patrón de punto de conexión del desencadenador sería el siguiente, que debe establecerse en el lado del servicio Web PubSub (Portal: configuración:> controlador de eventos -> Plantilla de dirección URL). En el patrón de punto de conexión, el elemento de consulta code=<API_KEY> es OBLIGATORIO cuando se usa la aplicación de funciones de Azure por motivos de seguridad. La clave se puede encontrar en Azure Portal. Busque el recurso de la aplicación de funciones y vaya Functions ->Claves de la aplicación ->Claves del sistema ->webpubsub_extension después de implementar la aplicación de funciones en Azure. Sin embargo, esta clave no es necesaria para trabajar con funciones locales.

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

Ejemplo

En el ejemplo siguiente se muestra cómo controlar los eventos de usuario de los clientes.

Modelo de trabajo aislado

[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 de proceso

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

El enlace WebPubSubTrigger también admite el valor devuelto en escenarios de sincronización, como, por ejemplo, Connectdel sistema y los eventos de usuario, cuando el servidor puede comprobar y denegar la solicitud de cliente o enviar mensajes directamente al autor de la llamada. El evento Connect respeta ConnectEventResponse y EventErrorResponse, y el evento de usuario respeta UserEventResponse y EventErrorResponse; los tipos rest que no coincidan con el escenario actual se ignoran.

Modelo de trabajo aislado

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

Modelo de proceso

[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 el enlace de desencadenador en function.json.

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

Defina la función en 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);
}

El enlace WebPubSubTrigger también admite el valor devuelto en escenarios de sincronización, como, por ejemplo, Connectdel sistema y los eventos de usuario, cuando el servidor puede comprobar y denegar la solicitud de cliente o enviar mensajes directamente al cliente de la solicitud. En el lenguaje débilmente tipado de JavaScript, se deserializará en relación con las claves de objeto. Y EventErrorResponse tiene la prioridad más alta en comparación con los objetos rest, que si code está en la devolución, se analiza en 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"
  };
}

Nota:

Los ejemplos completos de este lenguaje están pendientes.

Nota:

Todavía no se admiten las extensiones de Web PubSub para Java.

Configuración

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad de function.json	Propiedad de atributo	Descripción
tipo	N/D	Requerida: se debe establecer en webPubSubTrigger.
dirección	N/D	Requerida: se debe establecer en in.
nombre	N/D	Requerido: el nombre de la variable que se utiliza en el código de función para el parámetro que recibe los datos del evento.
concentrador	Centro	Requerido: el valor debe establecerse en el nombre del centro de Web PubSub para la función que se va a desencadenar. Se permite establecer el valor en el atributo como prioridad más alta o se puede establecer en la configuración de la aplicación como un valor global.
tipoDeEvento	WebPubSubEventType	Requerido: el valor debe establecerse en el tipo de evento de los mensajes para la función que se va a desencadenar. El valor debe ser user o system.
eventName	Nombre del evento	Requerido: el valor debe establecerse en el evento de los mensajes para la función que se va a desencadenar. Para system el tipo de evento, el nombre del evento debe estar en connect, connected, disconnected. Para subprotocolos definidos por el usuario, el nombre del evento es message. En el caso del subprotocolo json.webpubsub.azure.v1.admitido por el sistema, el nombre del evento es el nombre de evento definido por el usuario.
clientProtocols	ClientProtocols	Opcional: especifica qué protocolo de cliente puede desencadenar las funciones de desencadenador de Web PubSub. Los siguientes valores que no distinguen mayúsculas de minúsculas son válidos: all: acepta todos los protocolos de cliente. Valor predeterminado. webPubSub: solo acepta protocolos de Web PubSub. mqtt: solo acepta protocolos MQTT.
conexión	Conexión	Opcional: el nombre de una configuración de aplicación o una colección de configuraciones que especifica el servicio Azure Web PubSub ascendente. El valor se usa para la validación de firmas. Y el valor se resuelve automáticamente con la configuración de WebPubSubConnectionString la aplicación de forma predeterminada. Y null significa que la validación no es necesaria y siempre se realiza correctamente.

Importante

Para una seguridad óptima, la aplicación de funciones debe usar identidades administradas al conectarse al servicio Web PubSub en lugar de usar una cadena de conexión, que contiene una clave secreta compartida. Para obtener más información, consulte Autorización de una solicitud de identidad administrada mediante microsoft Entra ID.

Usos

En C#, WebPubSubEventRequest es el parámetro de enlace reconocido de tipo, los parámetros rest están enlazados por el nombre del parámetro. Compruebe la tabla siguiente para ver los parámetros y tipos disponibles.

En lenguaje débilmente tipado como JavaScript, name en function.json se usa para enlazar el objeto desencadenador con respecto a la tabla de asignación siguiente. Asimismo, respetará dataType en function.json para convertir el mensaje en consecuencia cuando name esté establecido en data como el objeto de enlace para la entrada del desencadenador. Todos los parámetros se pueden leer desde context.bindingData.<BindingName>y se convertirán a JObject.

Nombre del enlace	Tipo de enlace	Descripción	Propiedades
solicitud	WebPubSubEventRequest	Describe la solicitud ascendente	La propiedad difiere según los distintos tipos de eventos, incluidas las clases derivadas ConnectEventRequest, MqttConnectEventRequest, ConnectedEventRequestMqttConnectedEventRequest, , UserEventRequest, DisconnectedEventRequesty MqttDisconnectedEventRequest.
connectionContext	WebPubSubConnectionContext	Información de solicitud común	EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
datos	BinaryData,string,,Stream,byte[]	Solicitud de datos de mensaje del cliente en el evento message de usuario	-
Tipo de dato	WebPubSubDataType	Solicitud de mensaje de dataType, que admite binary, text, json	-
reclamaciones	IDictionary<string, string[]>	Notificaciones del usuario en la solicitud connect del sistema	-
consulta	IDictionary<string, string[]>	Consulta del usuario en la solicitud connect del sistema	-
subprotocolos	IList<string>	Subprotocolos disponibles en la solicitud connect del sistema	-
clientCertificates	IList<ClientCertificate>	Lista de huellas digitales de certificado de clientes en la solicitud connect del sistema	-
razón	string	Motivo de la solicitud disconnected del sistema	-

Importante

En C#, varios tipos admitidos parámetro DEBEN colocarse en el primero, es decir request, o data que no sea el tipo predeterminado BinaryData para que el enlace de función sea correcto.

Devolución de respuesta

WebPubSubTrigger respeta la respuesta devuelta por el cliente para los eventos síncronos de connect y el evento del usuario. Solo se devuelve la respuesta coincidente al servicio; de lo contrario, se omite. Además, el objeto devuelto WebPubSubTrigger admite a los usuarios que realicen SetState() y ClearStates() para administrar los metadatos de la conexión. Y la extensión combinará los resultados del valor devuelto con los originales de la solicitud WebPubSubConnectionContext.States. El valor de la clave existente se sobrescribe y se agrega el valor de la nueva clave.

Tipo devuelto	Descripción	Propiedades
ConnectEventResponse	Respuesta para el evento connect	Grupos, roles, UserId, Subprotocolo
UserEventResponse	Respuesta para el evento de usuario	DataType, Data
EventErrorResponse	Respuesta de error para el evento de sincronización	Code, ErrorMessage
*WebPubSubEventResponse	Tipo de respuesta base de los admitidos que se usan para casos de devolución inciertos.	-