Messaggi, payload e serializzazione

  • Articolo

bus di servizio di Azure gestisce i messaggi. I messaggi trasportano un payload e metadati. I metadati sono sotto forma di coppie chiave-valore e descrivono il payload e fornisce istruzioni di gestione per bus di servizio e applicazioni. In alcuni casi, solo i metadati sono sufficienti per trasmettere le informazioni che il mittente vuole comunicare ai destinatari e il payload rimane vuoto.

Il modello a oggetti dei client ufficiali del bus di servizio per .NET e Java riflette la struttura astratta dei messaggi del bus di servizio, mappata da e verso i protocolli wire supportati dal bus di servizio.

Un messaggio del bus di servizio è costituito da una sezione di payload binario che il bus di servizio non gestisce mai in alcun modulo sul lato servizio e da due set di proprietà. Le proprietà del broker sono predefinite dal sistema. Queste proprietà predefinite controllano le funzionalità a livello di messaggio all'interno del broker oppure sono mappate a elementi comuni e standardizzati dei metadati. Le proprietà utente sono una raccolta di coppie chiave-valore che possono essere definite e configurate dall'applicazione.

Le proprietà predefinite del broker sono elencate nella tabella seguente. I nomi vengono usati con tutte le API client ufficiali e anche nell'oggetto JSON BrokerProperties del mapping di protocolli HTTP.

I nomi equivalenti usati a livello del protocollo AMQP sono elencati tra parentesi. Mentre i nomi seguenti usano maiuscole e minuscole pascal, si noti che i client JavaScript e Python userebbero rispettivamente camel e snake maiuscole.

Nome proprietà Descrizione
ContentType (content-type) Descrive facoltativamente il payload del messaggio, con un descrittore che segue il formato RFC2045, Sezione 5, ad esempio application/json.
CorrelationId (correlation-id) Consente a un'applicazione di specificare un contesto per il messaggio per finalità di correlazione, ad esempio rispecchiando il valore MessageId di un messaggio a cui si risponde.
DeadLetterSource Impostato solo nei messaggi non recapitabili e successivamente assegnati automaticamente dalla coda di messaggi non recapitabili a un'altra entità. Indica l'entità in cui il messaggio è stato impostato come non recapitabile. Questa proprietà è di sola lettura.
DeliveryCount

Numero di tentativi di recapito per questo messaggio. Il numero viene incrementato allo scadere di un blocco di messaggio oppure quando il messaggio viene abbandonato esplicitamente dal ricevitore. Questa proprietà è di sola lettura.

