Padrão de verificação de sinistroClaim-Check Pattern

Divida uma mensagem grande em um cheque de reivindicação e uma carga útil.Split a large message into a claim check and a payload. Envie a verificação de sinistro para a plataforma de mensagens e armazene a carga para um serviço externo.Send the claim check to the messaging platform and store the payload to an external service. Esse padrão permite que mensagens grandes sejam processadas, protegendo o barramento de mensagens e o cliente de ser sobrecarregado ou desacelerado.This pattern allows large messages to be processed, while protecting the message bus and the client from being overwhelmed or slowed down. Esse padrão também ajuda a reduzir custos, já que o armazenamento geralmente é mais barato do que as unidades de recursos usadas pela plataforma de mensagens.This pattern also helps to reduce costs, as storage is usually cheaper than resource units used by the messaging platform.

Este padrão também é conhecido como Mensagens Baseadas em Referência, e foi originalmente descrito no livro Enterprise Integration Patterns, por Gregor Hohpe e Bobby Woolf.This pattern is also known as Reference-Based Messaging, and was originally described in the book Enterprise Integration Patterns, by Gregor Hohpe and Bobby Woolf.

Contexto e problemaContext and problem

Uma arquitetura baseada em mensagens em algum momento deve ser capaz de enviar, receber e manipular mensagens grandes.A messaging-based architecture at some point must be able to send, receive, and manipulate large messages. Essas mensagens podem conter qualquer coisa, incluindo imagens (por exemplo, ressonâncias magnéticas), arquivos de som (por exemplo, chamadas de call-center), documentos de texto ou qualquer tipo de dados binários de tamanho arbitrário.Such messages may contain anything, including images (for example, MRI scans), sound files (for example, call-center calls), text documents, or any kind of binary data of arbitrary size.

Enviar mensagens tão grandes diretamente para o barramento de mensagens não é recomendado, pois eles exigem mais recursos e largura de banda para serem consumidos.Sending such large messages to the message bus directly is not recommended, because they require more resources and bandwidth to be consumed. Grandes mensagens também podem retardar toda a solução, porque as plataformas de mensagens geralmente são ajustadas para lidar com grandes quantidades de pequenas mensagens.Large messages can also slow down the entire solution, because messaging platforms are usually fine-tuned to handle huge quantities of small messages. Além disso, a maioria das plataformas de mensagens tem limites no tamanho da mensagem, então você pode precisar contornar esses limites para mensagens grandes.Also, most messaging platforms have limits on message size, so you may need to work around these limits for large messages.

SoluçãoSolution

Armazene toda a carga de mensagem em um serviço externo, como um banco de dados.Store the entire message payload into an external service, such as a database. Obtenha a referência à carga armazenada e envie apenas essa referência para o barramento de mensagens.Get the reference to the stored payload, and send just that reference to the message bus. A referência age como um cheque de reivindicação usado para recuperar uma peça de bagagem, daí o nome do padrão.The reference acts like a claim check used to retrieve a piece of luggage, hence the name of the pattern. Os clientes interessados em processar essa mensagem específica podem usar a referência obtida para recuperar a carga, se necessário.Clients interested in processing that specific message can use the obtained reference to retrieve the payload, if needed.

Diagrama do padrão de verificação de sinistro

Problemas e consideraçõesIssues and considerations

Considere os seguintes pontos ao decidir como implementar esse padrão:Consider the following points when deciding how to implement this pattern:

  • Considere excluir os dados da mensagem depois de consumi-los, se você não precisar arquivar as mensagens.Consider deleting the message data after consuming it, if you don't need to archive the messages. Embora o armazenamento blob seja relativamente barato, ele custa algum dinheiro no longo prazo, especialmente se houver um monte de dados.Although blob storage is relatively cheap, it costs some money in the long run, especially if there is a lot of data. A exclusão da mensagem pode ser feita de forma sincronizada pelo aplicativo que recebe e processa a mensagem, ou assíncronamente por um processo dedicado separado.Deleting the message can be done synchronously by the application that receives and processes the message, or asynchronously by a separate dedicated process. A abordagem assíncrona remove dados antigos sem impacto no desempenho de throughput e processamento de mensagens do aplicativo receptor.The asynchronous approach removes old data with no impact on the throughput and message processing performance of the receiving application.

  • Armazenar e recuperar a mensagem causa algumas despesas adicionais e latência.Storing and retrieving the message causes some additional overhead and latency. Você pode querer implementar a lógica no aplicativo de envio para usar esse padrão somente quando o tamanho da mensagem exceder o limite de dados do barramento de mensagens.You may want to implement logic in the sending application to use this pattern only when the message size exceeds the data limit of the message bus. O padrão seria ignorado para mensagens menores.The pattern would be skipped for smaller messages. Essa abordagem resultaria em um padrão condicional de verificação de sinistros.This approach would result in a conditional claim-check pattern.

