Gatilho e ligações do Azure Web PubSub para as Azure Functions

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

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

Ação	Tipo
Executar uma função quando as mensagens chegam do serviço	Vinculação de gatilho
Vincular solicitação ao objeto de destino sob gatilho HTTP para negociação e solicitações upstream	Vinculação de entrada
Invocar serviço para realizar ações	Vinculação de saída

Código-fontePacoteDocumentação de referência da APIDocumentação do produtoExemplos

Adicionar à sua aplicação de funções

Para trabalhar com o acionador e as associações, é necessário referir o pacote apropriado. O pacote NuGet é usado para bibliotecas de classes .NET, enquanto um pacote de extensão é usado para todos os outros tipos de aplicativos.

Linguagem	Adicionar através de...
C#	Instalar o pacote NuGet, versão específica de destino
JavaScript, Python, PowerShell, script C# (somente portal do Azure)	Utilize pacotes de extensões (recomendado), instale extensões explicitamente

Conceitos-chave

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

(3)-(4) WebPubSubTrigger acionar a ligação ou WebPubSubContext a ligação de entrada com HttpTrigger para lidar com a solicitação de serviço.

(5)-(6) WebPubSub ligação de saída para solicitar que o serviço realize uma ação.

Vinculação de gatilho

Use o gatilho de função para lidar com 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 de 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 de ponto de extremidade, a parte de consulta code=<API_KEY> é NECESSÁRIA quando se utiliza o Azure Function App por motivos de segurança. A chave pode ser encontrada no portal do Azure. Encontre o seu recurso de aplicação de função e navegue até Funções ->Chaves de aplicação ->Chaves do sistema ->webpubsub_extension após a implementação da aplicação de função no Azure. No entanto, essa chave não é necessária quando você está trabalhando com funções locais.

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

Exemplo

C#

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

WebPubSubTrigger A vinculação também oferece suporte ao valor de retorno em cenários de sincronização, por exemplo, evento do sistema Connect e do usuário, quando o servidor pode verificar e negar a solicitação do cliente ou enviar mensagens diretamente para o chamador. Connect O evento respeita ConnectEventResponse e EventErrorResponse; o evento do utilizador respeita UserEventResponse e EventErrorResponse; os tipos restantes que não correspondem ao cenário atual são ignorados. E se EventErrorResponse for retornado, o serviço descarta 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);
}

Modelo JavaScript v4

O exemplo a seguir mostra uma função JavaScript de gatilho 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);
    }
});

WebPubSubTrigger A vinculação também oferece suporte ao valor de retorno em cenários de sincronização, por exemplo, evento do sistema Connect e do utilizador, quando o servidor pode verificar e negar a solicitação do cliente, ou enviar uma mensagem diretamente para o cliente que fez a solicitação. Na linguagem JavaScript fracamente tipada, ela é desserializada em relação às chaves de objeto. E EventErrorResponse tem a prioridade mais alta em comparação com os restantes objetos, de modo que se code estiver no retorno, ele é analisado em EventErrorResponse e a conexão do cliente é terminada.

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

Modelo JavaScript v3

Defina a ligação de gatilho em function.json.

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

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

WebPubSubTrigger A vinculação também oferece suporte ao valor de retorno em cenários de sincronização, por exemplo, o evento de sistema Connect e de utilizador, quando o servidor pode verificar e negar a solicitação do cliente ou enviar mensagem diretamente para o cliente de solicitação. Na linguagem JavaScript, que é fracamente tipada, a desserialização é feita com base nas chaves do objeto. E EventErrorResponse tem a prioridade mais alta em comparação com outros objetos REST, de modo que se code estiver no retorno, então ele é processado por EventErrorResponse e a conexão do cliente é encerrada.

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

Atributos e anotações

Em bibliotecas de classes C#, use o atributo WebPubSubTrigger .

Aqui está um WebPubSubTrigger atributo 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, consulte Exemplo de C#.

Configuração

