Så här använder du Service Bus och prenumerationer med PHP

Den här artikeln visar hur du använder Service Bus ämnen och prenumerationer. Exemplen är skrivna i PHP och använder Azure SDK för PHP. Scenarierna som beskrivs är:

• Skapa ämnen och prenumerationer
• Skapa prenumerationsfilter
• Skicka meddelanden till ett ämne
• Ta emot meddelanden från en prenumeration
• Ta bort ämnen och prenumerationer

Förutsättningar

1. En Azure-prenumeration. För att slutföra stegen i den här artikeln behöver du ett Azure-konto. Du kan aktivera dina Visual Studio eller MSDN-prenumerantförmåner eller registrera dig för ett kostnadsfritt konto.

2. Följ stegen i Snabbstart: Använd Azure Portal för att skapa ett Service Bus-ämne och prenumerationer på ämnet för att skapa ett Service Bus-namnområde och hämta anslutningssträngen.

   Anteckning

   Du skapar ett ämne och en prenumeration på ämnet med hjälp av PHP i den här artikeln.

Skapa ett PHP-program

Det enda kravet för att skapa ett PHP-program som har åtkomst till Azure Blob-tjänsten är att referera till klasser i Azure SDK för PHP inifrån din kod. Du kan använda alla utvecklingsverktyg för att skapa ditt program eller Anteckningar.

Den här artikeln beskriver hur du använder tjänstfunktioner som kan anropas i ett PHP-program lokalt eller i kod som körs i en Azure-webbroll, arbetsroll eller webbplats.

Hämta Azure-klientbiblioteken

Installera via Composer

1. Skapa en fil med namnet composer.json i roten av projektet och lägg till följande kod i den:

   {
     "require": {
       "microsoft/windowsazure": "*"
     }
   }
   

2. Ladda ned [composer.phar][composer-phar] i projektroten.

3. Öppna en kommandotolk och kör följande kommando i projektroten

   php composer.phar install
   

Konfigurera ditt program att använda Service Bus

Så här använder du Service Bus-API:er:

1. Referera till autoloader-filen med hjälp require_once -instruktionen.
2. Referera till alla klasser som du kan använda.

I följande exempel visas hur du inkluderar autoloader-filen och refererar till klassen ServiceBusService.

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

I följande exempel visas alltid require_once -instruktionen, men endast de klasser som krävs för att köra exemplet refereras.

Konfigurera en Service Bus anslutning

Om du vill instansiera Service Bus klient måste du först ha en giltig anslutningssträng i det här formatet:

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

Där Endpoint vanligtvis har formatet https://[yourNamespace].servicebus.windows.net .

Om du vill skapa en Azure-tjänstklient måste du använda ServicesBuilder klassen . Du kan:

• Skicka anslutningssträngen direkt till den.
• Använd CloudConfigurationManager (CCM) för att kontrollera anslutningssträngen för flera externa källor:
  • Som standard har den stöd för en extern källa – miljövariabler.
  • Du kan lägga till nya källor genom att utöka ConnectionStringSource-klassen.

I exemplen som beskrivs här anges anslutningssträngen direkt.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;

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

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

Skapa ett ämne

Du kan utföra hanteringsåtgärder för Service Bus ämnen via ServiceBusRestProxy klassen . Ett ServiceBusRestProxy -objekt skapas via ServicesBuilder::createServiceBusService fabriksmetoden med en lämplig anslutningssträng som kapslar in tokenbehörigheterna för att hantera det.

I följande exempel visas hur du instansierar ett ServiceBusRestProxy - och ServiceBusRestProxy->createTopic -anrop för att skapa ett ämne med namnet inom ett mytopic MySBNamespace namnområde:

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 />";
}

Skapa en prenumeration

Ämnesprenumerationer skapas också med ServiceBusRestProxy->createSubscription metoden . Prenumerationer är namngivna och kan ha ett valfritt filter som begränsar den uppsättning av meddelanden som skickas till prenumerationens virtuella kö.

Skapa en prenumeration med standardfiltret (MatchAll)

Om inget filter anges när en ny prenumeration skapas används MatchAll-filtret (standard). När MatchAll-filtret används placeras alla meddelanden som publiceras till ämnet i prenumerationens virtuella kö. I följande exempel skapas en prenumeration med namnet mysubscription och standardfiltret MatchAll används.

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 />";
}

Skapa prenumerationer med filter

Du kan även ställa in filter som gör att du kan ange vilka meddelanden som skickas till ett ämne som ska visas inom en viss ämnesprenumeration. Den mest flexibla typen av filter som stöds av prenumerationer är SqlFilter, som implementerar en delmängd av SQL92. SQL-filter tillämpas på egenskaperna i de meddelanden som publiceras till ämnet. Mer information om SqlFilters finns i SqlFilter.SqlExpression-egenskapen.

I följande exempel skapas en prenumeration med namnet med ett SqlFilter som endast HighMessages väljer meddelanden som har en anpassad egenskap som är större än MessageNumber 3. Se Skicka meddelanden till ett ämne för information om hur du lägger till anpassade egenskaper i meddelanden.

$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);

Den här koden kräver användning av ytterligare ett namnområde: WindowsAzure\ServiceBus\Models\SubscriptionInfo .

På samma sätt skapar följande exempel en prenumeration med namnet med en som bara väljer meddelanden som har en egenskap som är mindre LowMessages än eller lika med SqlFilter MessageNumber 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);

När ett meddelande nu skickas till ämnet levereras det alltid till mottagare som prenumererar på prenumerationen och levereras selektivt till mottagare som prenumererar på prenumerationerna och (beroende på mytopic mysubscription HighMessages LowMessages meddelandeinnehållet).

