Gatilho e vinculações do Azure Web PubSub para Azure Functions

Artigo
01/12/2024

Esta referência explica como manipular com eventos do Web PubSub no Azure Functions.

O Web PubSub é um serviço gerenciado do Azure que ajuda os desenvolvedores a criar aplicativos Web facilmente, com recursos em tempo real e padrão de publicação/assinatura.

Ação	Tipo
Executar uma função quando as mensagens chegam como serviço	Associação de gatilho
Associar solicitação ao objeto de destino no gatilho HTTP para solicitações de negociação e de upstream	Associação de entrada
Invocar que o serviço execute ações	Associação de saída

Código-fonte | Pacote | Documentação de referência da API | Documentação do produto | Exemplos

Adicione ao seu aplicativo Functions

Trabalhar com o gatilho e as ligações requer que você consulte o pacote apropriado. O pacote NuGet é usado para bibliotecas de classes .NET, enquanto o pacote de extensão é usado para todos os outros tipos de aplicativos.

Idioma	Adicionar por...	Comentários
C#	Instalar o pacote NuGet, versão pré-lançamento
C# Script, JavaScript, Python, PowerShell	Instalar extensões explicitamente, Usar pacotes de extensão	A extensão de Ferramentas do Azure é recomendada para uso com Visual Studio Code.
Script C# (apenas online no portal do Azure)	Adicionando uma associação	Para atualizar as extensões de associação existentes sem ter que republicar seu aplicativo de funções, confira Atualizar suas extensões.

Conceitos principais

Diagrama mostrando o fluxo de trabalho do serviço Azure Web PubSub trabalhando com Aplicativos de funções.

(1)-(2) associação de entrada WebPubSubConnection com HttpTrigger para gerar conexão de cliente.

(3)-(4) associação de gatilho WebPubSubTrigger ou associação de entrada WebPubSubContext com HttpTrigger para manipular a solicitação de serviço.

(5)-(6) associação de saída WebPubSub para solicitar que o serviço faça algo.

Associação de gatilho

Use o gatilho de função para tratar solicitações do serviço Azure Web PubSub.

WebPubSubTrigger é usado quando você precisa lidar com solicitações do lado do serviço. O padrão do ponto de extremidade do gatilho seria como abaixo, 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>

Captura de tela da obtenção das chaves do sistema da função.

Exemplo

