Entrega de pull com HTTP

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.

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.

Para obter mais informações, confira Suporte ao CloudEvents.

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.

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.

Para obter mais informações, confira Modos de conteúdo do CloudEvents.

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.

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.

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.

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.

• Publicar e assinar eventos usando Tópicos de Namespace.

Outros links úteis

• SDKs do painel de controle e do plano de dados.
• Comunicado dos SDKs do plano de dados com uma infinidade de informações, exemplos e links.
• Cotas e limites.