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

W tym przewodniku przedstawiono sposób wykonywania typowych scenariuszy przy użyciu usługi Azure Queue Storage. Przykłady są pisane za pośrednictwem klas z biblioteki klienta usługi Azure Storage dla języka PHP. Omówione scenariusze obejmują wstawianie, pokazywanie, pobieranie i usuwanie komunikatów w kolejce, 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órych można uzyskiwać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionych wywołań przy użyciu protokołu HTTP lub HTTPS. Pojedynczy komunikat w kolejce może mieć rozmiar do 64 KB, a kolejka może zawierać miliony komunikatów, aż do osiągnięcia całkowitej pojemności konta magazynu. Usługa Queue Storage jest często używana do tworzenia listy prac w celu asynchronicznego przetwarzania.

Pojęcia dotyczące usługi kolejkowania

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

• #B0 Konto magazynowe: #C1 Wszelki dostęp do usługi Azure Storage odbywa się za pośrednictwem konta magazynowego. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu.

• Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie wiadomości 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 wygasa. 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://.queue.core.windows.net/<storage account>

  Następujący adres URL adresuje kolejkę na diagramie:

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

Tworzenie konta usługi Azure Storage

Najprostszym sposobem utworzenia pierwszego konta usługi Azure Storage jest użycie witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta usług magazynowych.

Konto usługi Azure Storage można również utworzyć przy użyciu programu Azure PowerShell, interfejsu wiersza polecenia platformy Azurelub 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 do uruchomienia i przetestowania kodu w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development.

Tworzenie aplikacji 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. Możesz użyć dowolnego narzędzia programistycznego do utworzenia aplikacji, w tym Notatnika.

W tym przewodniku użyjesz 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
   

Możesz też przejść do biblioteki klienta PHP usługi Azure Storage w witrynie 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łuj się do pliku autoloader przy użyciu instrukcji require_once .
2. Odwołaj się do dowolnych klas, których możesz użyć.

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

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

W poniższych przykładach instrukcja require_once jest zawsze pokazywana, ale wymieniane są 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, należy użyć QueueRestProxy klasy . Możesz 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. Aby skonfigurować parametry połączenia, zobacz dokument Ustawienia konfiguracji aplikacji internetowej platformy Azure .

W przykładach opisanych tutaj 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);

Utwórz kolejkę

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

Dodaj komunikat do kolejki

Aby dodać komunikat do kolejki, użyj polecenia QueueRestProxy->createMessage. Metoda przyjmuje nazwę kolejki, tekst komunikatu i opcje komunikatu (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 />";
}

Przyjrzyj się następnej wiadomości

Możesz zajrzeć do jednej lub więcej wiadomości na początku kolejki bez ich usuwania, wywołując metodę 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 />";
    }
}

Usuń z kolejki następną wiadomość

Kod usuwa wiadomość z kolejki w dwóch krokach. Najpierw wywołujesz metodę QueueRestProxy->listMessages, co sprawia, że komunikat jest niewidoczny dla każdego 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ę ponownie widoczny 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 deleteMessage bezpośrednio po przetworzeniu wiadomości.

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

Można zmienić zawartość komunikatu bezpośrednio w kolejce, wywołując polecenie QueueRestProxy->updateMessage. Jeśli komunikat reprezentuje zadanie robocze, możesz użyć tej funkcji, aby zaktualizować stan zadania roboczego. Poniższy kod aktualizuje komunikat kolejki nową zawartością i ustawia limit czasu widoczności, przedłużając go o kolejne 60 sekund. Spowoduje to zapisanie stanu pracy skojarzonej z komunikatem i daje klientowi kolejną minutę na kontynuowanie pracy nad komunikatem. Można użyć tej techniki do śledzenia wieloetapowych przepływów pracy w wiadomościach w kolejce, bez konieczności zaczynania od początku, jeśli krok przetwarzania zakończy się niepowodzeniem spowodowanym awarią sprzętu lub oprogramowania. Zazwyczaj należy zachować liczbę ponownych prób, a jeśli komunikat zostanie ponowiony więcej niż n razy, należy go usunąć. Chroni to przed komunikatem, który wyzwala błąd aplikacji za każdym razem, gdy jest przetwarzany.

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 odkolejkowywania komunikatów

Istnieją dwa sposoby dostosowywania pobierania komunikatów z kolejki. Najpierw możesz pobrać partię komunikatów (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 metody `getMessages` do pobrania 16 komunikatów podczas jednego wywołania. 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 />";
}

Pobierz długość kolejki

Możesz uzyskać szacunkową liczbę komunikatów w kolejce. Metoda QueueRestProxy->getQueueMetadata pobiera metadane dotyczące kolejki. getApproximateMessageCount Wywołanie metody dla zwróconego obiektu podaje ilość komunikatów znajdujących się w kolejce. Liczba jest przybliżona, ponieważ 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;

Usuń kolejkę

Aby usunąć kolejkę i wszystkie komunikaty w niej, 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 łączy, aby dowiedzieć się więcej o bardziej złożonych zadaniach przechowywania.

• 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.