Share via

Entrega de pull com HTTP

  • Artigo

Este artigo baseia-se em O que é a Grade de Eventos do Azure? e no artigo de conceitos da Grade de Eventos para fornecer informações essenciais antes de começar a usar a entrega de pull da Grade de Eventos por HTTP. Ele aborda os conceitos fundamentais, os modelos de recursos e os modos de entrega de mensagens com suporte. No final deste documento, você encontrará links úteis para artigos que orientam você sobre como usar a Grade de Eventos e artigos que oferecem informações conceituais detalhadas.

Observação

Este documento ajuda você a começar a usar as funcionalidades da Grade de Eventos que usam o protocolo HTTP. Este artigo é adequado para usuários que precisam integrar aplicativos na nuvem. Caso você precise comunicar os dados do dispositivo IoT, confira Visão geral do recurso Agente MQTT na Grade de Eventos do Azure.

CloudEvents

Os tópicos do namespace da Grade de Eventos aceitam eventos que estão em conformidade com a especificação CloudEvents 1.0 padrão aberto do CNCF (Cloud Native Computing Foundation) usando a associação de protocolo HTTP com o formato JSON.

Confira os conceitos do CloudEvents para obter mais informações.

Modos de conteúdo do CloudEvents

A especificação CloudEvents define três modos de conteúdo que você pode usar: binário, estruturado e em lote.

Importante