[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. E se EventErrorResponse for retornado, o serviço remove a conexão do cliente.

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

O exemplo a seguir mostra uma função JavaScript do gatilho do Web PubSub.

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

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 maior comparação de prioridade com objetos rest, que se code estiver no retorno, ele será analisado para EventErrorResponse e a conexão do cliente será descartada.

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

Defina a associação de gatilho em 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 maior comparação de prioridade com objetos rest, que se code estiver no retorno, ele será analisado para EventErrorResponse e a conexão do cliente será descartada.

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

Atributos e anotações

Em Bibliotecas de classes do C#, use o atributo WebPubSubTrigger.

Aqui está um atributo WebPubSubTrigger em uma assinatura de método:

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

Para obter um exemplo completo, confira o exemplo em C#.

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 o tipo de evento `system`, 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.` com suporte do sistema, o nome do evento é o nome do evento definido pelo usuário.
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 de aplicativo "WebPubSubConnectionString" por padrão. E `null` significa que a validação não é necessária e sempre tem êxito.

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 abaixo com os parâmetros e tipos disponíveis.

Em uma linguagem em JavaScript com tipo fraco, name em function.json é usado para associar o objeto de gatilho em relação à tabela de mapeamento abaixo. 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 é diferente por diferentes tipos de evento, incluindo classes derivadas `ConnectEventRequest`, `ConnectedEventRequest`, `UserEventRequest` e `DisconnectedEventRequest`
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	-

Associação de entrada

Nossa extensão fornece duas associação de entrada que se direcionam a necessidades diferentes.

WebPubSubConnection

Para permitir que um cliente se conecte ao serviço Azure Web PubSub, ele deve saber o ponto de extremidade de serviço e ter um token de acesso válido. A associação de entrada WebPubSubConnection produz informações necessárias para que o cliente não precise lidar com a geração de token em si. Como o token é limitada pelo tempo e pode ser usado para autenticar um usuário específico para uma conexão, não armazene em cache nem compartilhe o token entre clientes. Um gatilho HTTP que funciona com essa associação de entrada pode ser usado para que os clientes recuperem as informações de conexão.
WebPubSubContext

Ao usar os Aplicativos Web Estáticos, HttpTrigger é o único gatilho com suporte e, no cenário Web PubSub, fornecemos a associação de entrada WebPubSubContext, que ajuda os usuários a desserializar a solicitação http upstream do lado do serviço em protocolos Web PubSub. Portanto, os clientes podem obter resultados semelhantes em comparação com WebPubSubTrigger para facilmente lidar com as funções. Veja exemplos abaixo. Quando usado com HttpTrigger, o cliente requer a configuração adequada da URL exposta do HttpTrigger no manipulador de eventos.

Exemplo – `WebPubSubConnection`

O exemplo a seguir mostra uma função C# que adquire as informações de conexão do Web PubSub usando a associação de entrada e retorna-a via HTTP. No exemplo abaixo, o UserId é passado por meio da parte de consulta de solicitação do cliente como ?userid={User-A}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
    return connection;
}

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

Defina as associações de entrada em function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Defina a função em index.js.

module.exports = function (context, req, connection) {
  context.res = { body: connection };
  context.done();
};

Tokens autenticados

Se a função for disparada por um cliente autenticado, você poderá adicionar uma declaração de ID de usuário ao token gerado. Você pode adicionar facilmente a autenticação a um aplicativo de funções usando Autenticação de Serviço de Aplicativo.

Autenticação do Serviço de Aplicativo define os cabeçalhos HTTP denominados x-ms-client-principal-id e x-ms-client-principal-name que contêm a ID e o nome da entidade de segurança do cliente do usuário autenticado, respectivamente.

É possível definir a propriedade UserId da associação como o valor do cabeçalho usando uma expressão de associação: {headers.x-ms-client-principal-id} ou {headers.x-ms-client-principal-name}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection)
{
    return connection;
}

Observação

Limitado aos tipos de parâmetro de associação não dá suporte a uma maneira de passar lista nem matriz, o WebPubSubConnectionnão dá suporte total com todos os parâmetros que o SDK do servidor tem, especialmente roles, e também inclui groups e expiresAfter. Caso o cliente precise adicionar funções ou atrasar a compilação do token de acesso na função, é sugerido trabalhar com o SDK do servidor para C#.

[FunctionName("WebPubSubConnectionCustomRoles")]
public static async Task<Uri> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest 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);
    return await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
}

Observação

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

Observação

Defina as associações de entrada em function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

Defina a função em index.js.

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

module.exports = async function (context, req) {
  const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
  let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  context.res = { body: token.url };
  context.done();
};

Exemplo – `WebPubSubContext`

O exemplo a seguir mostra uma função C# que adquire as informações de solicitação de upstream do Web PubSub usando a associação de entrada no tipo de evento connect e a retorna via HTTP.

[FunctionName("WebPubSubContextInputBinding")]
public static object Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubContext] WebPubSubContext wpsContext)
{
    // in the case request is a preflight or invalid, directly return prebuild response by extension.
    if (wpsContext.IsPreflight || wpsContext.HasError)
    {
        return wpsContext.Response;
    }
    var request = wpsContext.Request as ConnectEventRequest;
    var response = new ConnectEventResponse
    {
        UserId = wpsContext.Request.ConnectionContext.UserId
    };
    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 };
    }
});

Defina as associações de entrada em function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubContext",
      "name": "wpsContext",
      "direction": "in"
    }
  ]
}

Defina a função em index.js.

module.exports = async function (context, req, wpsContext) {
  // in the case request is a preflight or invalid, directly return prebuild response by extension.
  if (wpsContext.hasError || wpsContext.isPreflight)
  {
    return wpsContext.response;
  }
  // return an http response with connect event response as body.
  return { body: {"userId": wpsContext.connectionContext.userId} };
};

Configuração

WebPubSubConnection

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

Propriedade function.json	Propriedade de atributo	Descrição
tipo	N/D	Precisa ser definida como `webPubSubConnection`
direction	N/D	Precisa ser definida como `in`
name	N/D	Nome da variável usada no código de função para o objeto de associação de conexão de entrada.
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.
userId	UserId	Opcional – o valor da declaração do identificador de usuário a ser definida no token de chave de acesso.
connection	Conexão	Obrigatório - o nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do Web PubSub (o padrão é "WebPubSubConnectionString").

WebPubSubContext

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

Propriedade function.json	Propriedade de atributo	Descrição
tipo	n/d	Deve ser definido como `webPubSubContext`.
direction	n/d	Deve ser definido como `in`.
name	N/D	Nome da variável usada no código de função para a solicitação Web PubSub de entrada.
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 Proteção contra abuso e Validação de assinatura. O valor é resolvido automaticamente com "WebPubSubConnectionString" por padrão. E `null` significa que a validação não é necessária e sempre tem êxito.

Uso

WebPubSubConnection

WebPubSubConnection fornece as propriedades abaixo.

Nome da associação	Tipo de associação	Descrição
BaseUri	Uri	URL de conexão de cliente do Web PubSub.
Uri	Uri	O URI absoluto da conexão Web PubSub contém a base gerada `AccessToken` na solicitação.
AccessToken	string	Gerado `AccessToken` com base na solicitação do UserId e informações de serviço.

WebPubSubConnection fornece as propriedades abaixo.

Nome da associação	Descrição
baseUrl	URL de conexão de cliente do Web PubSub.
url	O URI absoluto da conexão Web PubSub contém a base gerada `AccessToken` na solicitação.
accessToken	Gerado `AccessToken` com base na solicitação do UserId e informações de serviço.

WebPubSubConnection fornece as propriedades abaixo.

Nome da associação	Descrição
baseUrl	URL de conexão de cliente do Web PubSub.
url	O URI absoluto da conexão Web PubSub contém a base gerada `AccessToken` na solicitação.
accessToken	Gerado `AccessToken` com base na solicitação do UserId e informações de serviço.

WebPubSubContext

WebPubSubContext fornece as propriedades abaixo.

Nome da associação	Tipo de associação	Descrição	Propriedades
solicitação	`WebPubSubEventRequest`	Solicitação do cliente, consulte a tabela abaixo para obter detalhes.	`WebPubSubConnectionContext` do cabeçalho de solicitação e outras propriedades desserializadas do corpo da solicitação descrevem a solicitação, por exemplo, `Reason` para \`DisconnectedEventRequest`.
response	`HttpResponseMessage`	A extensão cria a resposta principalmente para `AbuseProtection` e casos de erros.	-
errorMessage	string	Descreve os detalhes do erro ao processar a solicitação de upstream.	-
hasError	bool	Sinalizador para indicar se é uma solicitação de upstream do Web PubSub válida.	-
isPreflight	bool	Sinalizador para indicar se é uma solicitação de simulação de `AbuseProtection`.	-

Em WebPubSubEventRequest, ela é desserializada para classes diferentes que fornecem informações diferentes sobre o cenário de solicitação. Em PreflightRequest ou casos inválidos, o usuário pode verificar os sinalizadores IsPreflight e HasError para saber. É recomendável retornar a resposta de compilação do sistema WebPubSubContext.Response diretamente ou o cliente pode registrar em log os erros sob demanda. Em cenários diferentes, o cliente pode ler as propriedades da solicitação conforme abaixo.

Classe Derivada	Descrição	Propriedades
`PreflightRequest`	Usado em `AbuseProtection` quando `IsPreflight` for true	-
`ConnectEventRequest`	Usado no tipo de evento do sistema `Connect`	Declarações, Consulta, Subprotocols, ClientCertificates
`ConnectedEventRequest`	Usado no tipo de evento do sistema `Connected`	-
`UserEventRequest`	Usado no tipo de evento de usuário	Data, DataType
`DisconnectedEventRequest`	Usado no tipo de evento do sistema `Disconnected`	Motivo

Observação

Embora o WebPubSubContext seja uma entrada, a associação fornece uma opção de desserialização de solicitação semelhante em HttpTrigger comparando com WebPubSubTrigger, existem limitações, ou seja, o estado de conexão após a mesclagem não é suportado. A resposta de retorno ainda é respeitada pelo lado do serviço, mas os usuários precisam criar a resposta por conta própria. Se os usuários precisam definir a resposta do evento, você deve retornar um HttpResponseMessage contém ConnectEventResponse ou mensagens do evento de usuário como corpo da resposta e colocar o estado da conexão com a chave ce-connectionstate no cabeçalho de resposta.

Associação de saída

Use a associação de saída do Web PubSub para invocar o serviço do Azure Web PubSub para fazer algo. Você pode transmitir uma mensagem para:

Todos os clientes conectados
Clientes conectados autenticados como um usuário específico
Clientes conectados ingressaram em um grupo específico
Uma conexão de cliente específica

A associação de saída também permite gerenciar clientes e grupos, assim como conceder/revogar permissões que direcionam a connectionId específica com grupo.

Adicionar conexão ao grupo
Adicionar usuário ao grupo
Remover conexão de um grupo
Remover o usuário de um grupo
Remover usuário de todos os grupos
Fechar todas as conexões de cliente
Fechar uma conexão de cliente específica
Fechar conexões em um grupo
Conceder permissão de uma conexão
Revogar permissão de uma conexão

Para obter informações sobre a instalação e detalhes de configuração, confira a visão geral.

Exemplo

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

const { app, output } = require('@azure/functions');
const wpsMsg = output.generic({
    type: 'webPubSub',
    name: 'actions',
    hub: '<hub>',
});

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [wpsMsg],
    handler: async (request, context) => {
        context.extraOutputs.set(wpsMsg, [{
            "actionName": "sendToAll",
            "data": `Hello world`,
            "dataType": `text`
        }]);
    }
});

