Come usare gli argomenti e le sottoscrizioni del bus di servizio con PHPHow to use Service Bus topics and subscriptions with PHP

In questo articolo verrà descritto come usare gli argomenti e le sottoscrizioni del bus di servizio.This article shows you how to use Service Bus topics and subscriptions. Gli esempi sono scritti in PHP e usano Azure SDK per PHP.The samples are written in PHP and use the Azure SDK for PHP. Gli scenari presentati includono la creazione di argomenti e sottoscrizioni, la creazione di filtri per le sottoscrizioni, l’invio di messaggi a un argomento, la ricezione di messaggi da una sottoscrizione e l’eliminazione di argomenti e sottoscrizioni.The scenarios covered include creating topics and subscriptions, creating subscription filters, sending messages to a topic, receiving messages from a subscription, and deleting topics and subscriptions.

Cosa sono gli argomenti e le sottoscrizioni del bus di servizio?What are Service Bus topics and subscriptions?

Gli argomenti e le sottoscrizioni del bus di servizio supportano un modello di comunicazione con messaggistica di pubblicazione-sottoscrizione .Service Bus topics and subscriptions support a publish/subscribe messaging communication model. Quando si usano gli argomenti e le sottoscrizioni, i componenti di un'applicazione distribuita non comunicano direttamente l'uno con l'altro, ma scambiano messaggi tramite un argomento, che agisce da intermediario.When using topics and subscriptions, components of a distributed application do not communicate directly with each other; instead they exchange messages via a topic, which acts as an intermediary.

Concetti relativi agli argomenti

Diversamente dalle code del bus di servizio, in cui ogni messaggio viene elaborato da un unico consumer, gli argomenti e le sottoscrizioni offrono una forma di comunicazione "uno a molti" tramite un modello di pubblicazione-sottoscrizione.In contrast with Service Bus queues, in which each message is processed by a single consumer, topics and subscriptions provide a "one-to-many" form of communication, using a publish/subscribe pattern. È possibile registrare più sottoscrizioni a un argomento.It is possible to register multiple subscriptions to a topic. Quando un messaggio viene inviato a un argomento, viene reso disponibile affinché ogni sottoscrizione possa gestirlo o elaborarlo in modo indipendente.When a message is sent to a topic, it is then made available to each subscription to handle/process independently.

La sottoscrizione a un argomento è simile a una coda virtuale che riceve copie dei messaggi che sono stati inviati all'argomento.A subscription to a topic resembles a virtual queue that receives copies of the messages that were sent to the topic. È possibile registrare regole di filtro per un argomento in base alla sottoscrizione, per poter filtrare o limitare quali messaggi relativi a un argomento vengono ricevuti dalle diverse sottoscrizioni dell'argomento.You can optionally register filter rules for a topic on a per-subscription basis, which enables you to filter or restrict which messages to a topic are received by which topic subscriptions.

Gli argomenti e le sottoscrizioni del bus di servizio consentono la scalabilità e l'elaborazione di grandi quantità di messaggi tra un numero elevato di utenti e applicazioni.Service Bus topics and subscriptions enable you to scale and process a very large number of messages across many users and applications.

Creare uno spazio dei nomiCreate a namespace

Per iniziare a usare gli argomenti e le sottoscrizioni del bus di servizio in Azure, è necessario creare prima di tutto uno spazio dei nomi del servizio.To begin using Service Bus topics and subscriptions in Azure, you must first create a service namespace. 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. Selezionare il pulsante Create .Click the Create button. 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 credenzialiObtain the credentials

  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 Spazio dei nomi del bus di servizio fare clic su Criteri di accesso condiviso.In the Service Bus 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.

    connection-string

Creare un'applicazione PHPCreate a PHP application