Quando usar esse padrãoWhen to use this pattern

Esse padrão deve ser usado sempre que uma mensagem não se encaixar no limite de mensagem suportada da tecnologia de barramento de mensagens escolhida.This pattern should be used whenever a message cannot fit the supported message limit of the chosen message bus technology. Por exemplo, o Event Hubs atualmente tem um limite de 256 KB (Basic Tier), enquanto o Event Grid suporta apenas mensagens de 64 KB.For example, Event Hubs currently has a limit of 256 KB (Basic Tier), while Event Grid supports only 64-KB messages.

O padrão também pode ser usado se a carga deve ser acessada apenas por serviços autorizados a vê-la.The pattern can also be used if the payload should be accessed only by services that are authorized to see it. Ao descarregar a carga útil em um recurso externo, regras mais rígidas de autenticação e autorização podem ser colocadas em prática, para garantir que a segurança seja aplicada quando dados confidenciais são armazenados na carga útil.By offloading the payload to an external resource, stricter authentication and authorization rules can be put in place, to ensure that security is enforced when sensitive data is stored in the payload.

ExemplosExamples

No Azure, esse padrão pode ser implementado de várias formas e com diferentes tecnologias, mas existem duas categorias principais.On Azure, this pattern can be implemented in several ways and with different technologies, but there are two main categories. Em ambos os casos, o receptor tem a responsabilidade de ler o cheque de sinistro e usá-lo para recuperar a carga.In both cases, the receiver has the responsibility to read the claim check and use it to retrieve the payload.

  • Geração automática de verificação de sinistros.Automatic claim-check generation. Esta abordagem usa o Azure Event Grid para gerar automaticamente a verificação de sinistro e empurrá-la para o barramento de mensagens.This approach uses Azure Event Grid to automatically generate the claim check and push it into the message bus.

  • Geração manual de verificação de sinistros.Manual claim-check generation. Nesta abordagem, o remetente é responsável pelo gerenciamento da carga.In this approach, the sender is responsible for managing the payload. O remetente armazena a carga usando o serviço apropriado, recebe ou gera o cheque de sinistro, e envia o cheque de sinistro para o ônibus de mensagem.The sender stores the payload using the appropriate service, gets or generates the claim check, and sends the claim check to the message bus.

Event Grid é um serviço de roteamento de eventos e tenta entregar eventos dentro de um tempo configurável até 24 horas.Event Grid is an event routing service and tries to deliver events within a configurable amount of time up to 24 hours. Depois disso, os eventos são descartados ou mortos.After that, events are either discarded or dead lettered. Se você precisar arquivar as cargas do evento ou repetir o fluxo de eventos, você pode adicionar uma assinatura do Event Grid ao Event Hubs ou ao Queue Storage, onde as mensagens podem ser retidas por períodos mais longos e o arquivamento de mensagens é suportado.If you need to archive the event payloads or replay the event stream, you can add an Event Grid subscription to Event Hubs or Queue Storage, where messages can be retained for longer periods and archiving messages is supported. Para obter informações sobre afinação da entrega e repetição da mensagem Event Grid e a configuração de letras mortas, consulte políticas de letra e repetição.For information about fine tuning Event Grid message delivery and retry, and dead letter configuration, see Dead letter and retry policies.

Geração automática de verificação de sinistros com Blob Storage e Event GridAutomatic claim-check generation with Blob Storage and Event Grid

Nesta abordagem, o remetente coloca a carga de mensagem em um contêiner designado Azure Blob Storage.In this approach, the sender drops the message payload into a designated Azure Blob Storage container. Event Grid gera automaticamente uma tag/referência e envia-a para um barramento de mensagens suportado, como filas de armazenamento Azure.Event Grid automatically generates a tag/reference and sends it to a supported message bus, such as Azure Storage Queues. O receptor pode sondar a fila, obter a mensagem e, em seguida, usar os dados de referência armazenados para baixar a carga diretamente do Blob Storage.The receiver can poll the queue, get the message, and then use the stored reference data to download the payload directly from Blob Storage.

A mesma mensagem Event Grid pode ser consumida diretamente pelo Azure Functions, sem precisar passar por um barramento de mensagens.The same Event Grid message can be directly consumed by Azure Functions, without needing to go through a message bus. Essa abordagem aproveita ao máximo a natureza sem servidor tanto da Grade de Eventos quanto das Funções.This approach takes full advantage of the serverless nature of both Event Grid and Functions.