A tabela a seguir explica as propriedades de configuração de associação definidas 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 usada no código de função para o parâmetro que recebe os dados do evento.
hub	Núcleo	Obrigatório - o valor deve ser definido como o nome do hub Web PubSub para que a função seja acionada. Suportamos definir o valor no atributo como prioridade mais alta, ou ele pode ser definido nas configurações do aplicativo como um valor global.
TipoDeEvento	WebPubSubEventType	Obrigatório - o valor deve ser definido como o tipo de evento de mensagens para que a função seja acionada. O valor deve ser user ou system.
nome_do_evento	Nome do Evento	Obrigatório - o valor deve ser definido como o evento de 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.
conexão	Conexão	Opcional - o nome de definições de aplicativo ou de uma coleção de definições que especifica o serviço Azure Web PubSub upstream. O valor é usado para validação de assinatura. E o valor é resolvido automaticamente com as configurações do aplicativo "WebPubSubConnectionString" por padrão. E null significa que a validação não é necessária e sempre bem-sucedida.

Utilizações

Em C#, WebPubSubEventRequest é um parâmetro de ligação reconhecido por tipo; os parâmetros restantes são vinculados pelo nome do parâmetro. Verifique a tabela abaixo dos parâmetros e tipos disponíveis.

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

Nome da vinculação	Tipo de Ligação	Descrição	Propriedades
pedido	WebPubSubEventRequest	Descreve a solicitação upstream	A propriedade varia por diversos tipos de eventos, incluindo classes derivadas ConnectEventRequest, ConnectedEventRequest, UserEventRequest e DisconnectedEventRequest
contextoDeConexão	WebPubSubConnectionContext	Pedido comum de informações	EventType, EventName, Hub, ConnectionId, UserId, Cabeçalhos, Origem, Assinatura, Estados
dados	BinaryData,string,Stream,byte[]	Solicitar dados de mensagem do cliente no evento do usuário message	-
Tipo de dados	WebPubSubDataType	Tipo de dados da mensagem de pedido, que suporta binary, text, json	-
afirmações	IDictionary<string, string[]>	Declarações do usuário na solicitação do sistema connect	-
consulta	IDictionary<string, string[]>	Consulta do usuário na solicitação do sistema connect	-
Subprotocolos	IList<string>	Subprotocolos disponíveis na solicitação do sistema connect	-
clientCertificados	IList<ClientCertificate>	Uma lista de impressões digitais de certificados de clientes no pedido do sistema connect	-
razão	string	Motivo na solicitação do sistema disconnected	-

Importante

Em C#, vários tipos de parâmetros suportados DEVEM ser colocados como o primeiro, ou seja, request, data diferente do tipo padrão BinaryData, para que a função seja vinculada corretamente.

Resposta de retorno

WebPubSubTrigger respeita a resposta retornada do cliente para eventos síncronos de connect e evento do usuário. Apenas a resposta correspondente é enviada de volta ao serviço, caso contrário, é ignorada. Além disso, WebPubSubTrigger o objeto de retorno suporta usuários para SetState() e ClearStates() para gerenciar os metadados para a 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 ao evento connect	Grupos, Funções, UserId, Subprotocolo
UserEventResponse	Resposta para evento do usuário	DataType, Dados
EventErrorResponse	Resposta de erro para o evento de sincronização	Código, MensagemDeErro
*WebPubSubEventResponse	Tipo de resposta de base dos suportados usados para casos de retorno incerto	-

Vinculação de entrada

Nossa extensão fornece duas ligações de entrada direcionadas para necessidades diferentes.

• WebPubSubConnection

  Para permitir que um cliente se conecte ao Serviço Azure Web PubSub, ele deve saber a URL do ponto de extremidade do serviço e um token de acesso válido. A WebPubSubConnection ligação de entrada produz as informações necessárias, portanto, o cliente não precisa lidar com essa geração de token em si. Como o token é limitado no tempo e pode ser usado para autenticar um usuário específico em uma conexão, não armazene o token em cache ou compartilhe-o entre clientes. Um gatilho HTTP trabalhando com esta associação de entrada pode ser usado para os clientes obterem as informações de conexão.

• WebPubSubContext

  Ao utilizar o Static Web Apps, HttpTrigger é o único gatilho suportado e no cenário Web PubSub, fornecemos a ligação de entrada WebPubSubContext, que ajuda os utilizadores a desserializar a solicitação HTTP upstream do lado do serviço, sob os protocolos Web PubSub. Assim, os clientes podem obter resultados semelhantes em comparação com WebPubSubTrigger e manusear facilmente em funções. Veja exemplos abaixo. Quando usado com HttpTrigger, o cliente precisa configurar a HttpTrigger URL exposta no manipulador de eventos de acordo.

