Condividi tramite


AMQP 1.0 nel bus di servizio di Microsoft Azure: operazioni basate su richiesta/risposta

Questo articolo offre un elenco delle operazioni basate su richiesta/risposta del bus di servizio di Microsoft Azure. Le informazioni sono basate sulla bozza di lavoro di AMQP Management versione 1.0.

Per una guida dettagliata al protocollo wire-level AMQP 1.0, che illustra come il bus di servizio è basato sulla specifica tecnica OASIS AMQP e la implementa, vedere Guida al protocollo AMQP 1.0 nel bus di servizio e in Hub eventi di Azure.

Concetti

ServiceBusReceivedMessage/ServiceBusMessage

Rappresenta un messaggio nel bus di servizio mappato a un messaggio AMQP. Per la definizione del mapping, consultare la Guida al protocollo AMQP nel bus di servizio.

Eseguire il collegamento a un nodo di gestione di entità

Tutte le operazioni descritte in questo documento seguono un modello richiesta/risposta, hanno come ambito un'entità e richiedono il collegamento a un nodo di gestione di entità.

Crea un collegamento al nodo di gestione per l'invio delle richieste.

requestLink = session.attach(
role: SENDER,
   	target: { address: "<entity address>/$management" },
   	source: { address: ""<my request link unique address>" }
)

Crea un collegamento per la ricezione delle risposte dal nodo di gestione.

responseLink = session.attach(
role: RECEIVER,
	source: { address: "<entity address>/$management" }
   	target: { address: "<my response link unique address>" }
)

Trasferire un messaggio di richiesta

Trasferisce un messaggio di richiesta.
È possibile aggiungere uno stato della transazione facoltativamente per le operazioni che supportano le transazioni.

requestLink.sendTransfer(
        Message(
                properties: {
                        message-id: <request id>,
                        reply-to: "<my response link unique address>"
                },
                application-properties: {
                        "operation" -> "<operation>",
                }
        ),
        [Optional] State = transactional-state: {
                txn-id: <txn-id>
        }
)

Ricevere un messaggio di risposta

Riceve il messaggio di risposta dal collegamento per le risposte.

responseMessage = responseLink.receiveTransfer()

Il messaggio di risposta è nel modulo seguente:

Message(
properties: {
		correlation-id: <request id>
	},
	application-properties: {
			"statusCode" -> <status code>,
			"statusDescription" -> <status description>,
           },
)

Indirizzo delle entità del bus di servizio

L'indirizzo delle entità del bus di servizio deve essere definito come segue:

Tipo di entità Indirizzo Esempio
queue <queue_name> “myQueue”

“site1/myQueue”
argomento <topic_name> “myTopic”

“site2/page1/myQueue”
sottoscrizione <topic_name>/Subscriptions/<subscription_name> “myTopic/Subscriptions/MySub”

Operazioni sui messaggi

Rinnovo del blocco del messaggio

Estende il blocco di un messaggio in base alla durata del blocco impostata nella coda o nella sottoscrizione.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:renew-lock
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
lock-tokens matrice di UUID Token di blocco del messaggio da rinnovare.

Nota

Il token di blocco qui fa riferimento alla delivery-tag proprietà nel messaggio AMQP ricevuto. Se è stato ricevuto un messaggio posticipato e si vuole rinnovare il blocco, usare la proprietà lock-token nel messaggio invece di delivery-tag.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo.
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
expirations matrice di timestamp Nuova scadenza del token di blocco del messaggio corrispondente ai token di blocco della richiesta.

Visualizzazione del messaggio

Visualizza i messaggi senza blocco.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:peek-message
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
from-sequence-number long Numero di sequenza da cui iniziare la visualizzazione.
message-count int Numero massimo di messaggi da visualizzare.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) se sono presenti altri messaggi

204: (Nessun contenuto) se non sono presenti altri messaggi
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messages elenco di mapping Elenco di messaggi in cui ogni mapping rappresenta un messaggio.

Il mapping che rappresenta un messaggio deve contenere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messaggio matrice di byte Messaggio con codifica in transito AMQP 1.0.

Pianificazione del messaggio

Pianifica i messaggi. Questa operazione supporta la transazione.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:schedule-message
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messages elenco di mapping Elenco di messaggi in cui ogni mapping rappresenta un messaggio.