Você pode encontrar código de exemplo para esta abordagem aqui.You can find example code for this approach here.

Grade de eventos com hubs de eventosEvent Grid with Event Hubs

Semelhante ao exemplo anterior, event grid gera automaticamente uma mensagem quando uma carga é escrita em um contêiner Azure Blob.Similar to the previous example, Event Grid automatically generates a message when a payload is written to an Azure Blob container. Mas neste exemplo, o ônibus de mensagens é implementado usando Event Hubs.But in this example, the message bus is implemented using Event Hubs. Um cliente pode se cadastrar para receber o fluxo de mensagens à medida que são escritas no centro de eventos.A client can register itself to receive the stream of messages as they are written to the event hub. O hub de eventos também pode ser configurado para arquivar mensagens, disponibilizando-as como um arquivo Avro que pode ser consultado usando ferramentas como Apache Spark, Apache Drill ou qualquer uma das bibliotecas Avro disponíveis.The event hub can also be configured to archive messages, making them available as an Avro file that can be queried using tools like Apache Spark, Apache Drill, or any of the available Avro libraries.

Você pode encontrar código de exemplo para esta abordagem aqui.You can find example code for this approach here.

Geração de verificação de sinistro com ônibus de serviçoClaim check generation with Service Bus

Esta solução aproveita um plugin de ônibus de serviço específico, ServiceBus.AttachmentPlugin, o que torna o fluxo de trabalho de verificação de sinistro fácil de implementar.This solution takes advantage of a specific Service Bus plugin, ServiceBus.AttachmentPlugin, which makes the claim-check workflow easy to implement. O plugin converte qualquer corpo de mensagem em um anexo que é armazenado no Azure Blob Storage quando a mensagem é enviada.The plugin converts any message body into an attachment that gets stored in Azure Blob Storage when the message is sent.

using ServiceBus.AttachmentPlugin;
...

// Getting connection information
var serviceBusConnectionString = Environment.GetEnvironmentVariable("SERVICE_BUS_CONNECTION_STRING");
var queueName = Environment.GetEnvironmentVariable("QUEUE_NAME");
var storageConnectionString = Environment.GetEnvironmentVariable("STORAGE_CONNECTION_STRING");

// Creating config for sending message
var config = new AzureStorageAttachmentConfiguration(storageConnectionString);

// Creating and registering the sender using Service Bus Connection String and Queue Name
var sender = new MessageSender(serviceBusConnectionString, queueName);
sender.RegisterAzureStorageAttachmentPlugin(config);

// Create payload
var payload = new { data = "random data string for testing" };
var serialized = JsonConvert.SerializeObject(payload);
var payloadAsBytes = Encoding.UTF8.GetBytes(serialized);
var message = new Message(payloadAsBytes);

// Send the message
await sender.SendAsync(message);

A mensagem Service Bus funciona como uma fila de notificação, que um cliente pode assinar.The Service Bus message acts as a notification queue, which a client can subscribe to. Quando o consumidor recebe a mensagem, o plugin torna possível ler diretamente os dados da mensagem do Blob Storage.When the consumer receives the message, the plugin makes it possible to directly read the message data from Blob Storage. Em seguida, você pode escolher como processar a mensagem ainda mais.You can then choose how to process the message further. Uma vantagem dessa abordagem é que ela abstrai o fluxo de trabalho de verificação de sinistro do remetente e do receptor.An advantage of this approach is that it abstracts the claim-check workflow from the sender and receiver.

Você pode encontrar código de exemplo para esta abordagem aqui.You can find example code for this approach here.

Geração manual de verificação de sinistros com KafkaManual claim-check generation with Kafka

Neste exemplo, um cliente Kafka escreve a carga útil para o Azure Blob Storage.In this example, a Kafka client writes the payload to Azure Blob Storage. Em seguida, ele envia uma mensagem de notificação usando hubs de eventos habilitados para Kafka.Then it sends a notification message using Kafka-enabled Event Hubs. O consumidor recebe a mensagem e pode acessar a carga útil do Blob Storage.The consumer receives the message and can access the payload from Blob Storage. Este exemplo mostra como um protocolo de mensagens diferente pode ser usado para implementar o padrão de verificação de sinistro no Azure.This example shows how a different messaging protocol can be used to implement the claim-check pattern in Azure. Por exemplo, você pode precisar dar suporte aos clientes Kafka existentes.For example, you might need to support existing Kafka clients.

Você pode encontrar código de exemplo para esta abordagem aqui.You can find example code for this approach here.