Queue Storage gebruiken vanuit PHP

Deze handleiding laat zien hoe u algemene scenario's uitvoert met behulp van de Azure Queue Storage-service. De voorbeelden worden geschreven via klassen uit de Azure Storage-clientbibliotheek voor PHP. De behandelde scenario's omvatten het invoegen, bekijken, ophalen en verwijderen van wachtrijberichten, evenals het maken en verwijderen van wachtrijen.

Wat is Queue Storage?

Azure Queue Storage is een service voor de opslag van grote aantallen berichten die via HTTP of HTTPS overal vandaan kunnen worden opgevraagd met geverifieerde aanroepen. Een enkel wachtrijbericht mag maximaal 64 KB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot de totale capaciteitslimiet van een opslagaccount. Queue Storage wordt vaak gebruikt om een achterstand van werk te maken om asynchroon te verwerken.

Concepten van Queue-service

De Azure Queue-service bevat de volgende onderdelen:

• Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie Overzicht van opslagaccount voor meer informatie over opslagaccounts.

• Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.

• Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven staan. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

• URL-indeling: Wachtrijen kunnen worden adresseerbaar met de volgende URL-indeling: http://<storage account>.queue.core.windows.net/<queue>

  Met de volgende URL wordt een wachtrij in het diagram opgevraagd:

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

Een Azure-opslagaccount maken

De eenvoudigste manier om uw eerste Azure-opslagaccount te maken, is met behulp van de Azure Portal. Zie Een opslagaccount maken voor meer informatie.

U kunt ook een Azure-opslagaccount maken met behulp van Azure PowerShell, Azure CLI of de Azure Storage Resource Provider voor .NET.

Als u op dit moment liever geen opslagaccount in Azure maakt, kunt u de Azurite-opslagemulator ook gebruiken om uw code in een lokale omgeving uit te voeren en te testen. Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) voor meer informatie.

Een PHP-toepassing maken

De enige vereiste voor het maken van een PHP-toepassing die toegang heeft tot Azure Queue Storage, is het verwijzen naar klassen in de Azure Storage-clientbibliotheek voor PHP vanuit uw code. U kunt elk ontwikkelprogramma gebruiken om uw toepassing te maken, waaronder Kladblok.

In deze handleiding gebruikt u de queue storage-servicefuncties die lokaal kunnen worden aangeroepen in een PHP-toepassing of in code die wordt uitgevoerd in een webtoepassing in Azure.

De Azure-clientbibliotheken ophalen

Installeren via composer

1. Maak een bestand met de naam composer.json in de hoofdmap van uw project en voeg er de volgende code aan toe:

   {
     "require": {
       "microsoft/azure-storage-queue": "*"
     }
   }
   

2. Download composer.phar in de hoofdmap van uw project.

3. Open een opdrachtprompt en voer de volgende opdracht uit in de hoofdmap van het project:

   php composer.phar install
   

U kunt ook naar de Azure Storage PHP-clientbibliotheek op GitHub gaan om de broncode te klonen.

Uw toepassing configureren voor toegang tot Queue Storage

Als u de API's voor Azure Queue Storage wilt gebruiken, moet u het volgende doen:

1. Verwijs naar het autoloader-bestand met behulp van de require_once -instructie.
2. Verwijst naar klassen die u mogelijk gebruikt.

Het volgende voorbeeld laat zien hoe u het autoloaderbestand opneemt en een verwijzing maakt naar de klasse QueueRestProxy.

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

In de volgende voorbeelden wordt de require_once instructie altijd weergegeven, maar wordt alleen verwezen naar de klassen die nodig zijn om het voorbeeld uit te voeren.

Een Azure Storage-verbinding instellen

Als u een Azure Queue Storage-client wilt instantiëren, moet u eerst een geldige connection string hebben. De indeling voor het connection string Queue Storage is als volgt.

Voor toegang tot een liveservice:

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

Voor toegang tot de emulatoropslag:

UseDevelopmentStorage=true

Als u een Azure Queue Storage-client wilt maken, moet u de QueueRestProxy klasse gebruiken. U kunt een van de volgende technieken gebruiken:

• De verbindingsreeks rechtstreeks doorgeven aan deze klasse.
• Gebruik omgevingsvariabelen in uw web-app om de connection string op te slaan. Zie het document Configuratie-instellingen voor Azure-web-apps voor het configureren van verbindingsreeksen.

In de voorbeelden die hier worden beschreven, wordt de verbindingsreeks rechtstreeks doorgegeven.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Een wachtrij maken

QueueRestProxy Met een -object kunt u een wachtrij maken met behulp van de CreateQueue -methode. Wanneer u een wachtrij maakt, kunt u opties instellen voor de wachtrij, maar dit is niet vereist. In dit voorbeeld ziet u hoe u metagegevens instelt voor een wachtrij.

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