Il mapping che rappresenta un messaggio deve contenere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
message-id string amqpMessage.Properties.MessageId in formato stringa
session-id string No amqpMessage.Properties.GroupId as string
partition-key string No amqpMessage.MessageAnnotations.”x-opt-partition-key"
tramite chiave di partizione string No amqpMessage.MessageAnnotations."x-opt-via-partition-key"
messaggio matrice di byte Messaggio con codifica in transito AMQP 1.0.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo.
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
sequence-numbers matrice di long Numero di sequenza dei messaggi pianificati. Il numero di sequenza viene usato per l'annullamento.

Annullamento del messaggio pianificato

Annulla i messaggi pianificati.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:cancel-scheduled-message
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
sequence-numbers matrice di long Numero di sequenza dei messaggi pianificati da annullare.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo.
statusDescription string No Descrizione dello stato.

Operazioni sulle sessioni

Rinnovo del blocco della sessione

Estende il blocco di un messaggio in base alla durata del blocco impostata nella coda o nella sottoscrizione.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:renew-session-lock
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
session-id string ID sessione.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) se sono presenti altri messaggi

204: (Nessun contenuto) se non sono presenti altri messaggi
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
expiration timestamp Nuova scadenza.

Visualizzazione del messaggio di sessione

Visualizza i messaggi di sessione senza blocco.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:peek-message
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
from-sequence-number long Numero di sequenza da cui iniziare la visualizzazione.
message-count int Numero massimo di messaggi da visualizzare.
session-id string ID sessione.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) se sono presenti altri messaggi

204: (Nessun contenuto) se non sono presenti altri messaggi
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messages elenco di mapping Elenco di messaggi in cui ogni mapping rappresenta un messaggio.

Il mapping che rappresenta un messaggio deve contenere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messaggio matrice di byte Messaggio con codifica in transito AMQP 1.0.

Impostazione dello stato della sessione

Imposta lo stato di una sessione.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:set-session-state
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
session-id string ID sessione.
session-state matrice di byte Dati binari opachi.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Recupero dello stato della sessione

Recupera lo stato di una sessione.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:get-session-state
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
session-id string ID sessione.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
session-state matrice di byte Dati binari opachi.

Enumerazione delle sessioni

Enumera le sessioni per un'entità di messaggistica.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:get-message-sessions
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
last-updated-time timestamp Filtro per includere solo le sessioni aggiornate dopo un determinato momento.
skip int Numero di sessioni da ignorare.
migliori int Numero massimo di sessioni.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) se sono presenti altri messaggi

204: (Nessun contenuto) se non sono presenti altri messaggi
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
skip int Numero di sessioni ignorate se il codice di stato è 200.
sessions-ids matrice di stringhe Matrice di ID sessione se il codice di stato è 200.

Operazioni sulle regole

Aggiunta di una regola

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:add-rule
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
rule-name string Nome della regola, senza nomi di sottoscrizione e argomento.
rule-description mappa Descrizione della regola, come specificato nella sezione successiva.

Il mapping rule-description deve includere le voci seguenti, in cui sql-filter e correlation-filter si escludono a vicenda:

Chiave Tipo di valore Richiesto Contenuti del valore
sql-filter mappa sql-filter, come specificato nella sezione successiva.
correlation-filter mappa correlation-filter, come specificato nella sezione successiva.
sql-rule-action mappa sql-rule-action, come specificato nella sezione successiva.

Il mapping sql-filter deve includere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
expression string Espressione di filtro SQL.

Il mapping correlation-filter deve includere almeno una delle voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
correlation-id string No
message-id string No
a string No
reply-to string No
label string No
session-id string No
reply-to-session-id string No
content-type string No
proprietà mappa No Mappe a bus di servizio ServiceBusMessage.Properties

Il mapping sql-rule-action deve includere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
expression string Espressione di azione SQL.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Rimozione di una regola

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:remove-rule
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
rule-name string Nome della regola, senza nomi di sottoscrizione e argomento.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Regole Get

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:enumerate-rules
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
migliori int Il numero di regole da recuperare nella pagina.
skip int Il numero di regole da ignorare. Definisce l'indice iniziale (+ 1) nell'elenco di regole.

Response

Il messaggio di risposta include le proprietà seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
regole elenco di mapping Elenco di regole. Ogni regola è rappresentata da una mappa.

