Documentação do Oracle Cloud Infrastructure

Usando o STOMP para Gerenciamento de Mensagens

Use o protocolo de mensagens STOMP para publicar, consumir e gerenciar mensagens em uma fila.

Visão Geral

O STOMP é um protocolo de mensagens aberto que pode aumentar a eficiência de produção e consumo, porque a autenticação é feita uma vez por conexão, em vez de uma vez por solicitação. O serviço Queue suporta as especificações STOMP 1.0, 1.1 e 1.2. É possível usar STOMP e REST para publicar e consumir na mesma fila.

Consulte as seguintes seções para obter detalhes sobre como o Queue suporta o STOMP:

Observação

A fila não suporta cabeçalhos ou transações personalizadas (quadros do STOMP BEGIN/COMMIT/ABORT). O serviço Queue retornará um quadro ERROR e fechará a conexão se BEGIN/COMMIT/ABORT for usado.

Conexão e Autenticação

Os clientes podem usar o quadro CONNECT ou STOMP para estabelecer conexão com o serviço Queue em seu ponto final de mensagens na porta 61613. Para obter instruções detalhadas sobre como localizar o ponto final de mensagens de uma fila, consulte Ponto Final de Mensagens.

A autenticação com o protocolo STOMP usa tokens de autenticação. Os tokens de autenticação devem ser codificados por base64. Você pode gerar tokens na página de detalhes do usuário da Console. Consulte Como Trabalhar com Tokens de Autenticação para obter mais informações.

Dica

Crie um grupo ou usuário dedicado e conceda a ele a permissão para gerenciar filas no compartimento ou tenancy apropriado. Em seguida, gere um token de autenticação para o usuário criado e use-o na configuração do cliente STOMP. Consulte Políticas de Fila e Exemplos de Política para obter detalhes sobre as permissões necessárias para o gerenciamento de filas.

SEND

Use o quadro SEND para produzir mensagens. Você pode incluir os seguintes cabeçalhos no quadro SEND:

  • destination: (Obrigatório) O OCID (Oracle Cloud Identifier) da fila na qual as mensagens serão publicadas. Opcionalmente, você pode incluir um ID de canal para publicar no canal especificado. Por exemplo:

    <queue_OCID>/<channel_ID>
  • receipt: (Opcional) Se o quadro SEND contiver um cabeçalho receipt, o serviço Queue enviará um quadro RECEIPT para o cliente após uma publicação bem-sucedida ou um quadro ERROR em caso de erro.
    Observação

    Se o cabeçalho receipt estiver ausente, o serviço Queue não enviará um quadro RECEIPT, mas ainda poderá enviar um quadro ERROR em caso de erro.

Não há suporte para o cabeçalho transaction e quaisquer cabeçalhos personalizados. O serviço Queue enviará um quadro ERROR e fechará a conexão se cabeçalhos sem suporte forem incluídos.

SUBSCRIBE

Use o quadro SUBSCRIBE para consumir mensagens. O quadro SUBSCRIBE é igual a uma solicitação GetMessages de sondagem longa. Todas as mensagens recebidas no destino inscrito são entregues ao cliente como quadros MESSAGE da fila. Você pode incluir os seguintes cabeçalhos no quadro SUBSCRIBE:

  • destination: (Obrigatório) O OCID (Oracle Cloud Identifier) da fila da qual as mensagens serão consumidas. Opcionalmente, você pode incluir um filtro de canal a ser consumido do canal ou canais especificados. Por exemplo:

    <queue_OCID>/<channel_ID_filter>
    Observação

    Para obter mais informações sobre filtragem, consulte Seleção de Mensagem.
  • id: (Obrigatório) Identifica a assinatura. O mesmo ID deve ser informado pelo cliente em um quadro UNSUBSCRIBE para interromper o consumo de mensagens.
  • ack: (Obrigatório) Só há suporte para o valor client-individual. Isso significa que um quadro ACK só exclui a mensagem identificada no quadro ACK e não todas as mensagens entregues antes.
  • visibility: (Opcional) Por quanto tempo as mensagens consumidas só ficarão visíveis para o cliente que está fazendo a solicitação. Se o cabeçalho for omitido, o serviço Fila usará o timeout de visibilidade padrão da fila.

No caso de erro, o serviço Queue retornará um quadro ERROR e fechará a conexão.

