Jak používat Queue Storage z PHP

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Tip

Vyzkoušení Microsoft Azure Storage Exploreru

Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.

V této příručce se dozvíte, jak provádět běžné scénáře pomocí služby Azure Queue Storage. Ukázky se píší prostřednictvím tříd z klientské knihovny Azure Storage pro PHP. Popsané scénáře zahrnují vkládání, náhledy, získávání a odstraňování zpráv ve frontě a také vytváření a odstraňování front.

Co je Queue Storage?

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Zpráva s jednou frontou může mít velikost až 64 kB a jedna fronta můžete obsahovat miliony zpráv, až do dosažení celkové kapacity účtu úložiště. Queue Storage se často používá k vytvoření backlogu práce, která se má zpracovat asynchronně.

Koncepty služby Fronta

Služba Azure Queue obsahuje následující komponenty:

• Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště. Další informace o účtech úložiště najdete v tématu Přehled účtu úložiště.

• Fronta: Fronta obsahuje sadu zpráv. Všechny zprávy musí být ve frontě. Upozorňujeme, že název fronty musí být psaný malými písmeny. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.

• Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální hodnota time-to-live libovolné kladné číslo nebo -1 označující, že platnost zprávy nevyprší. Pokud je tento parametr vynechán, výchozí hodnota time-to-live je sedm dní.

• Formát adresy URL: Fronty lze adresovat pomocí následujícího formátu adresy URL: http://<storage account>.queue.core.windows.net/<queue>

  Následující adresa URL odkazuje na frontu v diagramu:

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

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je použít Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.

Pokud nechcete v tuto chvíli vytvořit účet úložiště v Azure, můžete také použít emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu Použití emulátoru Azurite pro místní vývoj služby Azure Storage.

Vytvoření aplikace PHP

Jediným požadavkem pro vytvoření aplikace PHP, která přistupuje ke službě Azure Queue Storage, je odkazování na třídy v klientské knihovně Azure Storage pro PHP z vašeho kódu. K vytvoření aplikace můžete použít jakékoli vývojové nástroje, včetně Poznámkového bloku.

V této příručce použijete funkce služby Queue Storage, které je možné volat místně v rámci aplikace PHP nebo v kódu spuštěném v rámci webové aplikace v Azure.

Získání klientských knihoven Azure

Instalace přes composer

1. V kořenovém adresáři projektu vytvořte soubor s názvem composer.json a přidejte do něj následující kód:

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

2. Stáhněte si composer.phar v kořenovém adresáři projektu.

3. Otevřete příkazový řádek a v kořenovém adresáři projektu spusťte následující příkaz:

   php composer.phar install
   

Případně přejděte do klientské knihovny PHP služby Azure Storage na GitHubu a naklonujte zdrojový kód.

Konfigurace aplikace pro přístup ke službě Queue Storage

Abyste mohli používat rozhraní API pro Azure Queue Storage, musíte:

1. Odkaz na soubor automatického require_once zavaděče použijte příkaz .
2. Odkaz na všechny třídy, které můžete použít.

Následující příklad ukazuje, jak zahrnout soubor automatického zavaděče a odkazovat na QueueRestProxy třídu.

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

V následujících příkladech require_once se příkaz zobrazuje vždy, ale odkazují se pouze na třídy potřebné ke spuštění příkladu.

Nastavení připojení ke službě Azure Storage

Pokud chcete vytvořit instanci klienta služby Azure Queue Storage, musíte mít nejprve platný připojovací řetězec. Připojovací řetězec Queue Storage má následující formát.

Pro přístup k živé službě:

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

Přístup k úložišti emulátoru:

UseDevelopmentStorage=true

Pokud chcete vytvořit klienta Azure Queue Storage, musíte použít QueueRestProxy třídu . Můžete použít některou z následujících technik:

• Předejte do něj přímo připojovací řetězec.
• K uložení připojovacího řetězce použijte proměnné prostředí ve webové aplikaci. Informace o konfiguraci připojovacích řetězců najdete v dokumentu o nastavení konfigurace webové aplikace Azure .

Ve zde uvedených příkladech se připojovací řetězec předává přímo.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Vytvoření fronty