Een bericht toevoegen aan een wachtrij

Als u een bericht wilt toevoegen aan een wachtrij, gebruikt u QueueRestProxy->createMessage. De methode gebruikt de naam van de wachtrij, de berichttekst en de berichtopties (optioneel).

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

Bekijken van het volgende bericht

U kunt een of meer berichten aan de voorzijde van een wachtrij bekijken zonder ze uit de wachtrij te verwijderen door aan te roepen QueueRestProxy->peekMessages. Standaard retourneert de peekMessage methode één bericht, maar u kunt deze waarde wijzigen met behulp van de PeekMessagesOptions->setNumberOfMessages methode .

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

Het volgende bericht uit de wachtrij verwijderen

Met uw code wordt in twee stappen een bericht uit een wachtrij verwijderd. Eerst roept QueueRestProxy->listMessagesu aan, waardoor het bericht onzichtbaar wordt voor alle andere code die uit de wachtrij wordt gelezen. Standaard blijft het bericht onzichtbaar gedurende 30 seconden. (Als het bericht in deze periode niet wordt verwijderd, wordt het weer zichtbaar in de wachtrij.) Als u het verwijderen van het bericht uit de wachtrij wilt voltooien, moet u aanroepen QueueRestProxy->deleteMessage. Dit proces van het verwijderen van een bericht in twee stappen zorgt ervoor dat wanneer uw code een bericht niet kan verwerken vanwege hardware- of softwarefouten, een ander exemplaar van uw code hetzelfde bericht kan ontvangen en het opnieuw kan proberen. Uw code roept aan deleteMessage zodra het bericht is verwerkt.

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

De inhoud van een bericht in de wachtrij wijzigen

U kunt de inhoud van een bericht in de wachtrij wijzigen door aan te roepen QueueRestProxy->updateMessage. Als het bericht een werktaak vertegenwoordigt, kunt u deze functie gebruiken om de status van de werktaak bij te werken. Met de volgende code wordt het wachtrijbericht bijgewerkt met nieuwe inhoud en wordt de time-out voor zichtbaarheid ingesteld om nog eens 60 seconden te verlengen. Hiermee wordt de werkstatus opgeslagen die aan het bericht is gekoppeld en heeft de client nog een minuut de tijd om verder te werken aan het bericht. U kunt deze techniek gebruiken om werkstromen met meerdere stappen in wachtrijberichten bij te houden, zonder dat u opnieuw hoeft te beginnen als een verwerkingsstap mislukt vanwege hardware- of softwarefouten. Doorgaans houdt u ook het aantal nieuwe pogingen bij en als het bericht meer dan n keer opnieuw is geprobeerd, verwijdert u het. Dit biedt bescherming tegen berichten die een toepassingsfout activeren telkens wanneer ze worden verwerkt.

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

Extra opties voor het verwijderen van berichten

Er zijn twee manieren waarop u het ophalen van berichten uit een wachtrij kunt aanpassen. Ten eerste kunt u berichten batchgewijs (maximaal 32) ophalen. Ten tweede kunt u een langere of kortere zichtbaarheidstime-out instellen, zodat uw code meer of minder tijd heeft om elk bericht volledig te verwerken. In het volgende codevoorbeeld wordt de getMessages methode gebruikt om 16 berichten in één aanroep op te halen. Vervolgens worden elk bericht verwerkt met behulp van een for lus. De time-out voor onzichtbaarheid wordt ingesteld op vijf minuten voor elk bericht.

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

Wachtrijlengte ophalen

U kunt een schatting ophalen van het aantal berichten in de wachtrij. Met de QueueRestProxy->getQueueMetadata methode worden metagegevens over de wachtrij opgehaald. Als u de getApproximateMessageCount methode op het geretourneerde object aanroept, wordt het aantal berichten in een wachtrij weergegeven. Het aantal is alleen bij benadering omdat berichten kunnen worden toegevoegd of verwijderd nadat Queue Storage op uw aanvraag heeft gereageerd.

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;

Een wachtrij verwijderen

Als u een wachtrij en alle berichten erin wilt verwijderen, roept u de QueueRestProxy->deleteQueue methode aan.

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

Volgende stappen

Nu u de basisbeginselen van Azure Queue Storage hebt geleerd, volgt u deze koppelingen voor meer informatie over complexere opslagtaken:

• Ga naar de API-naslaginformatie voor Azure Storage PHP-clientbibliotheek
• Zie het voorbeeld van een geavanceerde wachtrij.

Zie het PHP-ontwikkelaarscentrum voor meer informatie.