Com qualquer modo de conteúdo, você pode trocar texto (JSON, texto/*, etc.) ou dados de evento codificados binários. O modo de conteúdo binário não é usado exclusivamente para enviar dados binários.

Os modos de conteúdo não se referem à codificação que você usa, binário ou texto, mas a como os dados do evento e seus metadados são descritos e trocados. O modo de conteúdo estruturado usa uma única estrutura, por exemplo, um objeto JSON, em que os atributos de contexto e os dados de evento são reunidos no conteúdo HTTP. O modo de conteúdo binário separa atributos de contexto, que são mapeados para cabeçalhos HTTP e dados de evento, que é a carga HTTP codificada de acordo com o valor do tipo de mídia em Content-Type.

Confira os modos de conteúdo do CloudEvents para obter mais informações.

Mensagens e eventos

Um CloudEvent normalmente carrega dados de evento anunciando uma ocorrência em um sistema, ou seja, uma alteração de estado do sistema. No entanto, você pode transmitir qualquer tipo de dados ao usar o CloudEvents. Por exemplo, talvez você queira usar o formato de troca CloudEvents para enviar uma mensagem de comando e solicitar uma ação a um aplicativo downstream. Outro exemplo é quando você está roteando mensagens do agente MQTT da Grade de Eventos para um tópico. Nesse cenário, você está roteando uma mensagem MQTT encapsulada em um envelope CloudEvents.

Entrega pull

Com a entrega de pull, seu aplicativo se conecta à Grade de Eventos para ler CloudEvents usando semântica semelhante à fila.

A entrega de pull oferece estes benefícios de consumo de eventos:

  • Consuma eventos em seu próprio ritmo, em escala ou em uma taxa de entrada compatível com seu aplicativo.

  • Consuma eventos em um momento à sua escolha. Por exemplo, considerando os requisitos de negócios, as mensagens são processadas à noite.

  • Consuma eventos em um link privado para que seus dados usem espaço de IP privado.

Observação

  • Os namespaces fornecem um modelo de recurso mais simples com um só tipo de tópico. Atualmente, a Grade de Eventos dá suporte à publicação dos seus eventos de aplicativo por meio de tópicos de namespace. Não é possível consumir eventos de serviços do Azure ou de sistemas SaaS de parceiros usando tópicos de namespace. Também não é possível criar tópicos do sistema, tópicos de domínio ou tópicos de parceiros em um namespace.
  • Os tópicos de namespace dão suporte ao formato JSON de CloudEvents.

Enfileirar assinaturas de evento

Ao receber eventos ou usar operações que gerenciam o estado do evento, um aplicativo especifica um ponto de extremidade HTTP de namespace, um nome de tópico e o nome de uma assinatura de evento fila. Uma assinatura de evento de fila tem seu deliveryMode definido como "fila". As assinaturas de evento de fila são usadas para consumir eventos usando a API de entrega de pull. Para obter mais informações sobre como criar esses recursos, confira Criar namespaces, tópicos e assinaturas de eventos.

Você usa uma assinatura de evento para definir os critérios de filtragem de eventos e, ao fazer isso, define efetivamente o conjunto de eventos que ficam disponíveis para consumo por meio dessa assinatura de evento. Um ou mais aplicativos assinantes (consumidores) podem se conectar ao mesmo ponto de extremidade de namespace e usar o mesmo tópico e a mesma assinatura de evento.

Diagrama de alto nível de um editor e um consumidor usando uma assinatura de evento. O consumidor usa a entrega pull.

Operações de entrega de pull

Seu aplicativo usa as operações a seguir ao trabalhar com entrega de pull.

  • Uma operação de recebimento é usada para ler um ou mais eventos usando uma solicitação individual para a Grade de Eventos. O agente aguarda até 60 segundos até que os eventos fiquem disponíveis. Por exemplo, os eventos ficam disponíveis para entrega quando são publicados pela primeira vez. Uma solicitação de recebimento bem-sucedida não retorna nenhum ou mais eventos. Se os eventos estiverem disponíveis, ela retornará o máximo possível de eventos disponíveis até a contagem de eventos solicitada. A Grade de Eventos também retorna um token de bloqueio para cada evento lido.
  • Um token de bloqueio é um tipo de identificador que identifica um evento que você pode usar para controlar o estado.
  • Depois que um aplicativo consumidor recebe um evento e o processa, ele confirma o evento. Isso instrui a Grade de Eventos a excluir o evento para que ele não seja entregue novamente a outro cliente. O aplicativo consumidor confirma um ou mais tokens com uma solicitação individual especificando os tokens de bloqueio antes de eles expirarem.

Em algumas ocasiões, seu aplicativo consumidor pode querer liberar ou rejeitar eventos.

  • Seu aplicativo consumidor libera um evento recebido para sinalizar à Grade de Eventos que não está pronto para processar o evento e disponibilizá-lo para nova entrega. Ele faz isso chamando a operação de liberação e os tokens de bloqueio que identificam os eventos são devolvidos à Grade de Eventos. Seu aplicativo pode controlar se o evento deve ser liberado imediatamente ou se deve haver um atraso antes que o evento fique disponível para novo envio.

  • Você poderá optar por rejeitar um evento se houver uma condição, possivelmente permanente, que impeça que o aplicativo consumidor processe o evento. Por exemplo, uma mensagem malformada pode ser rejeitada, pois não pode ser analisada com sucesso. Os eventos rejeitados serão colocados na fila de mensagens mortas se um destino de mensagens mortas estiver disponível. Caso contrário, eles são descartados.

Escopo no qual as operações de entrega de pull são executadas

Quando você invoca uma operação de recebimento, confirmação, liberação, rejeição ou renovação de bloqueio, essas ações são executadas no contexto da assinatura do evento. Por exemplo, se você reconhecer um evento, esse evento não estará mais disponível por meio da assinatura de evento usada ao chamar a ação de reconhecimento. Outra assinatura de evento ainda pode ter o "mesmo" evento disponível. Isso ocorre porque uma assinatura de evento obtém uma cópia dos eventos publicados. Essas cópias de evento são efetivamente distintas umas das outras entre assinaturas de evento. Cada evento tem seu próprio estado independente de outros eventos.

Forma de dados no recebimento de eventos usando a entrega de pull

Ao fornecer eventos usando a entrega de pull, a Grade de Eventos inclui uma matriz de objetos que, por sua vez, inclui os objetos event e brokerProperties. O valor da propriedade event é o CloudEvent entregue no modo de conteúdo estruturado. O objeto brokerProperties contém o token de bloqueio associado ao CloudEvent entregue. O seguinte objeto JSON é uma resposta de exemplo de uma operação receive que retorna dois eventos:

{
    "value": [
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDXYS23Z+5Hq754VqQjxywE",
                "deliveryCount": 2
            },
            "event": {
                "specversion": "1.0",
                "id": "A234-1234-1235",
                "source": "/mycontext",
                "time": "2018-04-05T17:31:00Z",
                "type": "com.example.someeventtype",
                "data": "some data"
            }
        },
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDLeaL+nRJLNq3/5NXd/T0b",
                "deliveryCount": 1
            },
            "event": {
                "specversion": "1.0",
                "id": "B688-1234-1235",
                "source": "/mycontext",
                "type": "com.example.someeventtype",
                "time": "2018-04-05T17:31:00Z",
                "data": {
                    "somekey" : "value",
                    "someOtherKey" : 9
                }
            }
        }
    ]
}

Entrega push e pull

Usando o HTTP, a Grade de Eventos dá suporte às entregas push e pull de eventos. Com a entrega de push, você define um destino em uma assinatura de evento, um webhook ou um serviço do Azure para o qual a Grade de Eventos enviará os eventos. Com a entrega pull, os aplicativos assinantes se conectam à Grade de Eventos para consumir os eventos. A entrega de pull tem suporte para tópicos em um namespace da Grade de Eventos.

Importante

Os Hubs de Eventos têm suporte como destino para assinaturas para tópicos de namespace. Nas próximas versões, os Namespaces da Grade de Eventos darão suporte a todos os destinos atualmente disponíveis no Event Grid Básico, juntamente com destinos adicionais.

Diagrama de alto nível que mostra uma entrega push e uma entrega pull com os tipos de recursos envolvidos.

Quando usar a entrega push ou a entrega pull

As diretrizes gerais a seguir vão para ajudar você a decidir quando usar a entrega push ou pull.

Entrega pull

  • Você precisa obter controle completo sobre quando os eventos serão recebidos. Por exemplo, seu aplicativo talvez não fique online o tempo todo, não seja estável o suficiente ou você processa os dados em determinados horários.
  • Você precisa obter controle completo sobre o consumo de eventos. Por exemplo, um serviço downstream ou uma camada no seu aplicativo consumidor tem um problema que impede que você processe os eventos. Nesse caso, a API de entrega pull permite que o aplicativo consumidor libere um evento já lido novamente para o agente, de modo que ele possa ser entregue posteriormente.
  • Você deseja usar links privados ao receber eventos, o que é possível apenas com a entrega de pull, não com a entrega de push.
  • Você não tem a capacidade de expor um ponto de extremidade e usar a entrega push, mas pode se conectar à Grade de Eventos para consumir eventos.

Entrega push

  • Você deseja evitar a sondagem constante para determinar se ocorreu uma alteração de estado do sistema. Você prefere usar a Grade de Eventos para enviar eventos para você no momento em que as alterações de estado ocorrem.
  • Você tem um aplicativo que não pode fazer chamadas de saída. Por exemplo, sua organização talvez esteja preocupada com a exfiltração dos dados. No entanto, seu aplicativo pode receber eventos por meio de um ponto de extremidade público.

Próximas etapas

Os artigos a seguir fornecem informações sobre como usar a Grade de Eventos ou fornecem informações adicionais sobre os conceitos.