Objekt QueueRestProxy umožňuje vytvořit frontu pomocí CreateQueue metody . Při vytváření fronty můžete ve frontě nastavit možnosti, ale není to nutné. Tento příklad ukazuje, jak nastavit metadata ve frontě.

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

Poznámka

U klíčů metadat byste neměli spoléhat na rozlišování velkých a malých písmen. Všechny klíče se ze služby čtou malými písmeny.

Přidání zprávy do fronty

Pokud chcete přidat zprávu do fronty, použijte QueueRestProxy->createMessage. Metoda přebírá název fronty, text zprávy a možnosti zprávy (které jsou volitelné).

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

Zobrazení náhledu další zprávy

Voláním můžete nahlédnout na jednu nebo více zpráv na začátku fronty, aniž byste je z fronty odebrali QueueRestProxy->peekMessages. Ve výchozím nastavení peekMessage vrátí metoda jednu zprávu, ale tuto hodnotu můžete změnit pomocí PeekMessagesOptions->setNumberOfMessages metody .

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

Vyřazení další zprávy z fronty

Kód odebere zprávu z fronty ve dvou krocích. Nejprve zavoláte QueueRestProxy->listMessages, což způsobí, že zpráva bude neviditelná pro jakýkoli jiný kód, který čte z fronty. Ve výchozím nastavení tato zpráva zůstává neviditelná po dobu 30 sekund. (Pokud se zpráva v tomto časovém období neodstraní, znovu se zobrazí ve frontě.) Chcete-li dokončit odebrání zprávy z fronty, musíte volat QueueRestProxy->deleteMessage. Tento dvoustupňový proces odebrání zprávy zajišťuje, že když se vašemu kódu nepodaří zpracovat zprávu kvůli selhání hardwaru nebo softwaru, může jiná instance vašeho kódu získat stejnou zprávu a zkusit to znovu. Váš kód zavolá deleteMessage hned po zpracování zprávy.

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

Změna obsahu zpráv zařazených ve frontě

Obsah zprávy ve frontě můžete změnit voláním QueueRestProxy->updateMessage. Pokud zpráva představuje pracovní úlohu, mohli byste tuto funkci použít k aktualizaci stavu pracovních úloh. Následující kód aktualizuje zprávu fronty novým obsahem a nastaví časový limit viditelnosti tak, aby se prodloužil o dalších 60 sekund. Tím se uloží stav práce spojený se zprávou a klient získá další minutu, aby na zprávě pokračoval v práci. Tuto techniku můžete použít ke sledování vícekrokových pracovních postupů ve zprávách fronty, aniž byste museli začít znovu od začátku, pokud krok zpracování selže kvůli selhání hardwaru nebo softwaru. Obvykle byste udržovali také hodnotu počtu opakování, a pokud by se pokus o zpracování zprávy opakoval více než nkrát, odstranili byste ji. Je to ochrana proti tomu, aby zpráva při každém pokusu o zpracování nevyvolala chyby aplikace.

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

Další možnosti pro vyřazení zpráv z fronty

Existují dva způsoby, jak přizpůsobit načítání zpráv z fronty. Za prvé si můžete načíst dávku zpráv (až 32). Za druhé můžete nastavit delší nebo kratší časový limit viditelnosti, což kódu umožní více či méně času na úplné zpracování každé zprávy. Následující příklad kódu používá metodu getMessages k získání 16 zpráv v jednom volání. Každou zprávu pak zpracuje pomocí smyčky for . Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut.

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

Získání délky fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě. Metoda QueueRestProxy->getQueueMetadata načte metadata fronty. getApproximateMessageCount Volání metody u vráceného objektu poskytuje počet zpráv, které jsou ve frontě. Počet je pouze přibližný, protože zprávy je možné přidat nebo odebrat poté, co Queue Storage odpoví na vaši žádost.

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;

Odstranění fronty

Pokud chcete odstranit frontu a všechny zprávy v ní, zavolejte metodu QueueRestProxy->deleteQueue .

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

Další kroky

Teď, když jste se seznámili se základy služby Azure Queue Storage, použijte tyto odkazy k získání informací o složitějších úlohách úložiště:

• Projděte si referenční informace k rozhraní API pro klientskou knihovnu PHP služby Azure Storage.
• Podívejte se na příklad rozšířené fronty.

Další informace najdete ve středisku pro vývojáře PHP.