UNSUBSCRIBE

Use o quadro UNSUBSCRIBE para impedir que o cliente STOMP recebam mensagens da fila. Inclua o seguinte cabeçalho no quadro:

  • id: (Obrigatório) Identifica qual assinatura interromper. Esse ID foi usado no quadro SUBSCRIBE correspondente.

ACK/NACK

Use o quadro ACK para excluir uma mensagem após ela ter sido recebida e processada. Um quadro ACK só exclui a mensagem identificada pelo cabeçalho id.

Use o quadro NACK para notificar o serviço Queue de que a mensagem não foi processada com sucesso. O uso do quadro NACK atualiza a visibilidade da mensagem para torná-la imediatamente visível para outros consumidores.

Ambos os quadros aceitam o seguinte cabeçalho, dependendo da versão do protocolo:

  • id: (Obrigatório para STOMP v1.2) O ID da mensagem a ser excluída ou atualizada.
  • message-id: (Obrigatório para STOMP v1.1 ou 1.0) O ID da mensagem a ser excluída ou atualizada.

MESSAGE

O quadro MESSAGE transmite mensagens de assinaturas para o cliente STOMP. Um quadro MESSAGE contém os seguintes cabeçalhos:

  • message-id:
    • Para STOMP v1.2: Um identificador interno exclusivo da mensagem. Usado somente para fins de depuração.
    • Para STOMP v1.1 e v1.0: O recebimento de mensagem a ser usado com os quadros ACK e NACK.
  • subscription: O ID usado no quadro SUBSCRIBE.
  • destination: O OCID (Oracle Cloud Identifier) da fila que continha as mensagens e um ID de canal opcional a ser publicado em um canal especificado. Por exemplo:
    <queue_OCID>/<channel_ID>
  • ack: Somente para STOMP v.1.2, o recebimento da mensagem.
  • content-type: O tipo de payload, neste caso, plain/text.
  • content-length: O tamanho do payload ou da mensagem.
  • expire-after: O tempo de expiração da mensagem, como milissegundos desde a época.
  • visible-after: O tempo de visibilidade da mensagem, como milissegundos desde a época.
  • delivery-count: O número de vezes que essa mensagem foi entregue
  • oci-message-id : Um ID de mensagem interno.

Um quadro MESSAGE contém o payload da mensagem como corpo do quadro.

RECEIPT

O serviço Queue envia um quadro RECEIPT para o cliente STOMP depois que o serviço processa com sucesso um quadro SEND que solicitou um recebimento. Um quadro RECEIPT inclui um cabeçalho receipt-id com um valor que corresponde ao cabeçalho de recebimento no quadro SEND.

Um quadro RECEIPT é uma confirmação de que o quadro do cliente correspondente foi processado pelo servidor. Como o STOMP é baseado em fluxo, o recebimento também é uma confirmação cumulativa de que todos os quadros anteriores foram recebidos pelo servidor. No entanto, esses quadros anteriores talvez ainda não estejam totalmente processados. Se o cliente se desconectar, os quadros recebidos anteriormente deverão continuar a ser processados pelo servidor.

DISCONNECT

Use o quadro DISCONNECT para desconectar ou feche a conexão com o serviço Queue. Todas as assinaturas associadas à conexão são interrompidas. Você pode incluir o seguinte cabeçalho no quadro:

  • receipt: (Opcional) O serviço Queue enviará um quadro RECEIPT para o cliente STOMP depois que todos os quadros anteriores com um cabeçalho receipt tiverem sido processados com sucesso. Use o cabeçalho receipt para desconexões normais.

ERROR

O serviço Queue poderá enviar quadros ERROR se algo der errado. Depois de enviar o quadro ERROR, o serviço Queue fechará a conexão. O quadro ERROR pode conter os seguintes cabeçalhos:

  • message: Uma descrição curta do erro. O corpo contém informações mais detalhadas.
  • receipt-id: O valor do cabeçalho receipt, se o quadro que causou o erro incluiu um cabeçalho receipt.
  • content-type: O tipo de payload, se o corpo contiver mais detalhes de mensagem de erro.
  • content-length: O tamanho do payload ou os detalhes da mensagem de erro.

O corpo do quadro ERROR contém informações detalhadas sobre o erro.