Defina as associações em functions.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

Defina a função em index.js.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "hello",
    "dataType": "text"
  };
  context.done();
}

WebPubSubAction

WebPubSubAction é o tipo abstrato base das associações de saída. Os tipos derivados representam o servidor de ação que deseja que o serviço para invocar.

Na linguagem C#, fornecemos alguns métodos estáticos em WebPubSubAction para ajudar a descobrir as ações disponíveis. Por exemplo, o usuário pode criar o SendToAllAction por chamada WebPubSubAction.CreateSendToAllAction().

Classe Derivada	Propriedades
`SendToAllAction`	Data, DataType, Excluded
`SendToGroupAction`	Group, Data, DataType, Excluded
`SendToUserAction`	UserId, Data, DataType
`SendToConnectionAction`	ConnectionId, Data, DataType
`AddUserToGroupAction`	UserId, Group
`RemoveUserFromGroupAction`	UserId, Group
`RemoveUserFromAllGroupsAction`	UserId
`AddConnectionToGroupAction`	ConnectionId, Group
`RemoveConnectionFromGroupAction`	ConnectionId, Group
`CloseAllConnectionsAction`	Excluded, Reason
`CloseClientConnectionAction`	ConnectionId, Reason
`CloseGroupConnectionsAction`	Group, Excluded, Reason
`GrantPermissionAction`	ConnectionId, Permission, TargetName
`RevokePermissionAction`	ConnectionId, Permission, TargetName