Per creare un'applicazione PHP che acceda al servizio BLOB di Azure, è sufficiente fare riferimento alle classi in Azure SDK per PHP dall'interno del codice.The only requirement for creating a PHP application that accesses the Azure Blob service is to reference classes in the Azure SDK for PHP from within your code. Per creare l'applicazione, è possibile usare qualsiasi strumento di sviluppo o il Blocco note.You can use any development tools to create your application, or Notepad.

Nota

L'installazione di PHP deve avere anche l'estensione OpenSSL installata e abilitata.Your PHP installation must also have the OpenSSL extension installed and enabled.

Questo articolo illustra come usare le funzionalità del servizio che possono essere chiamate in un'applicazione PHP in locale o nel codice in esecuzione in un ruolo Web, in un ruolo di lavoro o in un sito Web di Azure.This article describes how to use service features that can be called within a PHP application locally, or in code running within an Azure web role, worker role, or website.

Acquisire le librerie client di AzureGet the Azure client libraries

Installazione tramite ComposerInstall via Composer

  1. Creare un file denominato composer.json nella radice del progetto, quindi aggiungere nel file il codice seguente:Create a file named composer.json in the root of your project and add the following code to it:

    {
      "require": {
        "microsoft/azure-storage": "*"
      }
    }
    
  2. Scaricare composer.phar nella radice del progetto.Download composer.phar in your project root.
  3. Aprire un prompt dei comandi ed eseguire il comando seguente nella radice del progettoOpen a command prompt and execute the following command in your project root

    php composer.phar install
    

In alternativa andare alla libreria client PHP di Archiviazione di Microsoft Azure su GitHub per clonare il codice sorgente.Alternatively go to the Azure Storage PHP Client Library on GitHub to clone the source code.

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

Per usare le API del bus di servizio:To use the Service Bus APIs:

  1. Fare riferimento al file autoloader mediante l'istruzione require_once.Reference the autoloader file using the require_once statement.
  2. Fare riferimento a tutte le eventuali classi utilizzabili.Reference any classes you might use.

Nell'esempio seguente viene indicato come includere il file autoloader e fare riferimento alla classe ServiceBusService.The following example shows how to include the autoloader file and reference the ServiceBusService class.

Nota

Questo esempio (e in altri esempi in questo articolo) presuppone che siano state installate le librerie client PHP per Azure tramite Composer.This example (and other examples in this article) assumes you have installed the PHP Client Libraries for Azure via Composer. Se le librerie sono state installate manualmente o come pacchetto PEAR, è necessario fare riferimento al file autoloader WindowsAzure.php.If you installed the libraries manually or as a PEAR package, you must reference the WindowsAzure.php autoloader file.

require_once 'vendor\autoload.php';
use WindowsAzure\Common\ServicesBuilder;

Negli esempi seguenti l'istruzione require_once viene sempre visualizzata, ma si fa riferimento solo alle classi necessarie per eseguire l'esempio.In the following examples, the require_once statement is always shown, but only the classes necessary for the example to execute are referenced.

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

Per creare un'istanza di un client del bus di servizio, è necessario innanzitutto disporre di una stringa di connessione valida nel seguente formato:To instantiate a Service Bus client you must first have a valid connection string in this format:

Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]

Dove Endpoint è in genere nel formato https://[yourNamespace].servicebus.windows.net.Where Endpoint is typically of the format https://[yourNamespace].servicebus.windows.net.

Per creare un client del servizio Azure, è necessario usare la classe ServicesBuilder.To create any Azure service client you must use the ServicesBuilder class. È possibile:You can:

  • Passare la stringa di connessione direttamente.Pass the connection string directly to it.
  • utilizzare CloudConfigurationManager (CCM) per cercare la stringa di connessione in più origini esterne:Use the CloudConfigurationManager (CCM) to check multiple external sources for the connection string:
    • Per impostazione predefinita viene fornito con il supporto per un'origine esterna, ovvero le variabili ambientali.By default it comes with support for one external source - environmental variables.
    • È possibile aggiungere nuove origini estendendo la classe ConnectionStringSource.You can add new sources by extending the ConnectionStringSource class.

