Så här använder du Queue Storage från PHP

Artikel
01/11/2018

Tips

Prova Microsoft Azure Lagringsutforskaren

Microsoft Azure Storage Explorer är en kostnadsfri, fristående app från Microsoft som gör det möjligt att arbeta visuellt med Azure Storage-data i Windows, macOS och Linux.

Den här guiden visar hur du utför vanliga scenarier med hjälp av Azure Queue Storage-tjänsten. Exemplen skrivs via klasser från Azure Storage-klientbiblioteket för PHP. De täckta scenarierna omfattar infogning, tittning, hämtar och tar bort kömeddelanden samt att skapa och ta bort köer.

Vad är Queue Storage?

Azure Queue Storage är en tjänst för att lagra stora mängder meddelanden som kan nås från var som helst i världen via autentiserade anrop med HTTP eller HTTPS. Ett enda kömeddelande kan vara upp till 64 KB stort och en kö kan innehålla miljontals meddelanden, upp till den totala kapacitetsgränsen för ett lagringskonto. Kölagring används ofta för att skapa en kvarvarande arbetslogg för att bearbeta asynkront.

Begrepp för kötjänst

Azure Queue-tjänsten innehåller följande komponenter:

Azure Queue-tjänstkomponenter

Lagringskonto: All åtkomst till Azure Storage görs genom ett lagringskonto. Mer information om lagringskonton finns i Översikt över lagringskonto.
Kö: en kö innehåller en uppsättning meddelanden. Alla meddelanden måste vara i en kö. Observera att könamnet måste vara helt i gemener. Mer information om namngivning av köer finns i namngivning av köer och metadata.
Meddelande: ett meddelande i valfritt format, som är upp till 64 KB. Den maximala tid som ett meddelande kan finnas i kön är 7 dagar. För version 2017-07-29 eller senare kan den maximala time-to-live vara ett positivt tal, eller -1 som anger att meddelandet inte upphör att gälla. Om den här parametern utelämnas är standardtiden att leva sju dagar.
URL-format: Köer kan adresseras med följande URL-format: http://<storage account>.queue.core.windows.net/<queue>

Följande URL adresserar en kö i diagrammet:

http://myaccount.queue.core.windows.net/incoming-orders

Skapa ett Azure Storage-konto

Det enklaste sättet att skapa ditt första Azure Storage-konto är att använda Azure Portal. Läs mer i Skapa ett lagringskonto.

Du kan också skapa ett Azure Storage-konto med Azure PowerShell, Azure CLI eller Azure Storage-resursprovidern för .NET.

Om du föredrar att inte skapa ett lagringskonto i Azure just nu kan du också använda Azurite Storage-emulatorn för att köra och testa koden i en lokal miljö. Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling.

Skapa ett PHP-program

Det enda kravet för att skapa ett PHP-program som har åtkomst till Azure Queue Storage är att referera till klasser i Azure Storage-klientbiblioteket för PHP inifrån koden. Du kan använda valfritt utvecklingsverktyg för att skapa programmet, inklusive Anteckningar.

I den här guiden använder du funktioner för Queue Storage-tjänsten som kan anropas i ett PHP-program lokalt eller i kod som körs i ett webbprogram i Azure.

Hämta Azure-klientbiblioteken

Installera via kompositör

Skapa en fil med namnet composer.json i projektets rot och lägg till följande kod i den:
```
{
  "require": {
    "microsoft/azure-storage-queue": "*"
  }
}
```
Ladda ned composer.phar i projektroten.
Öppna en kommandotolk och kör följande kommando i projektroten:
```
php composer.phar install
```

Du kan också gå till Azure Storage PHP-klientbiblioteket på GitHub för att klona källkoden.

Konfigurera ditt program för åtkomst till Queue Storage

Om du vill använda API:erna för Azure Queue Storage måste du:

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

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

require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Konfigurera en Azure Storage-anslutning

Om du vill instansiera en Azure Queue Storage-klient måste du först ha en giltig anslutningssträng. Formatet för kölagringsanslutningssträngen är följande.

För att få åtkomst till en livetjänst:

DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]

För åtkomst till emulatorns lagring:

UseDevelopmentStorage=true

Om du vill skapa en Azure Queue Storage-klient måste du använda QueueRestProxy klassen . Du kan använda någon av följande tekniker:

Skicka anslutningssträngen direkt till den.
Använd miljövariabler i webbappen för att lagra anslutningssträngen. Se dokumentet konfigurationsinställningar för Azure-webbappar för att konfigurera anslutningssträngar.

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

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";
$queueClient = QueueRestProxy::createQueueService($connectionString);

Skapa en kö

Med QueueRestProxy ett objekt kan du skapa en kö med hjälp CreateQueue av metoden . När du skapar en kö kan du ange alternativ i kön, men det krävs inte. Det här exemplet visar hur du anger metadata i en kö.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateQueueOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set queue metadata.
$createQueueOptions = new CreateQueueOptions();
$createQueueOptions->addMetaData("key1", "value1");
$createQueueOptions->addMetaData("key2", "value2");

