Padrão de verificação de declaraçãoClaim-Check Pattern

Divida uma mensagem grande em uma verificação de declaração e uma carga.Split a large message into a claim check and a payload. Enviar a verificação de declaração para a plataforma de mensagens e armazenar o conteúdo 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 para serem processados, enquanto protegem o barramento de mensagem e o cliente do que está sendo sobrecarregado ou mais lentas.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 os custos, como o armazenamento é geralmente mais barato do que as unidades de recurso usadas pela plataforma do sistema de mensagens.This pattern also helps to reduce costs, as storage is usually cheaper than resource units used by the messaging platform.

Esse padrão também é conhecido como referência com base no sistema de mensagens e foi originalmente [descrito] enterprise-integration-patterns no livro padrões de integração Enterprise, de 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, verificações de MRI), 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.

Não é recomendável enviar essas mensagens grandes para o barramento de mensagem diretamente, porque eles exigem mais recursos e largura de banda para ser consumido.Sending such large messages to the message bus directly is not recommended, because they require more resources and bandwidth to be consumed. Mensagens grandes também podem retardar a solução inteira, como plataformas de mensagens são geralmente 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, plataformas de mensagens mais têm limites no tamanho da mensagem, portanto, talvez você precise solucionar 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

Store a carga da mensagem inteira em um serviço externo, como um banco de dados.Store the entire message payload into an external service, such as a database. Obter a referência ao conteúdo armazenado e enviar apenas essa referência para o barramento de mensagem.Get the reference to the stored payload, and send just that reference to the message bus. A referência funciona como uma verificação de declaração usada para recuperar um pedaço de bagagem, portanto, 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. Interessado em processar essa mensagem específica de clientes pode usar a referência obtida para recuperar o conteúdo, 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 declaração

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 a exclusão de dados de mensagem após consumir, 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 de BLOBs é relativamente barato, custa algum dinheiro a longo prazo, especialmente se houver muitos dados.Although blob storage is relatively cheap, it costs some money in the long run, especially if there is a lot of data. Exclusão da mensagem pode ser feito de maneira síncrona pelo aplicativo que recebe e processa a mensagem, ou assincronamente por um processo dedicados separados.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 os dados antigos sem afetar a taxa de transferência e o desempenho do aplicativo de recebimento de processamento de mensagens.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 faz com que alguma sobrecarga adicional e a latência.Storing and retrieving the message causes some additional overhead and latency. Você talvez queira implementar lógica no aplicativo de envio para usar esse padrão apenas quando o tamanho da mensagem excede o limite de dados do barramento de mensagem.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 será ignorado para mensagens menores.The pattern would be skipped for smaller messages. Essa abordagem pode resultar em um padrão de verificação de declaração condicional.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 é possível ajustar o limite de mensagem com suporte da tecnologia de barramento de mensagem escolhido.This pattern should be used whenever a message cannot fit the supported message limit of the chosen message bus technology. Por exemplo, os Hubs de eventos atualmente tem um limite de 256 KB (camada básica), enquanto a grade de eventos dá suporte a mensagens apenas 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 somente pelos serviços que estão autorizados a vê-lo.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 para um recurso externo, autenticação mais rígida e regras de autorização podem ser colocadas em vigor para garantir que a segurança é imposta quando dados confidenciais são armazenados na carga.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 maneiras e com tecnologias diferentes, mas há 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 destinatário tem a responsabilidade de ler a verificação de declaração e usá-lo para recuperar o conteúdo.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 declaração.Automatic claim-check generation. Essa abordagem utiliza grade de eventos do Azure automaticamente gerar a verificação de declaração e enviá-los em barramento de mensagem.This approach uses Azure Event Grid to automatically generate the claim check and push it into the message bus.

  • Geração de verificação manual de declaração.Manual claim-check generation. Nessa abordagem, o remetente é responsável por gerenciar a carga.In this approach, the sender is responsible for managing the payload. O remetente armazena o conteúdo usando o serviço apropriado, obtém ou gera o comprovante de solicitação e envia a verificação de declaração para o barramento 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.

Grade de eventos é um serviço de roteamento de eventos e tenta entregar eventos dentro de um período de tempo configurável para cima para 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, eventos são descartados ou mensagens 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 de grade de eventos para Hubs de eventos ou armazenamento de fila, onde as mensagens podem ser retidas por períodos mais longos e arquivar mensagens tem suporte.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 entrega de mensagem de grade de eventos ajuste fina e a repetição e a configuração de mensagens mortas, consulte inativo de letra e políticas de 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 declaração com o armazenamento de BLOBs e a grade de eventosAutomatic claim-check generation with Blob Storage and Event Grid

Nessa abordagem, o remetente descarta o conteúdo da mensagem em um contêiner de armazenamento de BLOBs do Azure designado.In this approach, the sender drops the message payload into a designated Azure Blob Storage container. Grade de eventos automaticamente gera uma marca/referência e o envia para um barramento de mensagem com suporte, como as filas do armazenamento do 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, receber a mensagem e, em seguida, usar os dados de referência armazenada para baixar o conteúdo diretamente do armazenamento de BLOBs.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 de grade de eventos pode ser diretamente consumida por Azure Functions, sem a necessidade de passar por um barramento de mensagem.The same Event Grid message can be directly consumed by Azure Functions, without needing to go through a message bus. Essa abordagem tira total proveito da natureza da grade de eventos e funções sem servidor.This approach takes full advantage of the serverless nature of both Event Grid and Functions.

Você pode encontrar o código de exemplo para essa 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, a grade de eventos gera automaticamente uma mensagem quando uma carga é gravada em um contêiner de BLOBs do Azure.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 barramento de mensagem é implementado usando Hubs de eventos.But in this example, the message bus is implemented using Event Hubs. Um cliente pode se registrar para receber o fluxo de mensagens conforme elas são gravadas no hub 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-os como um arquivo do Avro que pode ser consultado usando ferramentas como o Apache Spark, Apache Drill ou qualquer uma das bibliotecas disponíveis do Avro.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 o código de exemplo para essa abordagem aqui.You can find example code for this approach here.

Geração de verificação de declaração com o barramento de serviçoClaim check generation with Service Bus

Essa solução aproveita um plug-in do barramento de serviço específico, ServiceBus.AttachmentPlugin, que torna o fluxo de trabalho de verificação de declaração 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 plug-in converte o corpo da mensagem em um anexo que é armazenado no armazenamento de BLOBs do Azure 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 do barramento de serviço atua como uma fila de notificação, um cliente pode se inscrever.The Service Bus message acts as a notification queue, which a client can subscribe to. Quando o consumidor recebe a mensagem, o plug-in torna possível ler diretamente os dados da mensagem do armazenamento de BLOBs.When the consumer receives the message, the plugin makes it possible to directly read the message data from Blob Storage. Você pode, em seguida, escolha como processar a mensagem ainda mais.You can then choose how to process the message further. Uma vantagem dessa abordagem é que ele abstrai o fluxo de trabalho de verificação de declaração do remetente e destinatário.An advantage of this approach is that it abstracts the claim-check workflow from the sender and receiver.

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

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

Neste exemplo, um cliente Kafka grava o conteúdo para o armazenamento de BLOBs do Azure.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 habilitado para Kafka.Then it sends a notification message using Kafka-enabled Event Hubs. O consumidor recebe a mensagem e pode acessar o conteúdo do armazenamento de BLOBs.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 declaração no Azure.This example shows how a different messaging protocol can be used to implement the claim-check pattern in Azure. Por exemplo, talvez seja necessário dar suporte a clientes existentes do Kafka.For example, you might need to support existing Kafka clients.

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