Il numero di recapito non viene incrementato quando la connessione AMQP sottostante viene chiusa.
EnqueuedSequenceNumber Per i messaggi assegnati automaticamente, questa proprietà riflette il numero di sequenza assegnato per la prima volta al messaggio al punto di invio originale. Questa proprietà è di sola lettura.
EnqueuedTimeUtc Istante UTC in cui il messaggio è stato accettato e archiviato nell'entità. Questo valore può essere usato come indicatore dell'ora di arrivo autorevole e neutra quando il ricevitore non vuole considerare attendibile l'orologio del mittente. Questa proprietà è di sola lettura.
Expires​AtUtc (absolute-expiry-time) Istante UTC in cui il messaggio viene contrassegnato per la rimozione e non più disponibile per il recupero dall'entità a causa della scadenza. La scadenza viene controllata dalla proprietà TimeToLive e questa proprietà viene calcolata da EnqueuedTimeUtc+TimeToLive. Questa proprietà è di sola lettura.
Label o Subject (oggetto) Questa proprietà consente all'applicazione di indicare la finalità del messaggio al ricevitore in modo standardizzato, analogamente alla riga dell'oggetto del messaggio di posta elettronica.
Locked​Until​Utc Per i messaggi recuperati in un blocco (modalità di ricezione peek-lock, non preimpostato) questa proprietà riflette l'istante UTC fino a quando il messaggio non viene bloccato nella coda o nella sottoscrizione. Alla scadenza del blocco, la proprietà DeliveryCount viene incrementata e il messaggio è di nuovo disponibile per il recupero. Questa proprietà è di sola lettura.
Lock​Token Il token di blocco è un riferimento al blocco mantenuto dal broker nella modalità di ricezione blocco di visualizzazione. Il token può essere usato per aggiungere in modo permanente il blocco tramite l'API Differimento e quindi di estrarre il messaggio dal flusso normale dello stato di recapito. Questa proprietà è di sola lettura.
Message​Id (message-id) Questo identificatore di messaggio è un valore definito dall'applicazione che identifica in modo univoco il messaggio e il rispettivo payload. L'identificatore è una stringa freeform e può rispecchiare un GUID o un identificatore derivato dal contesto dell'applicazione. Se abilitata, la funzionalità di rilevamento duplicati identifica e rimuove il secondo invio e gli invii successivi di messaggi con lo stesso valore MessageId.
Partition​Key Per le entità partizionate, la configurazione di questo valore consente di assegnare i messaggi correlati alla stessa partizione interna, in modo che l'ordine della sequenza di invio sia registrato correttamente. La partizione viene scelta da una funzione hash su questo valore e non può essere scelta direttamente. Per entità con riconoscimento della sessione, la proprietà SessionId esegue l'override di questo valore.
Reply​To (reply-to) Questo valore facoltativo e definito dall'applicazione è un modo standard per esprimere un percorso di risposta verso il ricevitore del messaggio. Quando un mittente si aspetta una risposta, imposta il valore sul percorso assoluto o relativo della coda o dell'argomento a cui si prevede che venga inviata la risposta.
Reply​To​Session​Id (reply-to-group-id) Questo valore aumenta l'informazione ReplyTo e specifica quale valore SessionId deve essere impostato per la risposta in caso di invio all'entità di risposta.
Scheduled​Enqueue​Time​Utc Per i messaggi che vengono resi disponibili solo per il recupero dopo un ritardo, questa proprietà definisce l'istante UTC in cui il messaggio verrà sottoposto logicamente ad accodamento e sequenziamento e verrà quindi reso disponibile per il recupero.
Sequence​Number Il numero di sequenza è un numero intero univoco a 64 bit assegnato a un messaggio quando viene accettato e archiviato dal broker. Viene usato come identificatore effettivo del messaggio. Per le entità partizionate, i primi 16 bit rispecchiano l'identificatore della partizione. I numeri di sequenza vengono incrementati in modo progressivo costante e senza pause. Viene eseguito il rollover a 0 all'esaurimento dell'intervallo compreso tra 48 e 64 bit. Questa proprietà è di sola lettura.
Session​Id (group-id) Per le entità con riconoscimento della sessione, questo valore definito dall'applicazione specifica l'affiliazione di sessione del messaggio. I messaggi con lo stesso identificatore di sessione sono soggetti al blocco di riepilogo e consentono l'elaborazione esatta in ordine e il demultiplexing. Per le entità che non sono sensibili alla sessione, questo valore viene ignorato.
Time​To​Live Questo valore è la durata relativa dopo la quale il messaggio scade, a partire dall'istante in cui è stato accettato e archiviato dal broker, come acquisito in EnqueueTimeUtc. Se non è configurata in modo esplicito, il valore predefinito è il DefaultTimeToLive per la coda o l'argomento corrispondente. Un valore TimeToLive a livello di messaggio non può essere più lungo dell'impostazione DefaultTimeToLive dell'entità. Se è più lungo, viene regolato in modo invisibile all'utente.
To (a) Questa proprietà è riservata per l'uso futuro negli scenari di routing e viene attualmente ignorata dal broker. Le applicazioni possono usare questo valore negli scenari di concatenamento automatico basato su regole per indicare la destinazione logica prevista del messaggio.
Via​Partition​Key Se un messaggio viene inviato tramite una coda di trasferimento nell'ambito di una transazione, questo valore seleziona la partizione della coda di trasferimento.

Il modello di messaggio astratto consente di pubblicare un messaggio in una coda tramite HTTPS e può essere recuperato tramite AMQP. In entrambi i casi, l'aspetto del messaggio è normale nel contesto del rispettivo protocollo. Le proprietà del broker vengono convertite in base alla necessità e le proprietà utente sono mappate alla posizione più appropriata nel rispettivo modello di messaggi relativo al protocollo. In HTTP le proprietà utente sono mappate direttamente verso e dalle intestazioni HTTP. In AMQP sono mappate verso e dalla mappa applicazione-proprietà.

Routing e correlazione dei messaggi