try    {
    // Create queue.
    $queueClient->createQueue("myqueue", $createQueueOptions);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Anteckning

Du bör inte förlita dig på skiftlägeskänslighet för metadatanycklar. Alla nycklar läss från tjänsten med gemener.

Lägga till ett meddelande i en kö

Om du vill lägga till ett meddelande i en kö använder du QueueRestProxy->createMessage. Metoden tar könamnet, meddelandetexten och meddelandealternativen (som är valfria).

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateMessageOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Create message.
    $queueClient->createMessage("myqueue", "Hello, World");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

En titt på nästa meddelande

Du kan titta på ett eller flera meddelanden längst fram i en kö utan att ta bort dem från kön genom att anropa QueueRestProxy->peekMessages. Som standard peekMessage returnerar metoden ett enda meddelande, men du kan ändra det värdet med hjälp PeekMessagesOptions->setNumberOfMessages av metoden .

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\PeekMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set peek message options.
$message_options = new PeekMessagesOptions();
$message_options->setNumberOfMessages(1); // Default value is 1.

try    {
    $peekMessagesResult = $queueClient->peekMessages("myqueue", $message_options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$messages = $peekMessagesResult->getQueueMessages();

// View messages.
$messageCount = count($messages);
if($messageCount <= 0){
    echo "There are no messages.<br />";
}
else{
    foreach($messages as $message)    {
        echo "Peeked message:<br />";
        echo "Message Id: ".$message->getMessageId()."<br />";
        echo "Date: ".date_format($message->getInsertionDate(), 'Y-m-d')."<br />";
        echo "Message text: ".$message->getMessageText()."<br /><br />";
    }
}

Ta bort nästa meddelande från kön

Koden tar bort ett meddelande från en kö i två steg. Först anropar QueueRestProxy->listMessagesdu , vilket gör meddelandet osynligt för all annan kod som läser från kön. Som standard är det här meddelandet osynligt i 30 sekunder. (Om meddelandet inte tas bort under den här tidsperioden blir det synligt i kön igen.) Om du vill ta bort meddelandet från kön måste du anropa QueueRestProxy->deleteMessage. Den här tvåstegsprocessen för att ta bort ett meddelande säkerställer att när koden inte kan bearbeta ett meddelande på grund av maskinvaru- eller programvarufel kan en annan instans av koden få samma meddelande och försöka igen. Koden anropas deleteMessage direkt efter att meddelandet har bearbetats.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

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

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Delete message.
    $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Ändra innehållet i ett meddelande i kön

Du kan ändra innehållet i ett meddelande på plats i kön genom att anropa QueueRestProxy->updateMessage. Om meddelandet representerar en arbetsuppgift kan du använda den här funktionen för att uppdatera arbetsuppgiftens status. Följande kod uppdaterar kömeddelandet med nytt innehåll och anger att tidsgränsen för synligheten ska förlängas med ytterligare 60 sekunder. Detta sparar det arbetstillstånd som är associerat med meddelandet, och det ger klienten ytterligare en minut att fortsätta arbeta med meddelandet. Du kan använda den här tekniken för att spåra arbetsflöden med flera steg i kömeddelanden, utan att behöva börja om från början om ett bearbetningssteg misslyckas på grund av maskinvaru- eller programvarufel. Normalt räknar du även antalet omförsök och tar bort meddelandet om fler än n försök misslyckas. Detta skyddar mot meddelanden som utlöser ett programfel varje gång de bearbetas.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

// Define new message properties.
$new_message_text = "New message text.";
$new_visibility_timeout = 5; // Measured in seconds.

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Update message.
    $queueClient->updateMessage("myqueue",
                                $messageId,
                                $popReceipt,
                                $new_message_text,
                                $new_visibility_timeout);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Ytterligare alternativ för att ta bort meddelanden

Det finns två sätt att anpassa meddelandehämtningen från en kö. För det första kan du hämta en grupp med meddelanden (upp till 32). För det andra kan du ange en längre eller kortare tidsgräns för synlighet, vilket ger koden mer eller mindre tid att bearbeta varje meddelande fullständigt. I följande kodexempel används getMessages metoden för att hämta 16 meddelanden i ett anrop. Sedan bearbetas varje meddelande med hjälp av en for loop. Koden ställer också in tidsgränsen för osynlighet till fem minuter för varje meddelande.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\ListMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Set list message options.
$message_options = new ListMessagesOptions();
$message_options->setVisibilityTimeoutInSeconds(300);
$message_options->setNumberOfMessages(16);

// Get messages.
try{
    $listMessagesResult = $queueClient->listMessages("myqueue",
                                                     $message_options);
    $messages = $listMessagesResult->getQueueMessages();

    foreach($messages as $message){

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

        // Get message Id and pop receipt.
        $messageId = $message->getMessageId();
        $popReceipt = $message->getPopReceipt();

        // Delete message.
        $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
    }
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Hämta kölängd

Du kan hämta en uppskattning av antalet meddelanden i en kö. Metoden QueueRestProxy->getQueueMetadata hämtar metadata om kön. getApproximateMessageCount Att anropa metoden för det returnerade objektet ger ett antal meddelanden i en kö. Antalet är bara ungefärligt eftersom meddelanden kan läggas till eller tas bort när Queue Storage svarar på din begäran.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Get queue metadata.
    $queue_metadata = $queueClient->getQueueMetadata("myqueue");
    $approx_msg_count = $queue_metadata->getApproximateMessageCount();
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

echo $approx_msg_count;

Ta bort en kö

Om du vill ta bort en kö och alla meddelanden i den anropar du QueueRestProxy->deleteQueue metoden .

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Delete queue.
    $queueClient->deleteQueue("myqueue");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Nästa steg

Nu när du har lärt dig grunderna i Azure Queue Storage följer du dessa länkar för att lära dig mer om mer komplexa lagringsuppgifter:

Gå till API-referensen för Azure Storage PHP-klientbiblioteket
Se exemplet med avancerad kö.

Mer information finns i PHP Developer Center.