Come usare le code del bus di servizio con RubyHow to use Service Bus queues with Ruby

Questa guida illustra come usare le code del bus di servizio.This guide describes how to use Service Bus queues. Gli esempi sono scritti in Ruby e utilizzano la gemma di Azure.The samples are written in Ruby and use the Azure gem. Gli scenari illustrati includono la creazione di code, l'invio e la ricezione di messaggi e l'eliminazione di code.The scenarios covered include creating queues, sending and receiving messages, and deleting queues. Per altre informazioni sulle code del bus di servizio, vedere la sezione Passaggi successivi .For more information about Service Bus queues, see the Next Steps section.

Informazioni sulle code del bus di servizioWhat are Service Bus queues?

Le code del bus di servizio supportano un modello di comunicazione con messaggistica negoziata .Service Bus queues support a brokered messaging communication model. Quando si usano le code, i componenti di un'applicazione distribuita non comunicano direttamente l'uno con l'altro, ma scambiano messaggi tramite una coda, che agisce da intermediario (broker).When using queues, components of a distributed application do not communicate directly with each other; instead they exchange messages via a queue, which acts as an intermediary (broker). Un producer di messaggi (mittente) invia un messaggio alla coda e quindi prosegue con la relativa elaborazione.A message producer (sender) hands off a message to the queue and then continues its processing. In modo asincrono, il consumer di messaggi (ricevitore) recupera il messaggio dalla coda e lo elabora.Asynchronously, a message consumer (receiver) pulls the message from the queue and processes it. Il producer non deve attendere la risposta del consumer per continuare a elaborare e inviare ulteriori messaggi.The producer does not have to wait for a reply from the consumer in order to continue to process and send further messages. Le code consentono un recapito dei messaggi di tipo FIFO (First In, First Out) a uno o più consumer concorrenti.Queues offer First In, First Out (FIFO) message delivery to one or more competing consumers. In base a questo metodo, in genere i messaggi vengono ricevuti ed elaborati nell'ordine temporale in cui sono stati aggiunti alla coda e ogni messaggio viene ricevuto ed elaborato da un solo consumer.That is, messages are typically received and processed by the receivers in the order in which they were added to the queue, and each message is received and processed by only one message consumer.

Concetti relativi alle code

Le code del bus di servizio sono una tecnologia di carattere generale che può essere usata in numerosi scenari:Service Bus queues are a general-purpose technology that can be used for a wide variety of scenarios:

  • Comunicazione tra ruoli Web e di lavoro in un'applicazione Azure multilivello.Communication between web and worker roles in a multi-tier Azure application.
  • Comunicazione tra app locali e app ospitate in Azure in una soluzione ibrida.Communication between on-premises apps and Azure-hosted apps in a hybrid solution.
  • Comunicazione tra componenti di un'applicazione distribuita in esecuzione in locale in organizzazioni diverse o in reparti diversi della stessa organizzazione.Communication between components of a distributed application running on-premises in different organizations or departments of an organization.

L'uso delle code consente la scalabilità delle applicazioni e garantisce maggiore resilienza all'architettura.Using queues enables you to scale your applications more easily, and enable more resiliency to your architecture.

Per iniziare a usare le entità di messaggistica del bus di servizio in Azure, prima di tutto è necessario creare uno spazio dei nomi con un nome univoco in Azure.To begin using Service Bus messaging entities in Azure, you must first create a namespace with a name that is unique across Azure. Uno spazio dei nomi fornisce un contenitore di ambito per fare riferimento alle risorse del bus di servizio all'interno dell'applicazione.A namespace provides a scoping container for addressing Service Bus resources within your application.

