Wie man den Warteschlangenspeicher aus PHP verwendet

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

Tipp

Testen des Microsoft Azure Storage Explorer-

Beim Microsoft Azure Storage-Explorer handelt es sich um eine kostenlose eigenständige App von Microsoft, über die Sie ganz einfach visuell mit Azure Storage-Daten arbeiten können – unter Windows, MacOS und Linux.

In diesem Handbuch erfahren Sie, wie Sie allgemeine Szenarien mithilfe des Azure Queue Storage-Diensts ausführen. Die Beispiele werden über Klassen aus der Azure Storage-Clientbibliothek für PHPgeschrieben. Die behandelten Szenarien umfassen das Einfügen, Einsehen, Abrufen und Löschen von Warteschlangennachrichten sowie das Erstellen und Löschen von Warteschlangen.

Was ist Queue-Speicher?

Azure Queue Storage ist ein Dienst zum Speichern großer Anzahl von Nachrichten, auf die von überall auf der Welt über authentifizierte Anrufe mit HTTP oder HTTPS zugegriffen werden kann. Eine einzelne Warteschlangennachricht kann bis zu 64 KB groß sein, und eine Warteschlange kann Millionen von Nachrichten bis zum Gesamtkapazitätslimit eines Speicherkontos enthalten. Der Warteschlangenspeicher wird häufig verwendet, um einen Arbeitsbestand zu erstellen, der asynchron verarbeitet werden kann.

Warteschlangendienstkonzepte

Der Azure-Warteschlangendienst enthält die folgenden Komponenten:

• Speicherkonto: Der gesamte Zugriff auf Azure Storage erfolgt über ein Speicherkonto. Weitere Informationen zu Speicherkonten finden Sie in der Speicherkontoübersicht.

• Warteschlange: Eine Warteschlange enthält einen Satz von Nachrichten. Alle Nachrichten müssen sich in Warteschlangen befinden. Beachten Sie, dass der Warteschlangenname nur aus Kleinbuchstaben bestehen darf. Informationen zum Benennen von Warteschlangen finden Sie unter Benennen von Warteschlangen und Metadaten.

• Nachricht: Eine Nachricht in einem beliebigen Format und mit einer Größe von bis zu 64 KB. Die maximale Zeit, die eine Nachricht in der Warteschlange verbleiben kann, beträgt 7 Tage. Für Version 2017-07-29 oder höhere Versionen kann die maximale Gültigkeitsdauer eine beliebige positive Zahl sein. Mit -1 wird angegeben, dass die Nachricht nicht abläuft. Wird dieser Parameter ausgelassen, beträgt die Standardgültigkeitsdauer sieben Tage.

• URL-Format: Warteschlangen können mithilfe des folgenden URL-Formats adressierbar sein: http://<storage account>.queue.core.windows.net/<queue>

  Die folgende URL behebt eine Warteschlange im Diagramm:

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

Erstellen eines Azure-Speicherkontos

Die einfachste Möglichkeit zum Erstellen Ihres ersten Azure-Speicherkontos ist die Verwendung des Azure-Portals. Weitere Informationen finden Sie unter Erstellen von Speicherkonten.

Sie können auch ein Azure-Speicherkonto erstellen, indem Sie Azure PowerShell-, Azure CLI-oder den Azure Storage Resource Provider für .NET-verwenden.

Wenn Sie derzeit kein Speicherkonto in Azure erstellen möchten, können Sie auch den Azurite-Speicheremulator verwenden, um Ihren Code in einer lokalen Umgebung auszuführen und zu testen. Weitere Informationen finden Sie unter Verwenden des Azurite-Emulators für die lokale Azure Storage-Entwicklung.

Erstellen einer PHP-Anwendung

Die einzige Anforderung zum Erstellen einer PHP-Anwendung, die auf Azure Queue Storage zugreift, ist die Referenzierung von Klassen in der Azure Storage-Clientbibliothek für PHP aus Ihrem Code. Sie können beliebige Entwicklungstools verwenden, um Ihre Anwendung zu erstellen, einschließlich Notepad.

In diesem Leitfaden verwenden Sie die Funktionen des Warteschlangenspeicherdiensts, die lokal in einer PHP-Anwendung oder in Code aufgerufen werden können, der in einer Webanwendung in Azure ausgeführt wird.

Abrufen der Azure-Clientbibliotheken

Installieren über Composer

1. Erstellen Sie eine Datei mit dem Namen composer.json im Stammverzeichnis Ihres Projekts, und fügen Sie ihm den folgenden Code hinzu:

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

2. Laden Sie composer.phar im Projektstamm herunter.

3. Öffnen Sie eine Eingabeaufforderung, und führen Sie den folgenden Befehl im Projektstamm aus:

   php composer.phar install
   

Alternativ wechseln Sie zur Azure Storage PHP-Clientbibliothek auf GitHub, um den Quellcode zu klonen.

Konfigurieren Sie Ihre Anwendung für den Zugriff auf Warteschlangenspeicher

Um die APIs für Azure Queue Storage zu verwenden, müssen Sie:

1. Verweisen Sie auf die Autoladedatei, indem Sie die require_once-Anweisung verwenden.
2. Verweisen Sie auf alle Klassen, die Sie verwenden können.

Das folgende Beispiel zeigt, wie Sie die AutoLoader-Datei einschließen und auf die QueueRestProxy Klasse verweisen.

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

In den folgenden Beispielen wird die require_once-Anweisung immer angezeigt, es wird jedoch nur auf die Klassen verwiesen, die zum Ausführen des Beispiels erforderlich sind.

Einrichten einer Azure Storage-Verbindung

Um einen Azure Queue Storage-Client instanziieren zu können, müssen Sie zuerst über eine gültige Verbindungszeichenfolge verfügen. Das Format für die Warteschlangenspeicher-Verbindungszeichenfolge lautet wie folgt.

Für den Zugriff auf einen Livedienst:

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

Für den Zugriff auf den Emulatorspeicher:

UseDevelopmentStorage=true

Um einen Azure Queue Storage-Client zu erstellen, müssen Sie die QueueRestProxy Klasse verwenden. Sie können eine der folgenden Techniken verwenden:

• Übergeben Sie die Verbindungszeichenfolge direkt an sie.
• Verwenden Sie Umgebungsvariablen in Ihrer Web-App, um die Verbindungszeichenfolge zu speichern. Siehe Azure Web App-Konfigurationseinstellungen Dokument zum Konfigurieren von Verbindungszeichenfolgen.

Für die hier beschriebenen Beispiele wird die Verbindungszeichenfolge direkt übergeben.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Warteschlange erstellen

Mit einem QueueRestProxy-Objekt können Sie eine Warteschlange mithilfe der CreateQueue-Methode erstellen. Beim Erstellen einer Warteschlange können Sie Optionen für die Warteschlange festlegen, dies ist jedoch nicht erforderlich. In diesem Beispiel wird gezeigt, wie Metadaten in einer Warteschlange festgelegt werden.

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

Hinweis

Sie sollten nicht auf die Groß-/Kleinschreibung für Metadatenschlüssel angewiesen sein. Alle Schlüssel werden aus dem Dienst in Kleinbuchstaben gelesen.

Hinzufügen einer Nachricht zu einer Warteschlange

Um einer Warteschlange eine Nachricht hinzuzufügen, verwenden Sie QueueRestProxy->createMessage. Die Methode verwendet den Warteschlangennamen, den Nachrichtentext und die Nachrichtenoptionen (optional).

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

Vorschau auf die nächste Nachricht

Sie können eine oder mehrere Nachrichten an der Vorderseite einer Warteschlange anzeigen, ohne sie aus der Warteschlange zu entfernen, indem Sie QueueRestProxy->peekMessagesaufrufen. Standardmäßig gibt die peekMessage-Methode eine einzelne Nachricht zurück, Aber Sie können diesen Wert mithilfe der PeekMessagesOptions->setNumberOfMessages-Methode ändern.

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

Aufheben der Warteschlange der nächsten Nachricht

Ihr Code entfernt eine Nachricht aus einer Warteschlange in zwei Schritten. Zuerst rufen Sie QueueRestProxy->listMessagesauf, wodurch die Nachricht für jeden anderen Code unsichtbar wird, der aus der Warteschlange gelesen wird. Diese Nachricht bleibt standardmäßig 30 Sekunden lang unsichtbar. (Wenn die Nachricht in diesem Zeitraum nicht gelöscht wird, wird sie erneut in der Warteschlange angezeigt.) Um das Entfernen der Nachricht aus der Warteschlange abzuschließen, müssen Sie QueueRestProxy->deleteMessageanrufen. Dieser zweistufige Prozess zum Entfernen einer Nachricht stellt sicher, dass beim Verarbeiten einer Nachricht aufgrund von Hardware- oder Softwarefehlern eine andere Instanz des Codes dieselbe Nachricht erhalten und es erneut versuchen kann. Ihr Code ruft deleteMessage direkt nach der Verarbeitung der Nachricht auf.

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

Ändern des Inhalts einer in die Warteschlange eingereihten Nachricht

Sie können den Inhalt einer Nachricht in der Warteschlange ändern, indem Sie QueueRestProxy->updateMessageaufrufen. Wenn die Nachricht eine Arbeitsaufgabe darstellt, können Sie dieses Feature verwenden, um den Status der Arbeitsaufgabe zu aktualisieren. Der folgende Code aktualisiert die Warteschlangennachricht mit neuem Inhalt und legt das Zeitlimit für die Sichtbarkeit fest, um weitere 60 Sekunden zu verlängern. Dadurch wird der Arbeitsstatus gespeichert, der der Nachricht zugeordnet ist, und dem Client wird eine weitere Minute zugewiesen, um die Arbeit an der Nachricht fortzusetzen. Sie können diese Technik verwenden, um mehrstufige Workflows in Warteschlangennachrichten nachzuverfolgen, ohne von Anfang an zu beginnen, wenn ein Verarbeitungsschritt aufgrund von Hardware- oder Softwarefehlern fehlschlägt. Normalerweise würden Sie auch eine Wiederholungsanzahl beibehalten, und wenn die Nachricht mehr als n Mal wiederholt wird, würden Sie sie löschen. Dadurch wird vor einer Meldung geschützt, die bei jeder Verarbeitung einen Anwendungsfehler auslöst.

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

Zusätzliche Optionen für das De-Queueing von Nachrichten

Es gibt zwei Möglichkeiten, um den Nachrichtenabruf aus einer Warteschlange anzupassen. Zunächst können Sie eine Reihe von Nachrichten (bis zu 32) abrufen. Zweitens können Sie ein längeres oder kürzeres Sichtbarkeitstimeout festlegen, sodass Ihr Code mehr oder weniger Zeit zum vollständigen Verarbeiten jeder Nachricht hat. Im folgenden Codebeispiel wird die getMessages-Methode verwendet, um 16 Nachrichten in einem Aufruf abzurufen. Anschließend verarbeitet sie jede Nachricht mithilfe einer for Schleife. Außerdem wird für jede Nachricht das Timeout für die Unsichtbarkeit auf fünf Minuten festgelegt.

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

Warteschlangenlänge abrufen

Sie können die Anzahl der Nachrichten in einer Warteschlange schätzen lassen. Die QueueRestProxy->getQueueMetadata Methode ruft Metadaten zur Warteschlange ab. Das Aufrufen der getApproximateMessageCount-Methode für das zurückgegebene Objekt gibt an, wie viele Nachrichten sich in einer Warteschlange befinden. Die Anzahl ist nur ungefähr, da Nachrichten hinzugefügt oder entfernt werden können, nachdem der Warteschlangenspeicher auf Ihre Anforderung antwortet.

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;

Eine Warteschlange löschen

Rufen Sie zum Löschen einer Warteschlange und aller darin angezeigten Nachrichten die QueueRestProxy->deleteQueue-Methode auf.

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ächste Schritte

Nachdem Sie nun die Grundlagen von Azure Queue Storage kennengelernt haben, folgen Sie diesen Links, um mehr über komplexere Speicheraufgaben zu erfahren:

• Besuchen Sie die API-Referenz für die Azure Storage PHP-Clientbibliothek
• Sehen Sie sich das erweiterte Warteschlangenbeispielan.

Weitere Informationen finden Sie im PHP Developer Center.