Exemplo - WebPubSubConnection

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

C#

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

Modelo JavaScript v4

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

Modelo JavaScript v3

Defina 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"
    }
  ]
}

Definir função em index.js.

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

Tokens autenticados

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

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

Você pode definir a propriedade UserId da associação para o valor de qualquer cabeçalho usando uma expressão de ligaçã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;
}

C#

Nota

Os tipos de parâmetros de vinculação limitados não suportam uma forma de passar lista nem matriz, o WebPubSubConnection não é totalmente suportado com todos os parâmetros que o SDK do servidor possui, especialmente roles, além de incluir groups e expiresAfter. Caso o cliente precise adicionar funções ou atrasar a criação do token de acesso na função, sugere-se 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);
}

Modelo JavaScript v4

Nota

Os tipos de parâmetros de vinculação limitados não suportam uma forma de passar lista nem matriz, o WebPubSubConnection não é totalmente suportado com todos os parâmetros que o SDK do servidor possui, especialmente roles, além de incluir groups e expiresAfter. Caso o cliente precise adicionar funções ou atrasar a criação do token de acesso na função, é sugerido trabalhar com o SDK do 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 };
    },
});

Modelo JavaScript v3

Nota

Os tipos de parâmetros de vinculação limitados não suportam uma forma de passar lista nem matriz, o WebPubSubConnection não é totalmente suportado com todos os parâmetros que o SDK do servidor possui, especialmente roles, além de incluir groups e expiresAfter. Caso o cliente precise adicionar funções ou atrasar a criação do token de acesso na função, é sugerido trabalhar com o SDK do servidor para JavaScript.

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

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

Definir 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 em C# que adquire informações da solicitação upstream do Web PubSub usando a associação de entrada com o tipo de evento connect e as retorna por HTTP.

C#

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

Modelo JavaScript v4

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

Modelo JavaScript v3

Defina 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"
    }
  ]
}

Definir 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

ConexãoWebPubSub

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

propriedade function.json	Propriedade de Atributo	Descrição
tipo	n/d	Deve ser definido como webPubSubConnection
direção	n/d	Deve ser definido como in
Nome	n/d	Nome da variável usado no código da função para o objeto de ligação de conexão de entrada.
hub	Núcleo	Obrigatório - O valor deve ser definido como o nome do hub Web PubSub para que a função seja acionada. Suportamos definir o valor no atributo como prioridade mais alta, ou ele pode ser definido nas configurações do aplicativo como um valor global.
userId	Id do usuário	Opcional - o valor da declaração de identificador de usuário a ser definido no token de chave de acesso.
conexão	Conexão	Obrigatório - O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço Web PubSub (o padrão é "WebPubSubConnectionString").

WebPubSubContext

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

propriedade function.json	Propriedade de Atributo	Descrição
tipo	n/d	Deve ser definido como webPubSubContext.
direção	n/d	Deve ser definido como in.
Nome	n/d	Nome da variável usado no código de função para a solicitação Web PubSub de entrada.
conexão	Conexão	Opcional - o nome de definições de aplicativo ou de uma coleção de definições que especifica o serviço 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 bem-sucedida.

Utilização

WebPubSubConnection

C#

WebPubSubConnection fornece as propriedades abaixo.

Nome da vinculação	Tipo de Ligação	Descrição
BaseUri	URI	URI de ligação do cliente Web PubSub.
URI	URI	URI absoluto da conexão Web PubSub, gerada com base na solicitação, contém AccessToken.
AccessToken	cadeia (de caracteres)	Gerado AccessToken com base no userid da solicitação e nas informações de serviço.

Modelo JavaScript v4

WebPubSubConnection fornece as propriedades abaixo.

Nome da vinculação	Descrição
baseUrl	URI de conexão do cliente Web PubSub.
URL	Uri absoluto da conexão Web PubSub, contém AccessToken a base gerada a partir do pedido.
accessToken	Gerado AccessToken com base na solicitação do identificador de usuário e nas informações de serviço.

Modelo JavaScript v3

