Jak używać usługi Queue Storage z poziomu języka PHP

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

Porada

Wypróbuj program Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer jest bezpłatną aplikacją autonomiczną oferowaną przez firmę Microsoft, która umożliwia wizualną pracę z danymi w usłudze Azure Storage w systemach Windows, macOS i Linux.

W tym przewodniku przedstawiono sposób wykonywania typowych scenariuszy przy użyciu usługi Azure Queue Storage. Przykłady są pisane za pomocą klas z biblioteki klienta usługi Azure Storage dla języka PHP. Omówione scenariusze obejmują wstawianie, podgląd, pobieranie i usuwanie komunikatów kolejki, a także tworzenie i usuwanie kolejek.

Co to jest usługa Queue Storage?

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów, do której można uzyskać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionego połączenia za pomocą protokołu HTTP lub HTTPS. Pojedynczy komunikat z kolejki nie może przekraczać 64 KB, a kolejka może zawierać miliony komunikatów — maksymalnie liczbę nieprzekraczającą całkowitego limitu pojemności konta magazynu. Usługa Queue Storage jest często używana do tworzenia listy prac w celu przetwarzania asynchronicznego.

Pojęcia dotyczące usługi kolejki

Usługa Azure Queue service zawiera następujące składniki:

• Konto magazynu: cały dostęp do usługi Azure Storage odbywa się przez konto magazynu. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu.

• Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie komunikaty muszą być w kolejce. Pamiętaj, że nazwa kolejki może zawierać tylko małe litery. Informacje dotyczące nazewnictwa kolejek można znaleźć w temacie Naming Queues and Metadata (Nazewnictwo kolejek i metadanych).

• Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Maksymalny czas pozostawania komunikatu w kolejce wynosi 7 dni. W przypadku wersji 2017-07-29 lub nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią lub -1 wskazującą, że komunikat nie wygaśnie. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi siedem dni.

• Format adresu URL: Kolejki są adresowalne przy użyciu następującego formatu adresu URL: http://<storage account>.queue.core.windows.net/<queue>

  Następujący adres URL dotyczy kolejki w schemacie:

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

Tworzenie konta usługi Azure Storage

Najprościej jest utworzyć pierwsze konto usługi Azure Storage przy użyciu witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.

Można również utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell, interfejsu wiersza polecenia Azure lub dostawcy zasobów usługi Azure Storage dla platformy .NET.

Jeśli w tej chwili nie chcesz tworzyć konta magazynu na platformie Azure, możesz również użyć emulatora magazynu Azurite, aby uruchomić i przetestować kod w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Tworzenie aplikacji języka PHP

Jedynym wymaganiem do utworzenia aplikacji PHP, która uzyskuje dostęp do usługi Azure Queue Storage, jest odwołanie do klas w bibliotece klienta usługi Azure Storage dla języka PHP z poziomu kodu. Do utworzenia aplikacji możesz użyć dowolnych narzędzi programistycznych, w tym programu Notatnik.

W tym przewodniku używasz funkcji usługi Queue Storage, które mogą być wywoływane lokalnie w aplikacji PHP lub w kodzie uruchomionym w aplikacji internetowej na platformie Azure.

Pobieranie bibliotek klienckich platformy Azure

Instalowanie za pośrednictwem kompozytora

1. Utwórz plik o nazwie composer.json w katalogu głównym projektu i dodaj do niego następujący kod:

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

2. Pobierz composer.phar plik w katalogu głównym projektu.

3. Otwórz wiersz polecenia i uruchom następujące polecenie w katalogu głównym projektu:

   php composer.phar install
   

Alternatywnie przejdź do biblioteki klienta PHP usługi Azure Storage w usłudze GitHub, aby sklonować kod źródłowy.

Konfigurowanie aplikacji w celu uzyskania dostępu do usługi Queue Storage

Aby użyć interfejsów API dla usługi Azure Queue Storage, należy wykonać następujące kroki:

1. Odwołaj się do pliku autoloadera przy użyciu instrukcji require_once .
2. Odwołaj się do wszystkich klas, których można użyć.

W poniższym przykładzie pokazano, jak dołączyć plik autoloader i odwołać się do QueueRestProxy klasy.

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

W poniższych przykładach require_once instrukcja jest wyświetlana zawsze, ale przywoły są przywołyane tylko klasy wymagane do uruchomienia przykładu.

Konfigurowanie połączenia usługi Azure Storage

Aby utworzyć wystąpienie klienta usługi Azure Queue Storage, musisz najpierw mieć prawidłowe parametry połączenia. Format parametrów połączenia usługi Queue Storage jest następujący.

Aby uzyskać dostęp do usługi na żywo:

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

Aby uzyskać dostęp do magazynu emulatora:

UseDevelopmentStorage=true

Aby utworzyć klienta usługi Azure Queue Storage, musisz użyć QueueRestProxy klasy . Można użyć jednej z następujących technik:

• Przekaż parametry połączenia bezpośrednio do niego.
• Użyj zmiennych środowiskowych w aplikacji internetowej do przechowywania parametrów połączenia. Zobacz dokument Ustawienia konfiguracji aplikacji internetowej platformy Azure , aby skonfigurować parametry połączenia.

W przedstawionych tutaj przykładach parametry połączenia są przekazywane bezpośrednio.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Tworzenie kolejki

Obiekt QueueRestProxy umożliwia utworzenie kolejki przy użyciu CreateQueue metody . Podczas tworzenia kolejki można ustawić opcje w kolejce, ale nie jest to wymagane. W tym przykładzie pokazano, jak ustawić metadane w kolejce.

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

Uwaga

Nie należy polegać na poufności liter dla kluczy metadanych. Wszystkie klucze są odczytywane z usługi w małych literach.

Dodawanie komunikatu do kolejki

Aby dodać komunikat do kolejki, użyj polecenia QueueRestProxy->createMessage. Metoda przyjmuje nazwę kolejki, tekst komunikatu i opcje komunikatu (które są opcjonalne).

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

Podgląd kolejnego komunikatu

Możesz zajrzeć do co najmniej jednego komunikatu z przodu kolejki bez usuwania ich z kolejki, wywołując polecenie QueueRestProxy->peekMessages. Domyślnie peekMessage metoda zwraca pojedynczy komunikat, ale można zmienić tę wartość przy użyciu 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 />";
    }
}

Usunięcie następnego komunikatu z kolejki

Kod usuwa komunikat z kolejki w dwóch krokach. Najpierw wywołasz metodę QueueRestProxy->listMessages, co sprawia, że komunikat jest niewidoczny dla dowolnego innego kodu odczytywanego z kolejki. Domyślnie komunikat pozostanie niewidoczny przez 30 sekund. (Jeśli komunikat nie zostanie usunięty w tym okresie, stanie się widoczny ponownie w kolejce). Aby zakończyć usuwanie komunikatu z kolejki, należy wywołać metodę QueueRestProxy->deleteMessage. Ten dwuetapowy proces usuwania komunikatu zapewnia, że gdy kod nie przetworzy komunikatu z powodu awarii sprzętu lub oprogramowania, inne wystąpienie kodu może uzyskać ten sam komunikat i spróbować ponownie. Kod wywołuje się deleteMessage bezpośrednio po przetworzeniu komunikatu.

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

Zmiana zawartości komunikatu w kolejce

Zawartość komunikatu w kolejce można zmienić, wywołując polecenie QueueRestProxy->updateMessage. Jeśli komunikat reprezentuje zadanie robocze, możesz użyć tej funkcji, aby zaktualizować stan zadania. Poniższy kod aktualizuje komunikat kolejki o nowej zawartości i ustawia limit czasu widoczności, aby przedłużyć kolejne 60 sekund. Spowoduje to zapisanie stanu pracy skojarzonej z komunikatem i daje klientowi kolejną minutę kontynuowania pracy nad komunikatem. Możesz użyć tej techniki do śledzenia wieloetapowych przepływów pracy w komunikatach kolejki, bez konieczności rozpoczynania się od początku, jeśli krok przetwarzania zakończy się niepowodzeniem z powodu awarii sprzętu lub oprogramowania. Zazwyczaj stosuje się również liczbę ponownych prób. Jeśli komunikat zostanie ponowiony więcej niż n razy, zostanie usunięty. Jest to zabezpieczenie przed komunikatami, które wyzwalają błąd aplikacji zawsze, gdy są przetwarzane.

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

Dodatkowe opcje usuwania komunikatów w kolejce

Istnieją dwa sposoby dostosowywania pobierania komunikatów z kolejki. Po pierwsze można uzyskać komunikaty zbiorczo (do 32). Po drugie można ustawić dłuższy lub krótszy limit czasu widoczności, dzięki czemu kod może w pełni przetworzyć każdy komunikat. Poniższy przykład kodu używa getMessages metody do pobierania 16 komunikatów w jednym wywołaniu. Następnie przetwarza każdy komunikat przy użyciu for pętli. Ustawia również limitu czasu niewidoczności na pięć minut dla każdego komunikatu.

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

Uzyskiwanie długości kolejki

Możesz uzyskać szacunkową liczbę komunikatów w kolejce. Metoda QueueRestProxy->getQueueMetadata pobiera metadane dotyczące kolejki. getApproximateMessageCount Wywołanie metody dla zwracanego obiektu zapewnia liczbę komunikatów znajdujących się w kolejce. Liczba jest przybliżona tylko dlatego, że komunikaty można dodać lub usunąć po odpowiedzi usługi Queue Storage na żądanie.

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;

Usuwanie kolejki

Aby usunąć kolejkę i wszystkie komunikaty w nim, wywołaj metodę 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 />";
}

Następne kroki

Teraz, gdy znasz już podstawy usługi Azure Queue Storage, skorzystaj z poniższych linków, aby dowiedzieć się więcej o bardziej złożonych zadaniach magazynu:

• Zapoznaj się z dokumentacją interfejsu API dotyczącą biblioteki klienta PHP usługi Azure Storage
• Zobacz przykład zaawansowanej kolejki.

Aby uzyskać więcej informacji, zobacz Centrum deweloperów JĘZYKA PHP.