Partekatu bidez

Enlaces de entrada de Azure Web PubSub para Azure Functions

Nuestra extensión proporciona dos enlaces de entrada destinados a necesidades diferentes.

  • WebPubSubConnection

    Para que un cliente pueda conectarse al servicio Azure Web PubSub, debe conocer la dirección URL del punto de conexión del servicio y tener un token de acceso válido. El enlace de entrada WebPubSubConnection genera la información necesaria, por lo que el cliente no necesita controlar la generación de tokens. El token tiene un tiempo limitado y puede autenticar a un usuario específico en una conexión. Por lo tanto, no almacene en caché el token ni compártalo entre clientes. Se puede usar un desencadenador HTTP que funcione con este enlace de entrada para que los clientes recuperen la información de conexión.

  • WebPubSubContext

    Cuando se usa Static Web Apps, HttpTrigger es el único desencadenador admitido. En escenarios de Web PubSub, el WebPubSubContext enlace de entrada ayuda a los usuarios a deserializar las solicitudes HTTP ascendentes del servicio en protocolos de Web PubSub. Por lo tanto, los clientes pueden obtener resultados similares en comparación con WebPubSubTrigger para controlar fácilmente las funciones. Cuando se usa con HttpTrigger, el cliente debe configurar la dirección URL expuesta de HttpTrigger en el controlador de eventos según corresponda.

WebPubSubConnection

Ejemplo

En el ejemplo siguiente se muestra una función de desencadenador HTTP que adquiere información de conexión de Web PubSub mediante el enlace de entrada y la devuelve a través de HTTP. En el ejemplo siguiente, se UserId pasa a través de la parte de consulta de solicitud de cliente, como ?userid={User-A}.

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

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

Cree una carpeta negotiate y actualice negotiate/function.json y copie los siguientes códigos 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"
    }
  ]
}

Defina la función en negotiate/init.py.

import logging

import azure.functions as func

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

Nota:

Los ejemplos completos de este lenguaje están pendientes

Nota:

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

Obtención del identificador de usuario autenticado

Si la función la desencadena un cliente autenticado, puede agregar una notificación del identificador de usuario al token generado. Puede agregar fácilmente la autenticación a una aplicación de función mediante Autenticación de App Service.

Autenticación de App Service establece encabezados HTTP denominados x-ms-client-principal-id y x-ms-client-principal-name que contienen el identificador y el nombre de la entidad de seguridad de cliente del usuario autenticado, respectivamente.

Puede establecer la UserId propiedad del enlace en el valor de cualquier encabezado mediante una expresión de enlace: {headers.x-ms-client-principal-id} o {headers.x-ms-client-principal-name}.

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

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

Cree una carpeta negotiate y actualice negotiate/function.json y copie los siguientes códigos 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"
    }
  ]
}

Defina la función en negotiate/init.py.

import logging

import azure.functions as func

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

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 tabla siguiente se explican las propiedades de configuración del enlace que se establecen en el archivo function.json y el atributo WebPubSubConnection.

Propiedad de function.json Propiedad de atributo Descripción
tipo N/D Se debe establecer en webPubSubConnection
dirección N/D Se debe establecer en in
nombre N/D Nombre de variable utilizado en el código de función para el objeto de enlace de la conexión de entrada.
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.
userId UserId Opcional: valor de la notificación del identificador de usuario que se debe establecer en el token de la clave de acceso.
clientProtocol ClientProtocol Opcional: tipo de protocolo de cliente. Entre los valores válidos se incluyen default y mqtt.
Para los clientes MQTT, debe establecerlo en mqtt.
Para otros clientes, puede omitir la propiedad o establecerla en default.
conexión Conexión Obligatorio: el nombre de la configuración de la aplicación que contiene la cadena de conexión del servicio Web PubSub (el valor predeterminado es "AzureSignalRConnectionString").

Uso

WebPubSubConnection proporciona las siguientes propiedades.

Nombre del enlace Tipo de enlace Descripción
BaseUri Identificador URI Identificador URI de conexión de cliente de Web PubSub.
Identificador URI Identificador URI Identificador URI absoluto de la conexión de Web PubSub; contiene la base generada por AccessToken en la solicitud.
AccessToken cuerda / cadena AccessToken generado basado en la información de servicio y UserId de la solicitud.