WebPubSubConnection fornece as propriedades abaixo.

Nome da vinculação	Descrição
baseUrl	URI de conexão do Web PubSub cliente.
URL	Uri absoluta da conexão Web PubSub, contém AccessToken gerado com base na solicitação.
accessToken	Gerado AccessToken com base no pedido do UserId e nas informações do serviço.

WebPubSubContext

WebPubSubContext fornece as propriedades abaixo.

Nome da vinculação	Tipo de Ligação	Descrição	Propriedades
pedido	WebPubSubEventRequest	Solicitação do cliente, consulte a tabela abaixo para obter detalhes.	WebPubSubConnectionContext do cabeçalho da solicitação e outras propriedades desserializadas do corpo da solicitação descrevem a solicitação, por exemplo, Reason para DisconnectedEventRequest.
resposta	HttpResponseMessage	A extensão cria resposta principalmente para casos de AbuseProtection e de erros.	-
mensagem de erro	cadeia (de caracteres)	Descreva os detalhes do erro ao processar a solicitação upstream.	-
hasError	booleano	Sinalizador para indicar se é uma solicitação upstream válida do Web PubSub.	-
isPré-vôo	booleano	Sinalizador para indicar se é um pedido preflight de AbuseProtection.	-

Para o WebPubSubEventRequest, é desserializado para classes diferentes que fornecem diferentes informações sobre o cenário do pedido. Para PreflightRequest casos não válidos, o utilizador pode verificar os sinais IsPreflight e HasError para saber. Sugere-se retornar a resposta WebPubSubContext.Response de compilação do sistema diretamente, ou o cliente pode registrar erros sob demanda. Em diferentes cenários, o cliente pode ler as propriedades da solicitação como abaixo.

Classe derivada	Descrição	Propriedades
PreflightRequest	Usado em AbuseProtection quando IsPreflight é true	-
ConnectEventRequest	Usado no tipo de evento do sistema Connect	Declarações, Consulta, Subprotocolos, Certificados de Cliente
ConnectedEventRequest	Usado no tipo de evento do sistema Connected	-
UserEventRequest	Usado no tipo de evento do usuário	Dados, TipoDeDados
DisconnectedEventRequest	Usado no tipo de evento do sistema Disconnected	Razão

Nota

Embora o WebPubSubContext seja uma ligação de entrada que fornece um método de desserialização de solicitação semelhante em HttpTrigger em comparação com WebPubSubTrigger, há limitações; isso significa que o estado da conexão pós-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 utilizadores tiverem necessidade de definir a resposta do evento, deverá retornar um HttpResponseMessage ou mensagens para o evento do utilizador como corpo de resposta e colocar o estado da conexão com a chave ce-connectionstate no cabeçalho de resposta.

Vinculação de saída

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

• Todos os clientes conectados
• Clientes conectados autenticados para 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 gerir clientes e grupos, bem como conceder/revogar permissões direcionadas a IDs de ligação específicos com o grupo.

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

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

Exemplo

C#

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

Modelo JavaScript v4

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

Modelo JavaScript v3

Defina associações em functions.json.

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

Definir 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 de ligações de saída. Os tipos derivados representam a ação que o servidor deseja que o serviço invoque.

C#

Na linguagem C#, fornecemos alguns métodos estáticos 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	Dados, DataType, Excluídos
SendToGroupAction	Grupo, Dados, Tipo de Dado, Excluído
SendToUserAction	UserId, Dados, TipoDeDados
SendToConnectionAction	ConnectionId, Dados, TipoDeDados
AddUserToGroupAction	UserId, Grupo
RemoveUserFromGroupAction	ID de Usuário, Grupo
RemoveUserFromAllGroupsAction	Id do usuário
AddConnectionToGroupAction	ConnectionId, Grupo
RemoveConnectionFromGroupAction	ConnectionId, Grupo
CloseAllConnectionsAction	Excluído, Razão
CloseClientConnectionAction	ConnectionId, Razão
CloseGroupConnectionsAction	Grupo, Excluído, Razão
GrantPermissionAction	IdConexão, Permissão, NomeDestino
RevokePermissionAction	ConnectionId, Permissão, NomeDoAlvo

Modelo JavaScript v4