Em linguagem de tipo fraco como javascript, actionName é o parâmetro de chave para resolver os tipos, as ações disponíveis são listadas como abaixo.

ActionName	Propriedades
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Importante

A propriedade de dados da mensagem nas ações relacionadas à mensagem de envio deve ser string se o tipo de dados for definido como json ou text para evitar a ambiguidade da conversão de dados. Use JSON.stringify() para converter o objeto JSON necessário. Isso é aplicado a todo lugar usando a propriedade mensagem, por exemplo, UserEventResponse.Data trabalhando com WebPubSubTrigger.

Quando o tipo de dados é definido como binary, é permitido aproveitar a associação naturalmente compatível dataType como binary configurado no function.json, consulte Definições de gatilho e associação para obter mais detalhes.

Em linguagem de tipo fraco como javascript, actionName é o parâmetro de chave para resolver os tipos, as ações disponíveis são listadas como abaixo.

ActionName	Propriedades
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Importante

Configuração

WebPubSub

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

Propriedade function.json	Propriedade de atributo	Descrição
tipo	N/D	Precisa ser definida como `webPubSub`
direction	N/D	Precisa ser definida como `out`
name	N/D	O nome da variável usada no código de função para a associação de saída do objeto.
hub	Hub	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.
connection	Conexão	O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do Web PubSub (o padrão é "WebPubSubConnectionString").

Solução de problemas

Configuração do registro em log do console

Também será possível habilitar o registro em log do console facilmente se quiser obter detalhes das solicitações que está fazendo ao serviço.

Próximas etapas

Use estes recursos para começar a criar seu aplicativo:

Tutorial: Publicar e assinar mensagens no Azure Web PubSub

Tutorial: criar uma sala de chat simples com o Azure Web PubSub

Tutorial: Usar um subprotocolo com suporte do serviço para streaming de cliente

Tutorial: Criar um chat sem servidor com o Azure Functions e o Web PubSub

Tutorial: Configurar um ouvinte de eventos

Experimentar demonstrações ao vivo

Explorar mais exemplos do Azure Web PubSub

Compartilhar via

Gatilho e vinculações do Azure Web PubSub para Azure Functions

Adicione ao seu aplicativo Functions

Conceitos principais

Associação de gatilho

Exemplo

Atributos e anotações

Configuração

Usos

Retorno de resposta

Associação de entrada

Exemplo – `WebPubSubConnection`

Tokens autenticados

Exemplo – `WebPubSubContext`

Configuração

WebPubSubConnection

WebPubSubContext

Uso

WebPubSubConnection

WebPubSubContext

Associação de saída

Exemplo

WebPubSubAction

Configuração

WebPubSub

Solução de problemas

Configuração do registro em log do console

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Gatilho e vinculações do Azure Web PubSub para Azure Functions

Adicione ao seu aplicativo Functions

Conceitos principais

Associação de gatilho

Exemplo

Atributos e anotações

Configuração

Usos

Retorno de resposta

Associação de entrada

Exemplo – WebPubSubConnection

Tokens autenticados

Exemplo – WebPubSubContext

Configuração

WebPubSubConnection

WebPubSubContext

Uso

WebPubSubConnection

WebPubSubContext

Associação de saída

Exemplo

WebPubSubAction

Configuração

WebPubSub

Solução de problemas

Configuração do registro em log do console

Próximas etapas

Comentários

Recursos adicionais

Exemplo – `WebPubSubConnection`

Exemplo – `WebPubSubContext`