Per creare uno spazio dei nomi:To create a namespace:

  1. Accedere al portale di Azure.Log on to the Azure portal.
  2. Nel riquadro di spostamento sinistro del portale fare clic su Nuovo, quindi su Enterprise Integration e infine su Bus di servizio.In the left navigation pane of the portal, click New, then click Enterprise Integration, and then click Service Bus.
  3. Nella finestra di dialogo Crea spazio dei nomi immettere un nome per lo spazio dei nomi.In the Create namespace dialog, enter a namespace name. Verrà effettuato immediatamente un controllo sulla disponibilità del nome.The system immediately checks to see if the name is available.
  4. Dopo aver verificato che il nome dello spazio dei nomi sia disponibile, scegliere il piano tariffario, ovvero Basic, Standard o Premium.After making sure the namespace name is available, choose the pricing tier (Basic, Standard, or Premium).
  5. Nel campo Sottoscrizione scegliere una sottoscrizione di Azure in cui creare lo spazio dei nomi.In the Subscription field, choose an Azure subscription in which to create the namespace.
  6. Nel campo Gruppo di risorse scegliere un gruppo di risorse esistente nel quale risiederà lo spazio dei nomi oppure crearne uno nuovo.In the Resource group field, choose an existing resource group in which the namespace will live, or create a new one.
  7. In Localitàscegliere il paese o l'area in cui deve essere ospitato lo spazio dei nomi.In Location, choose the country or region in which your namespace should be hosted.

    Crea spazio dei nomi

  8. Fare clic su Crea.Click Create. A questo punto, lo spazio dei nomi verrà creato e abilitato nel sistema.The system now creates your namespace and enables it. Potrebbero essere necessari alcuni minuti per consentire al sistema di effettuare il provisioning delle risorse per lo spazio dei nomi creato.You might have to wait several minutes as the system provisions resources for your account.

Ottenere le credenziali di gestioneObtain the management credentials

Con la creazione di un nuovo spazio dei nomi verrà generata automaticamente una regola di firma di accesso condiviso iniziale con una coppia di chiavi primaria e secondaria associata che concede il controllo completo di tutti gli aspetti dello spazio dei nomi.Creating a new namespace will automatically generate an initial Shared Access Signature (SAS) rule with an associated pair of primary and secondary keys that grants full control over all aspects of the namespace. Vedere Autenticazione e autorizzazione del bus di servizio per informazioni su come creare altre regole con diritti più limitati per mittenti e destinatari normali.Refer to Service Bus authentication and authorization for how to create further rules with more constrained rights for regular senders and receivers. Per copiare la regola iniziale seguire questa procedura:To copy the initial rule, follow these steps:

  1. Nell'elenco degli spazi dei nomi fare clic sul nome dello spazio dei nomi appena creato.In the list of namespaces, click the newly created namespace name.
  2. Nel pannello dello spazio dei nomi fare clic su Criteri di accesso condivisi.In the namespace blade, click Shared access policies.
  3. Nel pannello Criteri di accesso condivisi fare clic su RootManageSharedAccessKey.In the Shared access policies blade, click RootManageSharedAccessKey.

    connection-info

  4. Nel pannello Criteri: RootManageSharedAccessKey fare clic sul pulsante Copia accanto a Stringa di connessione - chiave primaria per copiare la stringa di connessione negli Appunti e usarla in un secondo momento.In the Policy: RootManageSharedAccessKey blade, click the copy button next to Connection string–primary key, to copy the connection string to your clipboard for later use. Incollare questo valore nel Blocco note o in un'altra posizione temporanea.Paste this value into Notepad or some other temporary location.

    connection-string

  5. Ripetere il passaggio precedente e copiare e incollare il valore della chiave primaria in un percorso temporaneo per usarlo in seguito.Repeat the previous step, copying and pasting the value of Primary key to a temporary location for later use.

Creare un'applicazione RubyCreate a Ruby application

Per istruzioni, vedere Creare un'applicazione Ruby in Azure.For instructions, see Create a Ruby Application on Azure.

Configurare l'applicazione per l'uso del bus di servizioConfigure Your application to Use Service Bus

Per usare il bus di servizio, scaricare e usare il pacchetto Ruby di Azure, che comprende un set di pratiche librerie che comunicano con i servizi REST di archiviazione.To use Service Bus, download and use the Azure Ruby package, which includes a set of convenience libraries that communicate with the storage REST services.

Utilizzare RubyGems per ottenere il pacchettoUse RubyGems to obtain the package

  1. Usare un'interfaccia della riga di comando, ad esempio PowerShell (Windows), Terminal (Mac) o Bash (Unix).Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Digitare "gem install azure" nella finestra di comando per installare la gemma e le dipendenze.Type "gem install azure" in the command window to install the gem and dependencies.

Importare il pacchettoImport the package

Usando l'editor di testo preferito aggiungere quanto segue alla parte superiore del file Ruby dove si intende usare l'archiviazione:Using your favorite text editor, add the following to the top of the Ruby file in which you intend to use storage:

require "azure"

Configurare una stringa di connessione per il bus di servizioSet up a Service Bus connection

Usare il codice seguente per impostare i valori dello spazio dei nomi, il nome della chiave, la chiave, il firmatario e l'host:Use the following code to set the values of namespace, name of the key, key, signer and host:

Azure.configure do |config|
  config.sb_namespace = '<your azure service bus namespace>'
  config.sb_sas_key_name = '<your azure service bus access keyname>'
  config.sb_sas_key = '<your azure service bus access key>'
end
signer = Azure::ServiceBus::Auth::SharedAccessSigner.new
sb_host = "https://#{Azure.sb_namespace}.servicebus.windows.net"

Impostare il valore dello spazio dei nomi sul valore creato invece che sull'intero URL.Set the namespace value to the value you created rather than the entire URL. Ad esempio, usare "yourexamplenamespace" e non "yourexamplenamespace.servicebus.windows.net".For example, use "yourexamplenamespace", not "yourexamplenamespace.servicebus.windows.net".

Come creare una codaHow to create a queue

L'oggetto Azure::ServiceBusService consente di usare le code.The Azure::ServiceBusService object enables you to work with queues. Per creare una coda, usare il metodo create_queue().To create a queue, use the create_queue() method. Nel seguente esempio viene creata una coda o stampato l'eventuale errore.The following example creates a queue or prints out any errors.

azure_service_bus_service = Azure::ServiceBus::ServiceBusService.new(sb_host, { signer: signer})
begin
  queue = azure_service_bus_service.create_queue("test-queue")
rescue
  puts $!
end

È anche possibile passare un oggetto Azure::ServiceBus::Queue con opzioni aggiuntive che consentono di sostituire le impostazioni predefinite delle code, ad esempio la durata dei messaggi o la dimensione massima della coda.You can also pass a Azure::ServiceBus::Queue object with additional options, which enables you to override the default queue settings, such as message time to live or maximum queue size. Il seguente esempio illustra come impostare la dimensione massima della coda su 5 GB e una durata di 1 minuto:The following example shows how to set the maximum queue size to 5 GB and time to live to 1 minute:

queue = Azure::ServiceBus::Queue.new("test-queue")
queue.max_size_in_megabytes = 5120
queue.default_message_time_to_live = "PT1M"

queue = azure_service_bus_service.create_queue(queue)

Come inviare messaggi a una codaHow to send messages to a queue

Per inviare un messaggio a una coda del bus di servizio, l'applicazione chiama il metodo send_queue_message() per l'oggetto Azure::ServiceBusService.To send a message to a Service Bus queue, your application calls the send_queue_message() method on the Azure::ServiceBusService object. I messaggi inviati e ricevuti dalle code del bus di servizio sono oggetti Azure::ServiceBus::BrokeredMessage e includono un set di proprietà standard, ad esempio label e time_to_live, un dizionario usato per mantenere le proprietà personalizzate specifiche dell'applicazione e un corpo di dati arbitrari dell'applicazione.Messages sent to (and received from) Service Bus queues are Azure::ServiceBus::BrokeredMessage objects, and have a set of standard properties (such as label and time_to_live), a dictionary that is used to hold custom application-specific properties, and a body of arbitrary application data. Un'applicazione può impostare il corpo del messaggio passando un valore stringa come messaggio, in modo da popolare le proprietà standard necessarie con valori predefiniti.An application can set the body of the message by passing a string value as the message and any required standard properties are populated with default values.

L'esempio seguente illustra come inviare un messaggio di prova alla coda denominata test-queue usando send_queue_message():The following example demonstrates how to send a test message to the queue named test-queue using send_queue_message():

message = Azure::ServiceBus::BrokeredMessage.new("test queue message")
message.correlation_id = "test-correlation-id"
azure_service_bus_service.send_queue_message("test-queue", message)

Le code del bus di servizio supportano messaggi di dimensioni fino a 256 KB nel livello Standard e fino a 1 MB nel livello Premium.Service Bus queues support a maximum message size of 256 KB in the Standard tier and 1 MB in the Premium tier. Le dimensioni massime dell'intestazione, che include le proprietà standard e personalizzate dell'applicazione, non possono superare 64 KB.The header, which includes the standard and custom application properties, can have a maximum size of 64 KB. Non esiste alcun limite al numero di messaggi mantenuti in una coda, mentre è prevista una limitazione alla dimensione totale dei messaggi di una coda.There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. Questa dimensione della coda viene definita al momento della creazione, con un limite massimo di 5 GB.This queue size is defined at creation time, with an upper limit of 5 GB.

Come ricevere messaggi da una codaHow to receive messages from a queue

I messaggi vengono ricevuti da una coda tramite il metodo receive_queue_message() per l'oggetto Azure::ServiceBusService.Messages are received from a queue using the receive_queue_message() method on the Azure::ServiceBusService object. Per impostazione predefinita, i messaggi vengono letti e bloccati senza essere eliminati dalla coda.By default, messages are read and locked without being deleted from the queue. È tuttavia possibile eliminare i messaggi dalla coda dopo essere stati letti impostando l'opzione :peek_lock su false.However, you can delete messages from the queue as they are read by setting the :peek_lock option to false.

In base al comportamento predefinito, la lettura e l'eliminazione vengono incluse in un'operazione di ricezione suddivisa in due fasi, in modo da consentire anche il supporto di applicazioni che non possono tollerare messaggi mancanti.The default behavior makes the reading and deleting a two-stage operation, which also makes it possible to support applications that cannot tolerate missing messages. Quando il bus di servizio riceve una richiesta, individua il messaggio successivo da usare, lo blocca per impedirne la ricezione da parte di altri consumer e quindi lo restituisce all'applicazione.When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers receiving it, and then returns it to the application. Dopo aver elaborato il messaggio o averlo archiviato in modo affidabile per una successiva elaborazione, l'applicazione esegue la seconda fase del processo di ricezione chiamando il metodo delete_queue_message() e specificando il messaggio da eliminare come parametro.After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by calling delete_queue_message() method and providing the message to be deleted as a parameter. Il metodo delete_queue_message() contrassegna il messaggio come usato e lo rimuove dalla coda.The delete_queue_message() method will mark the message as being consumed and remove it from the queue.

Se il parametro :peek_lock è impostato su false, la lettura e l'eliminazione del messaggio costituiscono il modello più semplice, adatto a scenari in cui un'applicazione può tollerare la mancata elaborazione di un messaggio in caso di errore.If the :peek_lock parameter is set to false, reading and deleting the message becomes the simplest model, and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. Per comprendere meglio questo meccanismo, si consideri uno scenario in cui il consumer invia la richiesta di ricezione e viene arrestato in modo anomalo prima dell'elaborazione.To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Poiché il bus di servizio ha contrassegnato il messaggio come utilizzato, quando l'applicazione viene riavviata e inizia a usare nuovamente i messaggi, il messaggio usato prima dell'arresto anomalo del sistema risulterà perso.Because Service Bus has marked the message as being consumed, when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

Nell'esempio seguente viene illustrato come ricevere ed elaborare i messaggi tramite receive_queue_message().The following example demonstrates how to receive and process messages using receive_queue_message(). Nell'esempio viene prima ricevuto ed eliminato un messaggio tramite :peek_lock impostato su false e successivamente viene ricevuto ed eliminato un altro messaggio tramite delete_queue_message():The example first receives and deletes a message by using :peek_lock set to false, then it receives another message and then deletes the message using delete_queue_message():

message = azure_service_bus_service.receive_queue_message("test-queue",
  { :peek_lock => false })
message = azure_service_bus_service.receive_queue_message("test-queue")
azure_service_bus_service.delete_queue_message(message)

Come gestire arresti anomali e messaggi illeggibili dell'applicazioneHow to handle application crashes and unreadable messages

Il bus di servizio fornisce funzionalità per il ripristino gestito automaticamente in caso di errori nell'applicazione o di problemi di elaborazione di un messaggio.Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. Se un'applicazione del ricevitore non è in grado di elaborare il messaggio per un qualsiasi motivo, può chiamare il metodo unlock_queue_message() sull'oggetto Azure::ServiceBusService.If a receiver application is unable to process the message for some reason, then it can call the unlock_queue_message() method on the Azure::ServiceBusService object. Con questa chiamata il bus di servizio sblocca il messaggio nella coda rendendolo nuovamente disponibile per la ricezione da parte della stessa o di un'altra applicazione consumer.This call causes Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.

Al messaggio bloccato nella coda è inoltre associato un timeout. Se l'applicazione non riesce a elaborare il messaggio prima della scadenza del timeout, ad esempio a causa di un arresto anomalo, il bus di servizio sbloccherà automaticamente il messaggio rendendolo nuovamente disponibile per la ricezione.There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus unlocks the message automatically and makes it available to be received again.

In caso di arresto anomalo dell'applicazione dopo l'elaborazione del messaggio ma prima della chiamata del metodo delete_queue_message(), il messaggio viene nuovamente recapitato all'applicazione al riavvio.In the event that the application crashes after processing the message but before the delete_queue_message() method is called, then the message is redelivered to the application when it restarts. Questo processo viene spesso definito di tipo At-Least-Once, per indicare che ogni messaggio verrà elaborato almeno una volta ma che in determinate situazioni potrà essere recapitato una seconda volta.This process is often called At Least Once Processing; that is, each message is processed at least once but in certain situations the same message may be redelivered. Se lo scenario non tollera la doppia elaborazione, gli sviluppatori dovranno aggiungere logica aggiuntiva all'applicazione per gestire il secondo recapito del messaggio.If the scenario cannot tolerate duplicate processing, then application developers should add additional logic to their application to handle duplicate message delivery. A tale scopo viene spesso usata la proprietà message_id del messaggio, che rimane costante in tutti i tentativi di recapito.This is often achieved using the message_id property of the message, which remains constant across delivery attempts.

Passaggi successiviNext steps

A questo punto, dopo aver appreso le nozioni di base delle code del bus di servizio, usare i collegamenti seguenti per altre informazioni.Now that you've learned the basics of Service Bus queues, follow these links to learn more.

Per un confronto tra le code del bus di servizio di Azure discusse in questo articolo e le code di Azure discusse nell'articolo Come usare l'archiviazione di accodamento da Ruby, vedere Analogie e differenze tra le code di Azure e le code del bus di servizio.For a comparison between the Azure Service Bus queues discussed in this article and Azure Queues discussed in the How to use Queue storage from Ruby article, see Azure Queues and Azure Service Bus Queues - Compared and Contrasted