Uso del almacenamiento de colas de PHPHow to use Queue storage from PHP

Sugerencia

Probar el Explorador de Microsoft Azure StorageTry the Microsoft Azure Storage Explorer

El Explorador de Microsoft Azure Storage es una aplicación independiente y gratuita de Microsoft que permite trabajar visualmente con los datos de Azure Storage en Windows, macOS y Linux.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Información generalOverview

Esta guía muestra cómo realizar algunas tareas comunes a través del servicio Azure Queue Storage.This guide shows you how to perform common scenarios by using the Azure Queue storage service. Los ejemplos están escritos mediante clases de la biblioteca de cliente de Azure Storage para PHP.The samples are written via classes from the Azure Storage Client Library for PHP. Entre los escenarios descritos se incluyen insertar, ojear, obtener y eliminar mensajes de la cola, así como crear y eliminar colas.The covered scenarios include inserting, peeking, getting, and deleting queue messages, as well as creating and deleting queues.

¿Qué es Queue Storage?What is Queue Storage?

El almacenamiento en cola de Azure es un servicio para almacenar grandes cantidades de mensajes a los que puede obtenerse acceso desde cualquier lugar del mundo a través de llamadas autenticadas con HTTP o HTTPS.Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. Un único mensaje en cola puede tener un tamaño de hasta 64 KB y una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento.A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

El almacenamiento en cola suele usarse para realizar las siguientes tareas:Common uses of Queue storage include:

  • Creación de trabajo pendiente para el procesamiento asincrónicoCreating a backlog of work to process asynchronously
  • Transferencia de mensajes de un rol web de Azure a un rol de trabajo de AzurePassing messages from an Azure web role to an Azure worker role

Conceptos del servicio ColaQueue Service Concepts

El servicio Cola contiene los siguientes componentes:The Queue service contains the following components:

Cola1

  • Formato de dirección URL: Las colas son direccionables mediante el siguiente formato de dirección URL:URL format: Queues are addressable using the following URL format:
    http://<storage account>.queue.core.windows.net/<queue>http://<storage account>.queue.core.windows.net/<queue>

    La siguiente dirección URL dirige a una cola del diagrama:The following URL addresses a queue in the diagram:

    http://myaccount.queue.core.windows.net/images-to-download

  • Cuenta de almacenamiento: Todo el acceso a Azure Storage se realiza a través de una cuenta de almacenamiento.Storage Account: All access to Azure Storage is done through a storage account. Consulte Objetivos de escalabilidad y rendimiento de Azure Storage para obtener información sobre la capacidad de la cuenta de almacenamiento.See Azure Storage Scalability and Performance Targets for details about storage account capacity.

  • Cola: una cola contiene un conjunto de mensajes.Queue: A queue contains a set of messages. Todos los mensajes deben encontrarse en una cola.All messages must be in a queue. Tenga en cuenta que el nombre de la cola debe ir en minúsculas.Note that the queue name must be all lowercase. Para más información, consulte Asignar nombres a colas y metadatos.For information on naming queues, see Naming Queues and Metadata.

  • Mensaje: un mensaje, en cualquier formato, de hasta 64 KB.Message: A message, in any format, of up to 64 KB. El tiempo máximo que un mensaje puede permanecer en la cola es de 7 días.The maximum time that a message can remain in the queue is 7 days.

Creación de una cuenta de Azure StorageCreate an Azure storage account

La forma más fácil de crear la primera cuenta de Azure Storage es a través de Azure Portal.The easiest way to create your first Azure storage account is by using the Azure portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.To learn more, see Create a storage account.

Puede crear también una cuenta de Azure Storage mediante Azure PowerShell, la CLI de Azure o el proveedor de recursos de Azure Storage para .NET.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Si no desea crear una cuenta de almacenamiento en Azure en este momento, también puede utilizar el emulador de Azure Storage para ejecutar y probar el código en un entorno local.If you prefer not to create a storage account in Azure at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure Storage Emulator for Development and Testing.

Creación de una aplicación PHPCreate a PHP application

El único requisito a la hora de crear una aplicación PHP para obtener acceso al servicio Azure Queue Storage es que el código haga referencia a clases de la biblioteca de cliente de Azure Storage para PHP.The only requirement for creating a PHP application that accesses Azure Queue storage is the referencing of classes in the Azure Storage Client Library for PHP from within your code. Puede utilizar cualquier herramienta de desarrollo para crear la aplicación, incluido el Bloc de notas.You can use any development tools to create your application, including Notepad.

En esta guía, usará funciones del servicio Queue Storage a las que se puede llamar desde una aplicación PHP localmente o bien mediante código a través de un rol web, rol de trabajo o sitio web de Azure.In this guide, you use the Queue storage service features that can be called within a PHP application locally, or in code running within an Azure web role, worker role, or website.

Obtención de las bibliotecas de clientes de AzureGet the Azure Client Libraries

