Condividi tramite

Messaggi, payload e serializzazione

  • Articolo

Il bus di servizio di Azure gestisce i messaggi. I messaggi trasportano un payload e metadati. I metadati hanno il formato di coppie chiave-valore, descrivono il payload e forniscono istruzioni di gestione al bus di servizio e alle 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 (Advanced Message Queuing Protocol) sono elencati tra parentesi. Mentre i nomi seguenti usano notazioni Pascal, i client JavaScript e Python usano rispettivamente notazioni Camel e Snake.

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 Viene configurata solo nei messaggi impostati come non recapitabili e successivamente inoltrati 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 recapiti non viene incrementato quando la connessione AMQP sottostante viene chiusa.
EnqueuedSequenceNumber Per i messaggi inoltrati automaticamente questa proprietà rispecchia il numero di sequenza assegnato inizialmente al messaggio nel 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 autorevole e neutro dell'ora di arrivo quando il ricevitore non vuole considerare attendibile il clock 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 risulta 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 (subject) 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 caso di blocco (modalità di ricezione blocco di visualizzazione, non pre-finalizzati), questa proprietà rispecchia l'istante UTC di termine del blocco del messaggio nella coda/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 in base a 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à senza riconoscimento della sessione, questo valore viene ignorato.
Time​To​Live Questo valore indica la durata relativa dopo cui il messaggio scade, a partire dall'istante in cui è stato accettato e archiviato dal broker, in base a quanto 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 superiore all'impostazione DefaultTimeToLive dell'entità. Viene modificato automaticamente nel caso in cui sia superiore.
To (to) Questa proprietà è riservata per l'uso futuro negli scenari di routing e viene attualmente ignorata dal broker. Le applicazioni possono usare questo valore in scenari di concatenamento con inoltro automatico basato su regole, per indicare la destinazione logica prevista per il 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 l'inserimento di un messaggio in una coda tramite HTTP e ne consente il recupero 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 eseguono il mapping direttamente verso e dalle intestazioni HTTP. In AMQP eseguono il mapping verso e dalla mappa application-properties.

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à, esaminare 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 viene 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.

È possibile ottenere il routing all'interno di uno spazio dei nomi del bus di servizio tramite il concatenamento di inoltro 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 vogliono implementare il routing devono eseguire questa operazione in base alle proprietà utente, senza affidarsi alla proprietà To. Questo approccio, tuttavia, non provocherà 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 ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, 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 del ritiro del supporto.

Quando si usa il protocollo SBMP legacy, questi oggetti vengono quindi serializzati con il serializzatore binario predefinito o con un serializzatore fornito esternamente. L'oggetto viene serializzato in un oggetto AMQP. Il destinatario 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 il bus di servizio di Azure, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti dell'SDK del bus di servizio di Azure usando il protocollo AMQP che offre aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Per altre informazioni, vedere l'annuncio del 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. Benché AMQP abbia un modello di codifica binaria avanzato, è associato all'ecosistema di messaggistica AMQP e i client HTTP decodificano con difficoltà 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.

Quando si gestisce la deserializzazione degli oggetti dal payload dei messaggi, gli sviluppatori devono tenere presente che i messaggi possono arrivare da più origini che usano metodi di serializzazione diversi. Ciò può verificarsi anche quando si evolve una singola applicazione, in cui è possibile che le versioni precedenti vengano eseguite insieme a quelle più recenti. In questi casi, è consigliabile disporre di metodi di deserializzazione aggiuntivi da poter provare se il primo tentativo di deserializzazione non ha esito positivo. Una libreria che fornisce questo tipo di supporto è NServiceBus. Se tutti i metodi di deserializzazione hanno esito negativo, è consigliabile inserire il messaggio nella coda di messaggi non recapitabili.

Passaggi successivi

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