Em linguagem fracamente tipada como javascript, actionName é o parâmetro chave para resolver o tipo, as ações disponíveis estão listadas abaixo.

Nome da Ação	Propriedades
sendToAll	Dados, DataType, Excluídos
sendToGroup	Grupo, Dados, Tipo de Dado, Excluído
sendToUser	UserId, Dados, TipoDeDados
sendToConnection	ConnectionId, Dados, TipoDeDados
addUserToGroup	UserId, Grupo
removeUserFromGroup	UserId, Grupo
removeUserFromAllGroups	Id do usuário
addConnectionToGroup	ConnectionId, Grupo
removeConnectionFromGroup	ConnectionId, Grupo
closeAllConnections	Excluído, Razão
closeClientConnection	Identificação da Conexão, Razão
closeGroupConnections	Grupo, Excluído, Razão
grantPermission	ConnectionId, Permissão, TargetName
revokePermission	ConnectionId, Permissão, NomeDoAlvo

Importante

A propriedade message data nas ações relacionadas a enviar mensagem deve ser string se o tipo de dados estiver definido como json ou text para evitar ambiguidade na conversão de dados. Por favor, use JSON.stringify() para converter o objeto JSON que necessita ser convertido. Aplica-se a qualquer lugar que utilize a propriedade message, por exemplo, UserEventResponse.Data trabalhando com WebPubSubTrigger.

Quando o tipo de dados é definido como binary, é permitido aproveitar a vinculação naturalmente suportada dataType, conforme configurado no binary, consulte definições de gatilho e vinculação function.json para obter detalhes.

Modelo JavaScript v3

Em uma linguagem fracamente tipada como javascript, actionName é o parâmetro chave para resolver o tipo; as ações disponíveis estão listadas abaixo.

Nome da Ação	Propriedades
sendToAll	Dados, DataType, Excluídos
sendToGroup	Grupo, Dados, Tipo de Dado, Excluído
sendToUser	UserId, Dados, TipoDeDados
sendToConnection	ConnectionId, Dados, TipoDeDados
addUserToGroup	UserId, Grupo
removeUserFromGroup	UserId, Grupo
removeUserFromAllGroups	Id do usuário
addConnectionToGroup	ConnectionId, Grupo
removeConnectionFromGroup	ConnectionId, Grupo
closeAllConnections	Excluído, Motivo
closeClientConnection	ConnectionId, Motivo
closeGroupConnections	Grupo, Excluído, Razão
grantPermission	ConnectionId, Permissão, TargetName
revokePermission	IdConexão, Permissão, NomeAlvo

Importante

A propriedade message data nas ações relacionadas a enviar mensagem deve ser string se o tipo de dados estiver definido como json ou text para evitar ambiguidade na conversão de dados. Por favor, use JSON.stringify() para converter o objeto JSON necessário. Isso é aplicado a qualquer lugar usando a propriedade message, por exemplo, UserEventResponse.Data trabalhando com WebPubSubTrigger.

Quando o tipo de dados é definido como binary, é permitido aproveitar a vinculação naturalmente suportada dataType, conforme configurado no binary, consulte as Definições de gatilho e de vinculação para obter detalhes.

Configuração

WebPubSub

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

propriedade function.json	Propriedade de Atributo	Descrição
tipo	n/d	Deve ser definido como webPubSub
direção	n/d	Deve ser definido como out
Nome	n/d	Nome da variável usado no código da função para o objeto de vinculação de saída.
hub	Núcleo	O valor deve ser definido como o nome do hub Web PubSub para que a função seja acionada. Suportamos definir o valor no atributo como prioridade mais alta, ou ele pode ser definido nas configurações do aplicativo como um valor global.
conexão	Conexão	O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço Web PubSub (o padrão é "WebPubSubConnectionString").

Resolução de Problemas

Configurando o registro em log do console

Você também pode ativar facilmente o registo de consola se quiser aprofundar-se nas solicitações que está a fazer no serviço.

Próximos passos

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

Tutorial: Publicar e subscrever mensagens no Azure Web PubSub

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

Tutorial: Usar um subprotocolo suportado por serviço para streaming de cliente

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

Tutorial: Configurar um ouvinte de eventos

Interaja com demonstrações ao vivo

Explore mais exemplos do Azure Web PubSub