Per gli esempi illustrati in questo articolo, la stringa di connessione viene passata direttamente.For the examples outlined here, the connection string is passed directly.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;

$connectionString = "Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]";

$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

Creare un argomentoCreate a topic

È possibile eseguire operazioni di gestione per gli argomenti del bus di servizio usando la classe ServiceBusRestProxy.You can perform management operations for Service Bus topics via the ServiceBusRestProxy class. Un oggetto ServiceBusRestProxy è costruito tramite il metodo factory ServicesBuilder::createServiceBusService con una stringa di connessione appropriata che incapsula le autorizzazioni di token per gestirlo.A ServiceBusRestProxy object is constructed via the ServicesBuilder::createServiceBusService factory method with an appropriate connection string that encapsulates the token permissions to manage it.

L'esempio seguente mostra come creare un'istanza di ServiceBusRestProxy e chiamare il metodo ServiceBusRestProxy->createTopic per creare un argomento denominato mytopic in uno spazio dei nomi MySBNamespace:The following example shows how to instantiate a ServiceBusRestProxy and call ServiceBusRestProxy->createTopic to create a topic named mytopic within a MySBNamespace namespace:

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\TopicInfo;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {        
    // Create topic.
    $topicInfo = new TopicInfo("mytopic");
    $serviceBusRestProxy->createTopic($topicInfo);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Nota

È possibile usare il metodo listTopics negli oggetti ServiceBusRestProxy per verificare se in uno spazio dei nomi del servizio esiste già un argomento con il nome specificato.You can use the listTopics method on ServiceBusRestProxy objects to check if a topic with a specified name already exists within a service namespace.

Creare una sottoscrizioneCreate a subscription

È possibile creare le sottoscrizioni di un argomento con il metodo ServiceBusRestProxy->createSubscription.Topic subscriptions are also created with the ServiceBusRestProxy->createSubscription method. Le sottoscrizioni sono denominate e possono includere un filtro facoltativo che limita l'insieme dei messaggi passati alla coda virtuale della sottoscrizione.Subscriptions are named and can have an optional filter that restricts the set of messages passed to the subscription's virtual queue.

Creare una sottoscrizione con il filtro (MatchAll) predefinitoCreate a subscription with the default (MatchAll) filter

Il filtro MatchAll è il filtro predefinito e viene usato se non vengono specificati altri filtri durante la creazione di una nuova sottoscrizione.The MatchAll filter is the default filter that is used if no filter is specified when a new subscription is created. Quando si usa il filtro MatchAll, tutti i messaggi pubblicati nell'argomento vengono inseriti nella coda virtuale della sottoscrizione.When the MatchAll filter is used, all messages published to the topic are placed in the subscription's virtual queue. Nell'esempio seguente viene creata una sottoscrizione denominata 'mysubscription' e viene usato il filtro predefinito MatchAll.The following example creates a subscription named 'mysubscription' and uses the default MatchAll filter.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\SubscriptionInfo;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Create subscription.
    $subscriptionInfo = new SubscriptionInfo("mysubscription");
    $serviceBusRestProxy->createSubscription("mytopic", $subscriptionInfo);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Creare sottoscrizioni con i filtriCreate subscriptions with filters

È anche possibile configurare filtri che consentono di specificare quali messaggi inviati a un argomento devono essere presenti in una specifica sottoscrizione dell'argomento.You can also set up filters that enable you to specify which messages sent to a topic should appear within a specific topic subscription. Il tipo di filtro più flessibile tra quelli supportati dalle sottoscrizioni è SqlFilter, che implementa un subset di SQL92.The most flexible type of filter supported by subscriptions is the SqlFilter, which implements a subset of SQL92. I filtri SQL agiscono sulle proprietà dei messaggi pubblicati nell'argomento.SQL filters operate on the properties of the messages that are published to the topic. Per altre informazioni su SqlFilters, vedere la sezione relativa alla proprietà SqlFilter.SqlExpression.For more information about SqlFilters, see SqlFilter.SqlExpression Property.

Nota

Ogni regola in una sottoscrizione elabora i messaggi in arrivo indipendentemente, aggiungendo i messaggi risultanti alla sottoscrizione stessa.Each rule on a subscription processes incoming messages independently, adding their result messages to the subscription. Ogni nuova sottoscrizione presenta anche un oggetto Rule predefinito con un filtro che aggiunge tutti i messaggi dall'argomento alla sottoscrizione.In addition, each new subscription has a default Rule object with a filter that adds all messages from the topic to the subscription. Per ricevere solo messaggi corrispondenti al filtro in uso, è necessario rimuovere la regola predefinita.To receive only messages matching your filter, you must remove the default rule. È possibile rimuovere la regola predefinita usando il metodo ServiceBusRestProxy->deleteRule.You can remove the default rule by using the ServiceBusRestProxy->deleteRule method.

L'esempio seguente crea una sottoscrizione denominata HighMessages con un filtro SqlFilter che seleziona solo i messaggi in cui il valore della proprietà MessageNumber personalizzata è maggiore di 3.The following example creates a subscription named HighMessages with a SqlFilter that only selects messages that have a custom MessageNumber property greater than 3. Per informazioni su come aggiungere proprietà personalizzate ai messaggi, vedere Inviare messaggi a un argomento.See Send messages to a topic for information about adding custom properties to messages.

$subscriptionInfo = new SubscriptionInfo("HighMessages");
$serviceBusRestProxy->createSubscription("mytopic", $subscriptionInfo);

$serviceBusRestProxy->deleteRule("mytopic", "HighMessages", '$Default');

$ruleInfo = new RuleInfo("HighMessagesRule");
$ruleInfo->withSqlFilter("MessageNumber > 3");
$ruleResult = $serviceBusRestProxy->createRule("mytopic", "HighMessages", $ruleInfo);

Si noti che questo codice richiede l'uso di uno spazio dei nomi aggiuntivo: WindowsAzure\ServiceBus\Models\SubscriptionInfo.Note that this code requires the use of an additional namespace: WindowsAzure\ServiceBus\Models\SubscriptionInfo.

Analogamente, l'esempio seguente crea una sottoscrizione denominata LowMessages con un filtro SqlFilter che seleziona solo i messaggi in cui il valore della proprietà MessageNumber è minore o uguale a 3.Similarly, the following example creates a subscription named LowMessages with a SqlFilter that only selects messages that have a MessageNumber property less than or equal to 3.

$subscriptionInfo = new SubscriptionInfo("LowMessages");
$serviceBusRestProxy->createSubscription("mytopic", $subscriptionInfo);

$serviceBusRestProxy->deleteRule("mytopic", "LowMessages", '$Default');

$ruleInfo = new RuleInfo("LowMessagesRule");
$ruleInfo->withSqlFilter("MessageNumber <= 3");
$ruleResult = $serviceBusRestProxy->createRule("mytopic", "LowMessages", $ruleInfo);

A questo punto, quando viene inviato un messaggio all'argomento mytopic, viene sempre recapitato ai ricevitori con sottoscrizione mysubscription e recapitato selettivamente ai ricevitori con sottoscrizioni HighMessages e LowMessages, a seconda del contenuto del messaggio.Now, when a message is sent to the mytopic topic, it is always delivered to receivers subscribed to the mysubscription subscription, and selectively delivered to receivers subscribed to the HighMessages and LowMessages subscriptions (depending upon the message content).

Inviare messaggi a un argomentoSend messages to a topic

Per inviare un messaggio a un argomento del bus di servizio, l'applicazione chiama il metodo ServiceBusRestProxy->sendTopicMessage.To send a message to a Service Bus topic, your application calls the ServiceBusRestProxy->sendTopicMessage method. Il codice seguente illustra come inviare un messaggio all'argomento mytopic creato prima nello spazio dei nomi del servizio MySBNamespace.The following code shows how to send a message to the mytopic topic previously created within the MySBNamespace service namespace.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\BrokeredMessage;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Create message.
    $message = new BrokeredMessage();
    $message->setBody("my message");

    // Send message.
    $serviceBusRestProxy->sendTopicMessage("mytopic", $message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

I messaggi inviati ad argomenti del bus di servizio sono istanze della classe BrokeredMessage.Messages sent to Service Bus topics are instances of the BrokeredMessage class. Gli oggetti BrokeredMessage includono un set di proprietà e metodi standard, nonché proprietà usate per contenere proprietà personalizzate specifiche dell'applicazione.BrokeredMessage objects have a set of standard properties and methods, as well as properties that can be used to hold custom application-specific properties. L'esempio seguente illustra come inviare 5 messaggi di prova all'argomento mytopic creato in precedenza.The following example shows how to send 5 test messages to the mytopic topic previously created. Il metodo setProperty viene usato per aggiungere una proprietà personalizzata (MessageNumber) a ogni messaggio.The setProperty method is used to add a custom property (MessageNumber) to each message. Si noti che il valore della proprietà MessageNumber varia per ogni messaggio, consentendo di determinare quali sottoscrizioni lo riceveranno, come descritto nella sezione Creare una sottoscrizione:Note that the MessageNumber property value varies on each message (you can use this value to determine which subscriptions receive it, as shown in the Create a subscription section):

for($i = 0; $i < 5; $i++){
    // Create message.
    $message = new BrokeredMessage();
    $message->setBody("my message ".$i);

    // Set custom property.
    $message->setProperty("MessageNumber", $i);

    // Send message.
    $serviceBusRestProxy->sendTopicMessage("mytopic", $message);
}

Gli argomenti del bus di servizio supportano messaggi di dimensioni massime pari a 256 KB nel livello Standard e pari a 1 MB nel livello Premium.Service Bus topics 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 un argomento, mentre è prevista una limitazione alla dimensione totale dei messaggi di un argomento.There is no limit on the number of messages held in a topic but there is a cap on the total size of the messages held by a topic. Il limite massimo delle dimensioni di un argomento è 5 GB.This upper limit on topic size is 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 sottoscrizioneReceive messages from a subscription

Il modo ideale per ricevere i messaggi da una sottoscrizione prevede l'uso di un metodo ServiceBusRestProxy->receiveSubscriptionMessage.The best way to receive messages from a subscription is to use a ServiceBusRestProxy->receiveSubscriptionMessage method. Le modalità di ricezione dei messaggi sono due: ReceiveAndDelete e PeekLock.Messages can be received in two different modes: ReceiveAndDelete and PeekLock. PeekLock è la modalità predefinita.PeekLock is the default.

Quando si usa la modalità ReceiveAndDelete, l'operazione di ricezione viene eseguita in un'unica fase. Quando infatti il bus di servizio riceve una richiesta di lettura relativa a un messaggio in una sottoscrizione, lo contrassegna come usato e lo restituisce all'applicazione.When using the ReceiveAndDelete mode, receive is a single-shot operation; that is, when Service Bus receives a read request for a message in a subscription, it marks the message as being consumed and returns it to the application. La modalità ReceiveAndDelete * costituisce il modello più semplice ed è adatta per scenari in cui un'applicazione può tollerare la mancata elaborazione di un messaggio in caso di errore.ReceiveAndDelete * mode 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.

Nella modalità PeekLock predefinita l'operazione di ricezione viene suddivisa in due fasi, in modo da consentire il supporto di applicazioni che non possono tollerare messaggi mancanti.In the default PeekLock mode, receiving a message 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 completa la seconda fase del processo di ricezione passando il messaggio ricevuto a ServiceBusRestProxy->deleteMessage.After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by passing the received message to ServiceBusRestProxy->deleteMessage. Quando il bus di servizio vede la chiamata deleteMessage, contrassegna il messaggio come utilizzato e lo rimuove dalla coda.When Service Bus sees the deleteMessage call, it marks the message as being consumed and remove it from the queue.

L'esempio seguente illustra come ricevere ed elaborare un messaggio usando la modalità PeekLock (predefinita).The following example shows how to receive and process a message using PeekLock mode (the default mode).

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\ReceiveMessageOptions;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Set receive mode to PeekLock (default is ReceiveAndDelete)
    $options = new ReceiveMessageOptions();
    $options->setPeekLock();

    // Get message.
    $message = $serviceBusRestProxy->receiveSubscriptionMessage("mytopic", "mysubscription", $options);

    echo "Body: ".$message->getBody()."<br />";
    echo "MessageID: ".$message->getMessageId()."<br />";

    /*---------------------------
        Process message here.
    ----------------------------*/

    // Delete message. Not necessary if peek lock is not set.
    echo "Deleting message...<br />";
    $serviceBusRestProxy->deleteMessage($message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Procedura: 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 è in grado di elaborare il messaggio per un qualsiasi motivo, può chiamare il metodo unlockMessage anziché deleteMessage sul messaggio ricevuto.If a receiver application is unable to process the message for some reason, then it can call the unlockMessage method on the received message (instead of the deleteMessage method). In questo modo, 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 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 è anche 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 make it available to be received again.

In caso di arresto anomalo dell'applicazione dopo l'elaborazione del messaggio, ma prima dell'invio della richiesta deleteMessage, il messaggio viene nuovamente recapitato all'applicazione al riavvio del sistema.In the event that the application crashes after processing the message but before the deleteMessage request is issued, then the message is 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 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 alle applicazioni per gestire il secondo recapito del messaggio.If the scenario cannot tolerate duplicate processing, then application developers should add additional logic to applications to handle duplicate message delivery. A tale scopo viene spesso usato il metodo getMessageId del messaggio, che rimane costante in tutti i tentativi di recapito.This is often achieved using the getMessageId method of the message, which remains constant across delivery attempts.

Eliminare argomenti e sottoscrizioniDelete topics and subscriptions

Per eliminare un argomento o una sottoscrizione, usare rispettivamente il metodo ServiceBusRestProxy->deleteTopic o ServiceBusRestProxy->deleteSubscripton.To delete a topic or a subscription, use the ServiceBusRestProxy->deleteTopic or the ServiceBusRestProxy->deleteSubscripton methods, respectively. Si noti che, se si elimina un argomento, vengono eliminate anche tutte le sottoscrizioni registrate con l'argomento.Note that deleting a topic also deletes any subscriptions that are registered with the topic.

L'esempio seguente illustra come eliminare un argomento denominato mytopic e le relative sottoscrizioni registrate.The following example shows how to delete a topic named mytopic and its registered subscriptions.

require_once 'vendor/autoload.php';

use WindowsAzure\ServiceBus\ServiceBusService;
use WindowsAzure\ServiceBus\ServiceBusSettings;
use WindowsAzure\Common\ServiceException;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {        
    // Delete topic.
    $serviceBusRestProxy->deleteTopic("mytopic");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

È possibile eliminare una sottoscrizione in modo indipendente usando il metodo deleteSubscription:By using the deleteSubscription method, you can delete a subscription independently:

$serviceBusRestProxy->deleteSubscription("mytopic", "mysubscription");

Passaggi successiviNext steps

A questo punto, dopo aver appreso le nozioni di base delle code del bus di servizio, vedere Code, argomenti e sottoscrizioni per altre informazioni.Now that you've learned the basics of Service Bus queues, see Queues, topics, and subscriptions for more information.