Come usare le code del bus di servizio con Node.jsHow to use Service Bus queues with Node.js

Questo articolo illustra come usare le code del bus di servizio con Node.js.This article describes how to use Service Bus queues with Node.js. Gli esempi sono scritti in JavaScript e utilizzano il modulo Node.js di Azure.The samples are written in JavaScript and use the Node.js Azure module. Gli scenari presentati 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, vedere la sezione Passaggi successivi .For more information on 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 Node.jsCreate a Node.js application

Creare un'applicazione Node.js vuota.Create a blank Node.js application. Per istruzioni su come creare un'applicazione Node.js, vedere Creare un'app Web Node.js nel servizio app di Azure oppure Creazione e distribuzione di un'applicazione Node.js a un servizio cloud di Azure con Windows PowerShell.For instructions on how to create a Node.js application, see Create and deploy a Node.js application to an Azure Website, or Node.js Cloud Service using Windows PowerShell.

Configurare l'applicazione per l'uso del bus di servizioConfigure your application to use Service Bus

Per usare il bus di servizio di Azure, scaricare e usare il pacchetto Azure Node.jsTo use Azure Service Bus, download and use the Node.js Azure package. che include un set di librerie di riferimento che comunicano con i servizi REST del bus di servizio.This package includes a set of libraries that communicate with the Service Bus REST services.

Usare Node Package Manager (NPM) per ottenere il pacchettoUse Node Package Manager (NPM) to obtain the package

  1. Usare la finestra di comando Windows PowerShell per Node.js per passare alla cartella c:\node\sbqueues\WebRole1 in cui è stata creata l'applicazione di esempio.Use the Windows PowerShell for Node.js command window to navigate to the c:\node\sbqueues\WebRole1 folder in which you created your sample application.
  2. Digitare npm install azure nella finestra di comando, che dovrebbe restituire un output simile al seguente:Type npm install azure in the command window, which should result in output similar to the following:

    azure@0.7.5 node_modules\azure
        ├── dateformat@1.0.2-1.2.3
        ├── xmlbuilder@0.4.2
        ├── node-uuid@1.2.0
        ├── mime@1.2.9
        ├── underscore@1.4.4
        ├── validator@1.1.1
        ├── tunnel@0.0.2
        ├── wns@0.5.3
        ├── xml2js@0.2.7 (sax@0.5.2)
        └── request@2.21.0 (json-stringify-safe@4.0.0, forever-agent@0.5.0, aws-sign@0.3.0, tunnel-agent@0.3.0, oauth-sign@0.3.0, qs@0.6.5, cookie-jar@0.3.0, node-uuid@1.4.0, http-signature@0.9.11, form-data@0.0.8, hawk@0.13.1)
    
  3. È possibile eseguire manualmente il comando ls per verificare che sia stata creata una cartella node_modules.You can manually run the ls command to verify that a node_modules folder was created. All'interno di tale cartella individuare il pacchetto azure, che contiene le librerie necessarie per accedere alle code del bus di servizio.Inside that folder find the azure package, which contains the libraries you need to access Service Bus queues.

Importare il moduloImport the module

Usando il Blocco note o un altro editor di testo, aggiungere quanto segue alla parte superiore del file server.js dell'applicazione:Using Notepad or another text editor, add the following to the top of the server.js file of the application:

var azure = require('azure');

Configurare una connessione del bus di servizio di AzureSet up an Azure Service Bus connection

Il modulo di Azure legge la variabile di ambiente AZURE_SERVICEBUS_CONNECTION_STRING per ottenere le informazioni necessarie per la connessione al bus di servizio.The Azure module reads the environment variable AZURE_SERVICEBUS_CONNECTION_STRING to obtain information required to connect to Service Bus. Se questa variabile di ambiente non è impostata, è necessario specificare le informazioni relative all'account durante la chiamata di createServiceBusService.If this environment variable is not set, you must specify the account information when calling createServiceBusService.

Per un esempio di impostazione delle variabili di ambiente in un file di configurazione per un servizio cloud di Azure, vedere Creazione di un'applicazione Web Node.js con Archiviazione.For an example of setting the environment variables in a configuration file for an Azure Cloud Service, see Node.js Cloud Service with Storage.

Per un esempio di impostazione delle variabili di ambiente nel portale di Azure per un sito Web di Azure, vedere Node.js Web Application with Storage (Applicazione Web Node.js con Archiviazione di Azure).For an example of setting the environment variables in the Azure portal for an Azure Website, see Node.js Web Application with Storage.

Creare una codaCreate a queue

L'oggetto ServiceBusService consente di usare le code del bus di servizio.The ServiceBusService object enables you to work with Service Bus queues. Il codice seguente consente di creare un oggetto ServiceBusService.The following code creates a ServiceBusService object. Aggiungerlo nella parte superiore del file server.js dopo l'istruzione per importare il modulo Azure:Add it near the top of the server.js file, after the statement to import the Azure module:

var serviceBusService = azure.createServiceBusService();

Chiamando createQueueIfNotExists nell'oggetto ServiceBusService, viene restituita la coda specificata, se esistente, oppure viene creata una nuova coda con il nome specificato.By calling createQueueIfNotExists on the ServiceBusService object, the specified queue is returned (if it exists), or a new queue with the specified name is created. Il codice seguente usa createQueueIfNotExists per connettersi alla coda denominata myqueue o crearla:The following code uses createQueueIfNotExists to create or connect to the queue named myqueue:

serviceBusService.createQueueIfNotExists('myqueue', function(error){
    if(!error){
        // Queue exists
    }
});

Il metodo createServiceBusService supporta anche opzioni aggiuntive che consentono di eseguire l'override delle impostazioni predefinite delle code, come la durata (TTL) dei messaggi o le dimensioni massime della coda.The createServiceBusService method also supports additional options, which enable you to override 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 (TTL) di 1 minuto:The following example sets the maximum queue size to 5 GB, and a time to live (TTL) value of 1 minute:

var queueOptions = {
      MaxSizeInMegabytes: '5120',
      DefaultMessageTimeToLive: 'PT1M'
    };

serviceBusService.createQueueIfNotExists('myqueue', queueOptions, function(error){
    if(!error){
        // Queue exists
    }
});

FiltriFilters

Le operazioni di filtro facoltative possono essere applicate alle operazioni eseguite usando ServiceBusService.Optional filtering operations can be applied to operations performed using ServiceBusService. Le operazioni di filtro possono includere la registrazione, la ripetizione automatica dei tentativi e così via. I filtri sono oggetti che implementano un metodo con la firma:Filtering operations can include logging, automatically retrying, etc. Filters are objects that implement a method with the signature:

function handle (requestOptions, next)

Dopo avere eseguito la pre-elaborazione sulle opzioni della richiesta, il metodo deve chiamare next passando un callback con la seguente firma:After doing its pre-processing on the request options, the method must call next, passing a callback with the following signature:

function (returnObject, finalCallback, next)

Dopo l'elaborazione di returnObject (ossia della risposta della richiesta al server), questo callback deve richiamare next, se esistente, per continuare a elaborare altri filtri oppure richiamare semplicemente finalCallback per terminare la chiamata al servizio.In this callback, and after processing the returnObject (the response from the request to the server), the callback must either invoke next if it exists to continue processing other filters, or simply invoke finalCallback, which ends the service invocation.

In Azure SDK per Node.js sono inclusi due filtri che implementano la logica di ripetizione dei tentativi, ExponentialRetryPolicyFilter e LinearRetryPolicyFilter.Two filters that implement retry logic are included with the Azure SDK for Node.js, ExponentialRetryPolicyFilter and LinearRetryPolicyFilter. Il codice seguente crea un oggetto ServiceBusService che usa ExponentialRetryPolicyFilter:The following code creates a ServiceBusService object that uses the ExponentialRetryPolicyFilter:

var retryOperations = new azure.ExponentialRetryPolicyFilter();
var serviceBusService = azure.createServiceBusService().withFilter(retryOperations);

Inviare messaggi a una codaSend messages to a queue

Per inviare un messaggio a una coda del bus di servizio, l'applicazione chiama il metodo sendQueueMessage per l'oggetto ServiceBusService.To send a message to a Service Bus queue, your application calls the sendQueueMessage method on the ServiceBusService object. I messaggi inviati e ricevuti dalle code del bus di servizio sono oggetti BrokeredMessage e includono un set di proprietà standard, ad esempio Label e TimeToLive, un dizionario usato per contenere le proprietà personalizzate specifiche dell'applicazione e un corpo di dati arbitrari dell'applicazione.Messages sent to (and received from) Service Bus queues are BrokeredMessage objects, and have a set of standard properties (such as Label and TimeToLive), 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 una stringa come messaggio.An application can set the body of the message by passing a string as the message. Le proprietà standard necessarie vengono popolate con i valori predefiniti.Any required standard properties are populated with default values.

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

var message = {
    body: 'Test message',
    customProperties: {
        testproperty: 'TestValue'
    }};
serviceBusService.sendQueueMessage('myqueue', message, function(error){
    if(!error){
        // message sent
    }
});

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. Per altre informazioni sulle quote, vedere Quote del bus di servizio.For more information about quotas, see Service Bus quotas.

Ricevere messaggi da una codaReceive messages from a queue

I messaggi vengono ricevuti da una coda usando il metodo receiveQueueMessage nell'oggetto ServiceBusService.Messages are received from a queue using the receiveQueueMessage method on the ServiceBusService object. Per impostazione predefinita, i messaggi vengono eliminati dalla coda non appena vengono letti. È tuttavia possibile leggere (visualizzare) e bloccare il messaggio senza eliminarlo dalla coda impostando il parametro facoltativo isPeekLock su true.By default, messages are deleted from the queue as they are read; however, you can read (peek) and lock the message without deleting it from the queue by setting the optional parameter isPeekLock to true.

Il comportamento predefinito di lettura ed eliminazione del messaggio nell'ambito dell'operazione di ricezione costituisce il modello più semplice ed è adatto per scenari in cui un'applicazione può tollerare la mancata elaborazione di un messaggio in caso di errore.The default behavior of reading and deleting the message as part of the receive operation is 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 contrassegna il messaggio come utilizzato, quando l'applicazione viene riavviata e inizia a utilizzare nuovamente i messaggi, il messaggio utilizzato prima dell'arresto anomalo risulterà perso.Because Service Bus will have marked the message as being consumed, then when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

Se il parametro isPeekLock è impostato su true, l'operazione di ricezione viene suddivisa in due fasi, in modo da consentire il supporto di applicazioni che non possono tollerare messaggi mancanti.If the isPeekLock parameter is set to true, the receive becomes a two stage operation, which 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 deleteMessage 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 deleteMessage method and providing the message to be deleted as a parameter. Il metodo deleteMessage contrassegna il messaggio come utilizzato e lo rimuove dalla coda.The deleteMessage method marks the message as being consumed and removes it from the queue.

L'esempio seguente illustra come ricevere ed elaborare messaggi usando receiveQueueMessage.The following example demonstrates how to receive and process messages using receiveQueueMessage. L'esempio prima di tutto riceve ed elimina un messaggio, quindi riceve un messaggio con isPeekLock impostato su true e infine elimina il messaggio con deleteMessage:The example first receives and deletes a message, and then receives a message using isPeekLock set to true, then deletes the message using deleteMessage:

serviceBusService.receiveQueueMessage('myqueue', function(error, receivedMessage){
    if(!error){
        // Message received and deleted
    }
});
serviceBusService.receiveQueueMessage('myqueue', { isPeekLock: true }, function(error, lockedMessage){
    if(!error){
        // Message received and locked
        serviceBusService.deleteMessage(lockedMessage, function (deleteError){
            if(!deleteError){
                // Message deleted
            }
        });
    }
});

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 ricevente non riesce a elaborare il messaggio per qualsiasi motivo, può chiamare il metodo unlockMessage nell'oggetto ServiceBusService.If a receiver application is unable to process the message for some reason, then it can call the unlockMessage method on the ServiceBusService object. In questo modo, il bus di servizio sbloccherà il messaggio nella coda rendendolo nuovamente disponibile per la ricezione da parte della stessa o da un'altra applicazione consumer.This will cause 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 (e.g., if the application crashes), then Service Bus will unlock the message automatically and make it available to be received again.

In caso di arresto anomalo dell'applicazione dopo l'elaborazione del messaggio ma prima della chiamata del metodo deleteMessage, il messaggio verrà nuovamente recapitato all'applicazione al riavvio.In the event that the application crashes after processing the message but before the deleteMessage method is called, then the message will be redelivered to the application when it restarts. Questo processo di elaborazione 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 is often called At Least Once Processing, that is, each message will be 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à MessageId del messaggio, che rimane costante in tutti i tentativi di recapito.This is often achieved using the MessageId property of the message, which will remain constant across delivery attempts.

Passaggi successiviNext steps

Per altre informazioni sulle code, vedere le risorse seguenti.To learn more about queues, see the following resources.