WebPubSubConnection proporciona las siguientes propiedades.

Nombre del enlace Descripción
baseUrl Identificador URI de conexión de cliente de Web PubSub.
dirección url Identificador URI absoluto de la conexión de Web PubSub; contiene la base generada por AccessToken en la solicitud.
accessToken AccessToken generado basado en la información de servicio y UserId de la solicitud.

Nota:

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

Más personalización del token generado

Limitado a los tipos de parámetros de enlace no admiten una manera de pasar una lista ni una matriz, no WebPubSubConnection es totalmente compatible con todos los parámetros que tiene el SDK del servidor de parámetros, especialmente roles, y también incluye groups y expiresAfter.

Cuando el cliente necesita agregar roles o retrasar la creación del token de acceso en la función, se recomienda trabajar con el SDK de servidor para C#.

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

Cuando el cliente necesita agregar roles o retrasar la creación del token de acceso en la función, se recomienda trabajar con el SDK de servidor para JavaScript.

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

Nota:

Los ejemplos completos de este lenguaje están pendientes

Nota:

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

WebPubSubContext

Ejemplo

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

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

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 definen en el archivo functions.json y el atributo WebPubSubContext.

Propiedad de function.json Propiedad de atributo Descripción
tipo N/D Se debe establecer en webPubSubContext.
dirección N/D Se debe establecer en in.
nombre N/D Nombre de variable usado en el código de función para la solicitud de Web PubSub de entrada.
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 usará para la protección contra abusos y la validación de firmas. Y el valor se resolverá automáticamente con "WebPubSubConnectionString" 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.

Uso

WebPubSubContext proporciona las siguientes propiedades.

Nombre del enlace Tipo de enlace Descripción Propiedades
solicitud WebPubSubEventRequest Solicitud del cliente, consulte la tabla siguiente para obtener más información. WebPubSubConnectionContext desde el encabezado de solicitud y otras propiedades deserializadas del cuerpo de la solicitud describen a esta, por ejemplo, Reason para DisconnectedEventRequest.
respuesta HttpResponseMessage La extensión genera la respuesta principalmente para AbuseProtection y los casos de error. -
mensaje de error cuerda / cadena Describa los detalles del error al procesar la solicitud ascendente. -
hasError booleano Marca para indicar si se trata de una solicitud ascendente de Web PubSub válida. -
isPreflight booleano Marca para indicar si se trata de una solicitud preparatoria de AbuseProtection. -

Para WebPubSubEventRequest, se deserializa en diferentes clases que proporcionan información diferente sobre el escenario de solicitud. Para PreflightRequest o para casos no válidos, el usuario puede comprobar las marcas IsPreflight y HasError y averiguarlo. Se recomienda devolver la respuesta WebPubSubContext.Response de compilación del sistema directamente o el cliente puede registrar errores a petición. En diferentes escenarios, el cliente puede leer las propiedades de solicitud como se indica a continuación.

Clase derivada Descripción Propiedades
PreflightRequest Se usa en AbuseProtection cuando IsPreflight es true. -
ConnectEventRequest Se usa en el tipo de evento Connect del sistema. Reclamaciones, Consulta, Subprotocolos, Certificados de Cliente
ConnectedEventRequest Se usa en el tipo de evento Connected del sistema. -
UserEventRequest Se usa en el tipo de evento de usuario. Datos, TipoDeDato
DisconnectedEventRequest Se usa en el tipo de evento Disconnected del sistema. Motivo

Nota:

Aunque es WebPubSubContext un enlace de entrada proporciona una forma similar de deserializar la solicitud en HttpTrigger comparación con WebPubSubTrigger, no se admiten las limitaciones, es decir, el estado de conexión posterior a la combinación. El lado del servicio seguirá respetando la respuesta de devolución, pero los usuarios deberán crear la respuesta ellos mismos. Si los usuarios tienen que establecer la respuesta del evento, debe devolver una respuesta HttpResponseMessage que contenga ConnectEventResponse o mensajes del evento del usuario como cuerpo de la respuesta y poner el estado de conexión con la clave ce-connectionstate en el encabezado de respuesta.

  • Last updated on