Ogni voce della mappa nell'elenco include le proprietà seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
rule-description oggetto descritto com.microsoft:rule-description con codice descritto AMQP 0x0000013700000004

com.microsoft.rule-description è un elenco descritto. Le proprietà sono le seguenti:

Indice Tipo di valore Richiesto Contenuti del valore
0 elenco descritto filter come specificato nella tabella successiva.
1 elenco descritto ruleAction come specificato più avanti in questa sezione.
2 string nome della regola.
3 timestamp timestamp.

filter può essere di uno dei tipi seguenti:

Nome descrittore Codice descrittore Valore
com.microsoft:sql-filter:list 0x000001370000006 Filtro SQL
com.microsoft:correlation-filter:list 0x000001370000009 Filtro di correlazione
com.microsoft:true-filter:list 0x000001370000007 Filtro true che rappresenta 1 = 1
com.microsoft:false-filter:list 0x000001370000008 Filtro false che rappresenta 1 = 0

com.microsoft:sql-filter:list è un elenco descritto, che include:

Indice Tipo di valore Richiesto Contenuti del valore
0 string Espressione filtro SQL
1 int sempre 20. Questo numero intero è il livello di compatibilità del filtro SQL. Indica la versione della sintassi del filtro SQL.

com.microsoft:correlation-filter:list è un elenco descritto, che include:

Indice (se presente) Tipo di valore Contenuti del valore
0 stringa ID correlazione
1 stringa ID del messaggio
2 stringa Task
3 stringa Rispondi a
4 stringa Etichetta
5 stringa ID sessione
6 stringa ID sessione risposta
7 stringa Tipo di contenuto
8 Mappa Mappa delle proprietà definite dall'applicazione

ruleAction può essere di uno dei tipi seguenti:

Nome descrittore Codice descrittore Valore
com.microsoft:empty-rule-action:list 0x0000013700000005 Operazione regola vuota: nessuna operazione regola presente
com.microsoft:sql-rule-action:list 0x0000013700000006 Operazione regola SQL

com.microsoft:sql-rule-action:list è un elenco descritto con due elementi.

Indice Tipo di valore Richiesto Contenuti del valore
0 string Espressione dell'azione regola SQL
1 int sempre 20. Questo numero intero è il livello di compatibilità del filtro SQL. Indica la versione della sintassi del filtro SQL.

Operazioni sui messaggi rinviati

Ricezione in base al numero di sequenza

Riceve i messaggi rinviati in base al numero di sequenza.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:receive-by-sequence-number
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
sequence-numbers matrice di long Numeri di sequenza.
receiver-settle-mode ubyte Modalità di finalizzazione del ricevitore, come indicata nella specifica di base AMQP versione 1.0.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Il corpo del messaggio di risposta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
messages elenco di mapping Elenco di messaggi in cui ogni mapping rappresenta un messaggio.

Il mapping che rappresenta un messaggio deve contenere le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
lock-token uuid Token di blocco se il valore di receiver-settle-mode è 1.
messaggio matrice di byte Messaggio con codifica in transito AMQP 1.0.

Aggiornamento dello stato di ricezione

Aggiorna lo stato di ricezione dei messaggi rinviati. Questa operazione supporta le transazioni.

Richiesta

Il messaggio di richiesta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
operation (operazione) string com.microsoft:update-disposition
com.microsoft:server-timeout uint No Timeout del server per l'operazione, in millisecondi.

Il corpo del messaggio di richiesta deve essere costituito da una sezione amqp-value contenente un mapping con le voci seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
disposition-status string completato

abandoned

suspended
lock-tokens matrice di UUID Token di blocco dei messaggi per aggiornare lo stato di ricezione.
deadletter-reason string No Può essere impostato se lo stato di ricezione è suspended.
deadletter-description string No Può essere impostato se lo stato di ricezione è suspended.
properties-to-modify mappa No Elenco delle proprietà dei messaggi negoziati del bus di servizio da modificare.

Response

Il messaggio di risposta deve includere le proprietà di applicazione seguenti:

Chiave Tipo di valore Richiesto Contenuti del valore
statusCode int Codice di risposta HTTP [RFC2616]

200 (OK) in caso di esito positivo, altro valore in caso di esito negativo
statusDescription string No Descrizione dello stato.

Passaggi successivi

Per altre informazioni su AMQP e sul bus di servizio, visitare i collegamenti seguenti: