Uso di STOMP per la gestione dei messaggi

Utilizzare il protocollo di messaggio STOMP per pubblicare, utilizzare e gestire i messaggi in una coda.

panoramica

STOMP è un protocollo di messaggistica aperto che può aumentare l'efficienza a livello di produzione e consumo, poiché l'autenticazione viene eseguita una volta per connessione, anziché una volta per richiesta. Il servizio Queue supporta le specifiche STOMP 1.0, 1.1 e 1.2. È possibile utilizzare sia STOMP che REST per pubblicare e utilizzare nella stessa coda.

Per ulteriori informazioni su come Queue supporta STOMP, vedere le sezioni seguenti:

Nota

La coda non supporta intestazioni o transazioni personalizzate (frame STOMP BEGIN/COMMIT/ABORT). Queue restituisce un frame ERROR e chiude la connessione se si utilizza BEGIN/COMMIT/ABORT.

Connessione e autenticazione

I client possono utilizzare il frame CONNECT o STOMP per connettersi al servizio Queue sul relativo endpoint di messaggi sulla porta 61613. Per istruzioni dettagliate sulla ricerca dell'endpoint dei messaggi di una coda, vedere Endpoint messaggi.

L'autenticazione con il protocollo STOMP utilizza i token di autenticazione. I token di autenticazione devono avere una codifica base64. È possibile generare i token nella pagina dei dettagli utente della console. Per ulteriori informazioni, vedere Utilizzo dei token di autenticazione.

Suggerimento

Creare un gruppo o un utente dedicato e concedere loro l'autorizzazione per gestire le code nel compartimento o nella tenancy appropriati. Quindi generare un token di autenticazione per l'utente creato e utilizzarlo nella configurazione client STOMP. Per i dettagli sulle autorizzazioni necessarie per la gestione delle code, vedere Criteri di coda ed Esempi di criteri.

SEND

Utilizzare il frame SEND per produrre i messaggi. È possibile includere le seguenti intestazioni nel frame SEND:

destination: (obbligatorio) l'OCID (identificativo Oracle Cloud) della coda in cui pubblicare i messaggi. Facoltativamente, è possibile includere un ID canale da pubblicare nel canale specificato. Ad esempio:
```
<queue_OCID>/<channel_ID>
```
receipt: (facoltativo) se il frame SEND contiene un'intestazione receipt, Queue invia un frame RECEIPT al client al completamento della pubblicazione oppure un frame ERROR in caso di errore.
Nota

Se manca l'intestazione receipt, il servizio Queue non invia un frame RECEIPT, ma potrebbe comunque inviare un frame ERROR in caso di errore.

L'intestazione transaction e le intestazioni personalizzate non sono supportate. Queue invia un frame ERROR e chiude la connessione se sono incluse intestazioni non supportate.

ESEGUI SOTTOSCRIZIONE

Utilizzare il frame SUBSCRIBE per utilizzare i messaggi. Il frame SUBSCRIBE è uguale a una richiesta GetMessages di polling lungo. Tutti i messaggi ricevuti nella destinazione sottoscritta vengono consegnati al client come frame MESSAGE dalla coda. È possibile includere le seguenti intestazioni nel frame SUBSCRIBE:

destination: (obbligatorio) l'OCID (identificativo Oracle Cloud) della coda da cui consumare i messaggi. Facoltativamente, è possibile includere un filtro canale da utilizzare dal canale o dai canali specificati. Ad esempio:
```
<queue_OCID>/<channel_ID_filter>
```
Nota

Per ulteriori informazioni sull'applicazione dei filtri, vedere Selezione dei messaggi.
id: (Obbligatorio) Identifica l'abbonamento. Lo stesso ID deve essere passato dal client in un frame UNSUBSCRIBE per interrompere l'utilizzo dei messaggi.
ack: (Obbligatorio) È supportato solo il valore client-individual. Ciò significa che un frame ACK elimina solo il messaggio identificato nel frame ACK e non tutti i messaggi consegnati in precedenza.
visibility: (facoltativo) per quanto tempo i messaggi consumati saranno visibili solo per il client che effettua la richiesta. Se l'intestazione viene omessa, il servizio Coda utilizza il timeout di visibilità predefinito della coda.

In caso di errore, il servizio Queue restituisce un frame ERROR e chiude la connessione.

ANNULLA SOTTOSCRIZIONE

Utilizzare il frame UNSUBSCRIBE per impedire al client STOMP di ricevere messaggi dalla coda. Includere la seguente intestazione nel frame:

id: (Obbligatorio) Identifica la sottoscrizione da interrompere. Questo ID è stato utilizzato nel frame SUBSCRIBE corrispondente.

ACK/NACK

Utilizzare il frame ACK per eliminare un messaggio dopo che è stato ricevuto ed elaborato. Un frame ACK elimina solo il messaggio identificato dall'intestazione id.

Utilizzare il frame NACK per notificare a Queue che il messaggio non è stato elaborato correttamente. L'uso del frame NACK consente di aggiornare la visibilità del messaggio per renderlo immediatamente visibile ad altri utenti.

Entrambi i frame accettano la seguente intestazione, a seconda della versione del protocollo:

id: (Obbligatorio per STOMP v1.2) L'ID del messaggio da eliminare o aggiornare.
message-id: (Obbligatorio per STOMP v1.1 o 1.0) L'ID del messaggio da eliminare o aggiornare.

MESSAGGIO

Il frame MESSAGE trasmette i messaggi delle sottoscrizioni al client STOMP. Un frame MESSAGE contiene le intestazioni riportate di seguito.

message-id:
- Per STOMP v1.2: identificativo interno univoco del messaggio. Utilizzato solo per debug.
- Per STOMP v1.1 e v1.0: la ricezione dei messaggi da utilizzare con i frame ACK e NACK.
subscription: l'ID utilizzato nel frame SUBSCRIBE.
destination: l'OCID (Oracle Cloud Identifier) della coda contenente i messaggi e un ID canale facoltativo da pubblicare in un canale specificato. Ad esempio:
```
<queue_OCID>/<channel_ID>
```
ack: solo per STOMP v.1.2, la ricezione del messaggio.
content-type: il tipo di payload, in questo caso plain/text.
content-length: la lunghezza del payload o del messaggio.
expire-after: l'ora di scadenza del messaggio, espressa in millisecondi dall'epoca.
visible-after: il tempo di visibilità del messaggio, espresso in millisecondi dall'epoca.
delivery-count: il numero di volte in cui questo messaggio è stato consegnato
oci-message-id : ID di un messaggio interno.

Un frame MESSAGE contiene il payload del messaggio come corpo del frame.

RICEVUTA

Il servizio Queue invia un frame RECEIPT al client STOMP dopo che il servizio ha elaborato correttamente un frame SEND che ha richiesto una ricevuta. Un frame RECEIPT include un'intestazione receipt-id con un valore che corrisponde all'intestazione della ricevuta nel frame SEND.

Un frame RECEIPT è una conferma che il frame client corrispondente è stato elaborato dal server. Poiché STOMP è basato su flusso, la ricevuta è anche una conferma cumulativa che tutti i frame precedenti sono stati ricevuti dal server. Tuttavia, questi frame precedenti potrebbero non essere ancora completamente elaborati. Se il client si disconnette, i frame ricevuti in precedenza devono continuare a essere elaborati dal server.

DISCONNECT

Utilizzare il frame DISCONNECT per disconnettersi o chiudere la connessione al servizio Queue. Tutte le sottoscrizioni associate alla connessione vengono arrestate. È possibile includere la seguente intestazione nel frame:

receipt: (Facoltativo) Queue invierà un frame RECEIPT al client STOMP dopo che tutti i frame precedenti con un'intestazione receipt sono stati elaborati correttamente. Utilizzare l'intestazione receipt per le disconnessioni normali.

ERRORE

Queue può inviare frame ERROR se qualcosa va storto. Dopo aver inviato il frame ERROR, Queue chiude la connessione. Il frame ERROR può contenere le intestazioni riportate di seguito.

message: una breve descrizione dell'errore. Il corpo contiene informazioni più dettagliate.
receipt-id: il valore dell'intestazione receipt, se il frame che ha causato l'errore includeva un'intestazione receipt.
content-type: il tipo di payload, se il corpo contiene ulteriori dettagli del messaggio di errore.
content-length: la lunghezza del payload o i dettagli del messaggio di errore.

Il corpo del frame ERROR contiene informazioni dettagliate sull'errore.

Documentazione di Oracle Cloud Infrastructure