Instalación mediante el compositorInstall via Composer

  1. Cree un archivo con el nombre composer.json en la raíz del proyecto y agréguele el código siguiente:Create a file named composer.json in the root of your project and add the following code to it:

    {
      "require": {
        "microsoft/azure-storage-queue": "*"
      }
    }
    
  2. Descargue composer.phar en la raíz del proyecto.Download composer.phar in your project root.

  3. Abra un símbolo del sistema y ejecute el siguiente comando en la raíz del proyectoOpen a command prompt and execute the following command in your project root

    php composer.phar install
    

También puede ir a la biblioteca de cliente de PHP de Azure Storage en GitHub para clonar el código fuente.Alternatively go to the Azure Storage PHP Client Library on GitHub to clone the source code.

Configuración de la aplicación para obtener acceso al almacenamiento en colaConfigure your application to access Queue storage

Para usar las API de almacenamiento en cola de Azure, necesitará:To use the APIs for Azure Queue storage, you need to:

  1. Hacer referencia al archivo autocargador mediante la instrucción require_once.Reference the autoloader file by using the require_once statement.
  2. Hacer referencia a todas las clases que puede que use.Reference any classes that you might use.

En el siguiente ejemplo se muestra cómo incluir el archivo autocargador y hacer referencia a la clase QueueRestProxy.The following example shows how to include the autoloader file and reference the QueueRestProxy class.

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

En los ejemplos siguientes, la instrucción require_once se muestra siempre, pero solo se hará referencia a las clases necesarias para la ejecución del ejemplo.In the following examples, the require_once statement is shown always, but only the classes that are necessary for the example to execute are referenced.

Configuración de una conexión de Almacenamiento de AzureSet up an Azure storage connection

Para crear una instancia de un cliente de almacenamiento en cola de Azure, primero debe disponer de una cadena de conexión válida.To instantiate an Azure Queue storage client, you must first have a valid connection string. El formato de las cadenas de conexión del servicio Cola es:The format for the queue service connection string is as follows.

Para obtener acceso a un servicio en directo:For accessing a live service:

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

Para obtener acceso al emulador de almacenamiento:For accessing the emulator storage:

UseDevelopmentStorage=true

Para crear un cliente del servicio Azure Queue, debe usar la clase QueueRestProxy.To create an Azure Queue service client, you need to use the QueueRestProxy class. Puede usar cualquiera de las técnicas siguientes:You can use either of the following techniques:

  • pasarle directamente la cadena de conexión, o bienPass the connection string directly to it.
  • usar variables de entorno en la aplicación web para almacenar la cadena de conexión.Use environment variables in your Web App to store the connection string. Consulte el documento sobre la configuración de aplicaciones web en Azure para configurar cadenas de conexión.See Azure web app configuration settings document for configuring connection strings. En los ejemplos descritos aquí, la cadena de conexión se pasa directamente.For the examples outlined here, the connection string is passed directly.
require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

Crear una colaCreate a queue

Un objeto QueueRestProxy le permite crear una cola con el método createQueue.A QueueRestProxy object lets you create a queue by using the createQueue method. Al crear una cola, puede establecer opciones en ella, aunque no es obligatorio.When creating a queue, you can set options on the queue, but doing so is not required. El ejemplo siguiente muestra cómo configurar metadatos en una cola.(The example below shows how to set metadata on a queue.)

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

Nota

No debe confiar en la distinción entre minúsculas y mayúsculas para las claves de metadatos.You should not rely on case sensitivity for metadata keys. Todas las claves se leen en el servicio en minúsculas.All keys are read from the service in lowercase.

un mensaje a una colaAdd a message to a queue

Para agregar un mensaje a una cola, use QueueRestProxy->createMessage.To add a message to a queue, use QueueRestProxy->createMessage. El método toma el nombre de la cola, el texto del mensaje y las opciones de mensaje (que son opcionales).The method takes the queue name, the message text, and message options (which are 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 />";
}

siguiente mensajePeek at the next message

Puede ojear uno o varios mensajes en la parte delantera de una cola, sin quitarlos de la cola, mediante una llamada a QueueRestProxy->peekMessages.You can peek at a message (or messages) at the front of a queue without removing it from the queue by calling QueueRestProxy->peekMessages. De forma predeterminada, el método peekMessage devuelve un único mensaje, pero puede cambiar el valor con el método PeekMessagesOptions->setNumberOfMessages.By default, the peekMessage method returns a single message, but you can change that value by using the PeekMessagesOptions->setNumberOfMessages method.

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

siguiente mensaje de la colaDe-queue the next message

El código borra un mensaje de una cola en dos pasos.Your code removes a message from a queue in two steps. Primero llama a QueueRestProxy->listMessages, que hace que el mensaje sea invisible a cualquier otro código que esté leyendo de la cola.First, you call QueueRestProxy->listMessages, which makes the message invisible to any other code that's reading from the queue. De forma predeterminada, este mensaje permanece invisible durante 30 segundos.By default, this message stays invisible for 30 seconds. (Si el mensaje no se elimina en este período, volverá a estar visible de nuevo en la cola). Para terminar de quitar el mensaje de la cola, debe llamar a QueueRestProxy->deleteMessage.(If the message is not deleted in this time period, it becomes visible on the queue again.) To finish removing the message from the queue, you must call QueueRestProxy->deleteMessage. Este proceso de extracción de un mensaje que consta de dos pasos garantiza que si su código no puede procesar un mensaje a causa de un error de hardware o software, otra instancia de su código puede obtener el mismo mensaje e intentarlo de nuevo.This two-step process of removing a message assures that when your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. Su código llama a deleteMessage justo después de que se haya procesado el mensaje.Your code calls deleteMessage right after the message has been processed.

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

contenido de un mensaje en colaChange the contents of a queued message

Puede cambiar el contenido de un mensaje local en la cola llamando a QueueRestProxy->updateMessage.You can change the contents of a message in-place in the queue by calling QueueRestProxy->updateMessage. Si el mensaje representa una tarea de trabajo, puede usar esta característica para actualizar el estado de la tarea de trabajo.If the message represents a work task, you could use this feature to update the status of the work task. El siguiente código actualiza el mensaje de la cola con contenido nuevo y amplía el tiempo de espera de la visibilidad en 60 segundos más.The following code updates the queue message with new contents, and it sets the visibility timeout to extend another 60 seconds. De este modo, se guarda el estado de trabajo asociado al mensaje y se le proporciona al cliente un minuto más para que siga elaborando el mensaje.This saves the state of work that's associated with the message, and it gives the client another minute to continue working on the message. Esta técnica se puede usar para realizar un seguimiento de los flujos de trabajo de varios pasos en los mensajes en cola, sin que sea necesario volver a empezar desde el principio si se produce un error en un paso del proceso a causa de un error de hardware o software.You could use this technique to track multi-step workflows on queue messages, without having to start over from the beginning if a processing step fails due to hardware or software failure. Normalmente, también mantendría un número de reintentos y, si el mensaje se intentara más de n veces, lo eliminaría.Typically, you would keep a retry count as well, and if the message is retried more than n times, you would delete it. Esto proporciona protección frente a un mensaje que produce un error en la aplicación cada vez que se procesa.This protects against a message that triggers an application error each time it is processed.

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

Opciones adicionales para quitar mensajes de la colaAdditional options for de-queuing messages

Hay dos formas de personalizar la recuperación de mensajes de una cola.There are two ways that you can customize message retrieval from a queue. En primer lugar, puede obtener un lote de mensajes (hasta 32).First, you can get a batch of messages (up to 32). En segundo lugar, puede establecer un tiempo de espera de la visibilidad más largo o más corto para que el código disponga de más o menos tiempo para procesar cada mensaje.Second, you can set a longer or shorter visibility timeout, allowing your code more or less time to fully process each message. El siguiente ejemplo de código utiliza el método getMessages para obtener 16 mensajes en una llamada.The following code example uses the getMessages method to get 16 messages in one call. A continuación, procesa cada mensaje con un bucle for .Then it processes each message by using a for loop. También establece el tiempo de espera de la invisibilidad en cinco minutos para cada mensaje.It also sets the invisibility timeout to five minutes for each message.

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

longitud de la colaGet queue length

Puede obtener una estimación del número de mensajes existentes en una cola.You can get an estimate of the number of messages in a queue. El método QueueRestProxy->getQueueMetadata solicita a Queue service que devuelva los metadatos sobre la cola.The QueueRestProxy->getQueueMetadata method asks the queue service to return metadata about the queue. Si llama al método getApproximateMessageCount en el objeto devuelto, se ofrece un recuento de la cantidad de mensajes que hay en una cola.Calling the getApproximateMessageCount method on the returned object provides a count of how many messages are in a queue. El recuento solo es aproximado, ya que se pueden agregar o borrar mensajes después de que el servicio de cola haya respondido su solicitud.The count is only approximate because messages can be added or removed after the queue service responds to your request.

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;

Eliminación de una colaDelete a queue

Para eliminar una cola y todos los mensajes contenidos en ella, llame al método QueueRestProxy->deleteQueue.To delete a queue and all the messages in it, call the QueueRestProxy->deleteQueue method.

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

Pasos siguientesNext steps

Ahora que está familiarizado con los aspectos básicos del almacenamiento en cola de Azure, use estos vínculos para obtener más información acerca de tareas de almacenamiento más complejas.Now that you've learned the basics of Azure Queue storage, follow these links to learn about more complex storage tasks:

Para obtener más información, consulte también el Centro para desarrolladores de PHP.For more information, see also the PHP Developer Center.