Entrega pull com HTTP

  • Artigo

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

Nota

Este documento ajuda você a começar com os recursos de Grade de Eventos que usam o protocolo HTTP. Este artigo é adequado para usuários que precisam integrar aplicativos na nuvem. Se você precisar comunicar dados de dispositivos IoT, consulte Visão geral do recurso MQTT Broker na Grade de Eventos do Azure.

CloudEventos

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

Consulte 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 lotes.

Importante

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

Os modos de conteúdo não são sobre a codificação que você usa, binário ou texto, mas sobre 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, onde os atributos de contexto e os dados de evento estão juntos na carga HTTP. O modo de conteúdo binário separa atributos de contexto, que são mapeados para cabeçalhos HTTP, e dados de eventos, que são a carga HTTP codificada de acordo com o valor do tipo de mídia em Content-Type.

Consulte 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 para solicitar uma ação para 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 do CloudEvents.

Entrega puxada

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

O pull delivery oferece estes benefícios de consumo de eventos:

  • Consuma eventos ao seu próprio ritmo, em escala ou a uma taxa de entrada suportada pela sua aplicação.

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

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

Nota

  • Os namespaces fornecem um modelo de recurso mais simples com um único tipo de tópico. Atualmente, a Grade de Eventos oferece suporte à publicação de seus próprios eventos de aplicativo por meio de tópicos de namespace. Você não pode consumir eventos de serviços do Azure ou sistemas SaaS 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 suportam o formato JSON CloudEvents.

Fila de assinaturas de eventos

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 de fila . Uma assinatura de evento de fila tem seu deliveryMode definido como "fila". As assinaturas de eventos de fila são usadas para consumir eventos usando a API de entrega pull. Para obter mais informações sobre como criar esses recursos, consulte Criar namespaces, tópicos e assinaturas de eventos.

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

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

Operações de pull delivery

Seu aplicativo usa as seguintes operações ao trabalhar com entrega pull.

  • Uma operação de recebimento é usada para ler um ou mais eventos usando uma única solicitação para a Grade de Eventos. Por padrão, o broker aguarda até 60 segundos para 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 retorna zero ou mais eventos. Se os eventos estiverem disponíveis, ele retornará o maior número 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 seu estado.
  • Quando um aplicativo de consumidor recebe um evento e o processa, ele reconhece esse evento. Esta operação instrui a Grade de Eventos a excluir o evento para que ele não seja entregue novamente a outro cliente. O aplicativo consumidor reconhece um ou mais tokens com uma única solicitação, especificando seus tokens de bloqueio antes que eles expirem.

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

  • Seu aplicativo de consumidor libera um evento recebido para sinalizar à Grade de Eventos que não está pronto para processar esse evento e disponibilizá-lo para reentrega. Ele faz isso chamando a operação de liberação com os tokens de bloqueio identificando os eventos a serem retornados à Grade de Eventos. Seu aplicativo pode controlar se o evento deve ser liberado imediatamente ou se um atraso deve ser usado antes que o evento esteja disponível para reentrega.

  • Você pode optar por rejeitar um evento se houver uma condição, possivelmente permanente, que impeça seu aplicativo de consumidor de processar o evento. Por exemplo, uma mensagem malformada pode ser rejeitada, pois não pode ser analisada com êxito. Os eventos rejeitados são com letra morta, se um destino de letra morta estiver disponível. Caso contrário, eles são descartados.

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

Quando você invoca uma operação de bloqueio de recebimento, confirmação, liberação, rejeição ou renovação, 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 confirmação . Outras assinaturas de eventos ainda podem ter o "mesmo" evento disponível. Isso ocorre porque uma assinatura de evento recebe uma cópia dos eventos publicados. Essas cópias de eventos são efetivamente distintas entre si em todas as assinaturas de eventos. Cada evento tem seu próprio estado, independente de outros eventos.

Forma de dados ao receber eventos usando entrega pull

Ao entregar eventos usando a entrega 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 objeto json a seguir é uma resposta de exemplo de uma operação de recebimento 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 and pull

A Grade de Eventos oferece suporte à entrega de eventos push e pull usando HTTP. Com a entrega por 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 envia eventos. Com a entrega pull, os aplicativos do assinante se conectam à Grade de Eventos para consumir eventos. A entrega pull é suportada para tópicos em um namespace Event Grid.

Importante

Os Hubs de Eventos são suportados como um destino para assinaturas de tópicos de namespace. Nas próximas versões, os Namespaces de Grade de Eventos suportarão todos os destinos atualmente disponíveis no Event Grid Basic, juntamente com destinos adicionais.

Diagrama de alto nível mostrando push delivery e pull delivery com o tipo de recursos envolvidos.

Quando usar a entrega por push vs. entrega por pull

Seguem-se orientações gerais para o ajudar a decidir quando utilizar a entrega por pull ou push.

Entrega puxada

  • Você precisa de controle total sobre quando receber eventos. Por exemplo, seu aplicativo pode não estar ativo o tempo todo, não ser estável o suficiente ou você processar dados em determinados momentos.
  • Você precisa de controle total sobre o consumo de eventos. Por exemplo, um serviço ou camada downstream em seu aplicativo de consumidor tem um problema que impede que você processe eventos. Nesse caso, a API de entrega pull permite que o aplicativo do consumidor libere um evento já lido de volta ao corretor para que possa ser entregue posteriormente.
  • Você deseja usar links privados ao receber eventos, o que só é possível com a entrega pull, não com a entrega push.
  • Você não tem a capacidade de expor um ponto de extremidade e usar a entrega por push, mas pode se conectar à Grade de Eventos para consumir eventos.

Entrega por push

  • Você deseja evitar sondagens constantes para determinar se ocorreu uma alteração no estado do sistema. Em vez disso, use a Grade de Eventos para enviar eventos para você no momento em que as alterações de estado ocorrerem.
  • Você tem um aplicativo que não pode fazer chamadas de saída. Por exemplo, sua organização pode estar preocupada com a exfiltração de dados. No entanto, seu aplicativo pode receber eventos por meio de um ponto de extremidade público.

Próximos passos

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

  • SDKs de plano de controle e plano de dados.
  • Anúncio de SDKs de plano de dados com uma infinidade de informações, exemplos e links.
  • Quotas e limites.