Skicka meddelanden till ett ämne

Om du vill skicka ett meddelande Service Bus ett ämne anropar programmet ServiceBusRestProxy->sendTopicMessage metoden . Följande kod visar hur du skickar ett meddelande till ämnet mytopic som tidigare skapats i MySBNamespace tjänstens namnområde.

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 />";
}

Meddelanden som skickas till Service Bus-ämnen är instanser av klassen BrokeredMessage. BrokeredMessage-objekt har en uppsättning standardegenskaper och standardmetoder, samt egenskaper som kan användas för att innehålla anpassade programspecifika egenskaper. I följande exempel visas hur du skickar fem testmeddelanden till ämnet mytopic som du skapade tidigare. Metoden setProperty används för att lägga till en anpassad egenskap ( ) i varje MessageNumber meddelande. Egenskapsvärdet varierar för varje meddelande (du kan använda det här värdet för att avgöra vilka prenumerationer som får det, som du MessageNumber ser i avsnittet Skapa en prenumeration):

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);
}

Service Bus har stöd för en maximal meddelandestorlek på 256 kB på standardnivån och 100 MB på Premium nivån. Rubriken, som inkluderar standardprogramegenskaperna och de anpassade programegenskaperna, kan ha en maximal storlek på 64 kB. Det finns ingen gräns för antalet meddelanden som kan finnas i ett ämne men det finns ett tak för den totala storleken för de meddelanden som ligger i ett ämne. Den här övre gränsen för ämnesstorlek är 5 GB. Mer information om kvoter finns i Service Bus kvoter.

Ta emot meddelanden från en prenumeration

Det bästa sättet att ta emot meddelanden från en prenumeration är att använda en ServiceBusRestProxy->receiveSubscriptionMessage -metod. Meddelanden kan tas emot i två olika lägen: ReceiveAndDelete och PeekLock. PeekLock är standard.

När du använder läget ReceiveAndDelete är inleveransen en engångsåtgärd, det vill säga, när Service Bus tar emot en läsbegäran för ett meddelande i en prenumeration så markerar den meddelandet som förbrukat och skickar tillbaka det till programmet. Läget ReceiveAndDelete * är den enklaste modellen och fungerar bäst för scenarier där ett program kan tolerera att inte bearbeta ett meddelande när ett fel inträffar. För att förstå detta kan du föreställa dig ett scenario där konsumenten utfärdar en receive-begäran och sedan kraschar innan den kan bearbeta denna begäran. Eftersom Service Bus har markerat meddelandet som förbrukat har programmet, när det startas om och börjar använda meddelanden igen, missat meddelandet som förbrukades före kraschen.

I standardläget PeekLock blir mottagandet av ett meddelande en åtgärd i två steg, vilket gör det möjligt att stödja program som inte tolererar att meddelanden saknas. När Service Bus tar emot en begäran letar det upp nästa meddelande som ska förbrukas, låser det för att förhindra andra användare tar emot det och skickar sedan tillbaka det till programmet. När programmet har slutfört bearbetningen av meddelandet (eller lagrar det på ett tillförlitligt sätt för framtida bearbetning) slutför det andra steget i mottagningsprocessen genom att skicka det mottagna meddelandet till ServiceBusRestProxy->deleteMessage . När Service Bus ser deleteMessage anropet markerar det meddelandet som förbrukat och tar bort det från kön.

I följande exempel visas hur du tar emot och bearbetar ett meddelande med PeekLock-läge (standardläget).

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 />";
}

Gör så här: Hantera programkrasch och oläsliga meddelanden

Service Bus innehåller funktioner som hjälper dig att återställa fel i programmet eller lösa problem med bearbetning av meddelanden på ett snyggt sätt. Om ett mottagarprogram av någon anledning inte kan bearbeta meddelandet kan det anropa metoden för det mottagna unlockMessage meddelandet (i stället för deleteMessage metoden ). Det gör Service Bus låser upp meddelandet i kön och gör det tillgängligt att tas emot igen, antingen av samma användningsprogram eller av ett annat användningsprogram.

Det finns också en tidsgräns som är associerad med ett meddelande som är låst i kön, och om programmet inte kan bearbeta meddelandet innan tidsgränsen för låsning upphör att gälla (till exempel om programmet kraschar) låser Service Bus upp meddelandet automatiskt och gör det tillgängligt för att kunna tas emot igen.

Om programmet kraschar efter att meddelandet har bearbetats men innan begäran har utfärdats, skickas meddelandet vidare till programmet när deleteMessage det startas om. Den här typen av bearbetning kallas ofta för bearbetning minst en gång. Det innebär att varje meddelande bearbetas minst en gång, men i vissa situationer kan samma meddelande levereras igen. Om scenariot inte tolererar duplicerad bearbetning bör programutvecklare lägga till ytterligare logik i program för att hantera duplicerad meddelandeleverans. Det görs ofta med hjälp getMessageId av metoden för meddelandet, som är konstant under leveransförsök.

Ta bort ämnen och prenumerationer

Om du vill ta bort ett ämne eller en ServiceBusRestProxy->deleteTopic prenumeration använder du metoderna eller ServiceBusRestProxy->deleteSubscripton . Om du tar bort ett ämne så tar du även bort alla prenumerationer som är registrerade på det ämnet.

I följande exempel visas hur du tar bort ett ämne med mytopic namnet och dess registrerade prenumerationer.

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 />";
}

Med hjälp av deleteSubscription metoden kan du ta bort en prenumeration oberoende av varandra:

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

Nästa steg

Mer information finns i Köer, ämnen och prenumerationer.