Un sottoinsieme delle proprietà del broker illustrate in precedenza, in particolare To, ReplyTo, ReplyToSessionId, MessageId, CorrelationId e SessionId, viene usato per consentire alle applicazioni di indirizzare i messaggi verso destinazioni specifiche. Per illustrare questa funzionalità, considerare alcuni modelli:

  • Richiesta/Risposta semplice: un server di pubblicazione invia un messaggio in una coda e aspetta una risposta dal consumer del messaggio. Per ricevere la risposta, l'entità di pubblicazione è proprietaria di una coda in cui si aspetta che vengano recapitate le risposte. L'indirizzo della coda è espresso nella proprietà ReplyTo del messaggio in uscita. Quando il consumer risponde, copia il valore MessageId del messaggio gestito nella proprietà CorrelationId del messaggio di risposta e recapita il messaggio alla destinazione indicata dalla proprietà ReplyTo. Un messaggio può ottenere più risposte, in base al contesto dell'applicazione.
  • Richiesta/Risposta multicast: variazione del modello precedente in cui un server di pubblicazione invia il messaggio in un argomento e più sottoscrittori diventano consumer idonei del messaggio. Ogni sottoscrittore può rispondere come illustrato in precedenza. Questo modello viene usato in scenari di individuazione o di verifica di presenze e l'intervistato si identifica in genere con una proprietà utente o all'interno del payload. Se ReplyTo fa riferimento a un argomento, tale set di risposte di individuazione può essere distribuito a un gruppo di destinatari.
  • Multiplexing: questa funzionalità della sessione consente il multiplexing dei flussi di messaggi correlati tramite una singola coda o sottoscrizione, in modo che ogni sessione o gruppo di messaggi correlati, identificati da valori SessionId corrispondenti, venga indirizzato a un ricevitore specifico mentre il ricevitore applica un blocco alla sessione. Altre informazioni sui dettagli delle sessioni sono disponibili qui.
  • Richiesta/Risposta con multiplexing: questa funzionalità della sessione abilita le risposte con multiplexing, consentendo a diverse entità di pubblicazione di condividere una coda di risposte. Configurando il valore ReplyToSessionId, l'entità di pubblicazione può richiedere ai consumer di copiare tale valore nella proprietà SessionId del messaggio di risposta. Non è necessario che la coda di pubblicazione o l'argomento sia compatibile con la sessione. Quando il messaggio viene inviato, l'entità di pubblicazione può quindi attendere in modo specifico che nella coda si materializzi una sessione con il valore SessionId specificato, accettando in modo condizionale un ricevitore di sessione.

Il routing all'interno di uno spazio dei nomi bus di servizio può essere realizzato usando il concatenamento automatico e le regole di sottoscrizione degli argomenti. È possibile ottenere il routing tra spazi dei nomi tramite le app per la logica di Azure. Come indicato nell'esempio precedente, la proprietà To è riservata per l'uso futuro e potrebbe essere interpretata dal broker con una funzionalità abilitata in modo specifico. Le applicazioni che desiderano implementare il routing devono farlo in base alle proprietà utente e non si appoggiano alla proprietà To . Tuttavia, questa operazione non causerà problemi di compatibilità.

Serializzazione del payload

Quando è in transito o archiviato all'interno del bus di servizio, il payload è sempre un blocco binario opaco. La proprietà ContentType consente all'applicazione di descrivere il payload, con il formato suggerito per i valori della proprietà corrispondente a una descrizione di tipo contenuto MIME basata su IETF RFC2045, ad esempio application/json;charset=utf-8.

A differenza delle varianti per Java o .NET Standard, la versione .NET Framework dell'API Bus di servizio supporta la creazione di istanze di BrokeredMessage tramite il passaggio di oggetti .NET arbitrari al costruttore.

Il 30 settembre 2026 verranno ritirati le librerie bus di servizio di Azure SDK WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Il supporto del protocollo SBMP verrà terminato, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio di ritiro del supporto.

Quando si usa il protocollo SBMP legacy, tali oggetti vengono quindi serializzati con il serializzatore binario predefinito o con un serializzatore fornito esternamente. L'oggetto viene serializzato in un oggetto AMQP. Il ricevitore può recuperare tali oggetti con il metodo GetBody<T>(), fornendo il tipo previsto. Con AMQP, gli oggetti vengono serializzati in un grafico AMQP di oggetti ArrayList e IDictionary<string,object> e qualsiasi client AMQP può decodificarli.

Il 30 settembre 2026 verrà ritirato il supporto del protocollo SBMP per bus di servizio di Azure, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie sdk di bus di servizio di Azure più recenti usando il protocollo AMQP, che offre aggiornamenti critici della sicurezza e funzionalità migliorate prima di tale data.

Per altre informazioni, vedere l'annuncio di ritiro del supporto.

Anche se questa funzionalità di serializzazione nascosta è utile, le applicazioni devono assumere il controllo esplicito della serializzazione degli oggetti e trasformare i relativi grafici di oggetti in flussi prima di includerli in un messaggio e fare il contrario sul lato del destinatario. Ciò produce risultati interoperativi. Anche se AMQP ha un potente modello di codifica binaria, è associato all'ecosistema di messaggistica AMQP e i client HTTP avranno problemi di decodifica di tali payload.

Le varianti di API .NET Standard e Java accettano solo matrici di byte e quindi l'applicazione deve gestire il controllo della serializzazione degli oggetti.

Se il payload di un messaggio non può essere deserializzato, è consigliabile inviare messaggi non recapitabili al messaggio.

Passaggi successivi

Per altre informazioni sulla messaggistica del bus di servizio, vedere gli argomenti seguenti: