Fuente de datos: SQS

1Presentación

Amazon SQS (Simple Queue Service) es una cola de mensajes usada para registrar órdenes de procesamiento por un lado, y recuperar esas órdenes para su procesamiento por el otro.

Si has configurado correctamente los parámetros de conexión de SQS, Temma crea automáticamente un objeto de tipo \Temma\Datasources\Sqs. Por convención, supondremos que has nombrado esta conexión sqs en el archivo etc/temma.php (consulta documentación de configuración).

La conexión está entonces disponible en el controlador de la siguiente forma: 

$sqs = $this->sqs;

En los demás objetos gestionados por el componente de inyección de dependencias, la conexión SQS es accesible de la siguiente forma: 

$sqs = $loader->dataSources->sqs;
$sqs = $loader->dataSources['sqs'];

2Instalación

Para conectarse a AWS (Amazon Web Services), Temma necesita acceso al AWS PHP SDK. Esto puede hacerse instalándolo con Composer, o instalándolo manualmente.

2.1Instalación con Composer

Para instalar el AWS PHP SDK con Composer, basta con escribir este comando desde la raíz del proyecto: 

$ composer require aws/aws-sdk-php

2.2Instalación manual

Para instalar el AWS PHP SDK manualmente, descarga el archivo aws.phar y colócalo en el directorio lib/ del proyecto. Por ejemplo, ejecutando el siguiente comando: 

$ wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

También puedes optar por instalar el AWS PHP SDK a nivel de sistema, para no tener que reinstalarlo en cada proyecto. Para ello, basta con copiar el archivo aws.phar en un directorio que forme parte de las rutas de inclusión, como /usr/share/php (en lugar de colocarlo en el directorio lib/ de tu proyecto).

3Configuración

En el archivo etc/temma.php (consulta documentación de configuración), declaras el DSN (Data Source Name) usado para conectarte a SQS.

El DSN usado para conectarse a SQS se escribe como: sqs://ACCESS_KEY:PRIVATE_KEY@QUEUE_URL[#WAIT_POLLING]

  • La clave de acceso y la clave privada son proporcionadas por AWS.
  • QUEUE_URL corresponde a la URL de la cola de mensajes, sin el prefijo "https://".
    Ejemplo: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name
  • WAIT_POLLING es el tiempo (opcional, en segundos) que la lectura esperará para recibir un mensaje antes de fallar y devolver un mensaje vacío. Puede tomar un valor entre 1 y 20.
    Ejemplo: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name#8

4Características específicas de las colas de mensajes

A diferencia de otras fuentes de datos, los mensajes se añaden a una cola de mensajes sin proporcionar un identificador (nombre, clave, ruta, etc.). El identificador se crea automáticamente mediante SQS. Cuando se lee un mensaje, su identificador se devuelve junto con sus datos; este identificador se usa posteriormente para eliminar el mensaje de la cola.

En consecuencia, SQS no permite comprobar la existencia de un mensaje a partir de su identificador, ni seleccionar un mensaje, ni definir un valor por defecto al recuperar un mensaje.

Ten en cuenta que, a diferencia de Beanstalk, donde las lecturas quedan bloqueadas hasta que un mensaje esté disponible, las lecturas en SQS no son bloqueantes. Es posible realizar long polling definiendo un tiempo límite de hasta 20 segundos. Sin embargo, si la llamada de lectura devuelve un valor nulo, tendrás que intentarlo de nuevo.

5Llamadas unificadas

5.1Acceso tipo array

// escribe un mensaje (serializado)
$sqs[''] = $data;

// lee un mensaje (deserializado)
// devuelve un array asociativo con las claves "id" y "data"
$msg = $sqs[''];

// eliminación del mensaje
unset($sqs[$msg['id']]);

// conteo de mensajes en espera
$cnt = count($sqs);

5.2Métodos generales

// elimina un mensaje
$sqs->remove($msg['id']);

// elimina todos los mensajes
$sqs->flush();

5.3Gestión de datos serializados complejos

// lee un mensaje (deserializado)
// devuelve un array asociativo con las claves "id" y "data"
$msg = $sqs->get('');

// lee un mensaje (deserializado) con una espera máxima de 8 segundos
// devuelve un array asociativo con las claves "id" y "data"
$msg = $sqs->get('', options: 8);

// escribe un mensaje (serializado)
$sqs->set('', $msgData);

// escribe varios mensajes (serializados)
$sqs->mSet([
    $user1data,
    $user2data,
    $user3data,
]);

5.4Gestión de datos en bruto

// lee un mensaje (en bruto)
// devuelve un array asociativo con las claves "id" y "data"
$html = $sqs->read('');

// lee un mensaje (en bruto) con una espera máxima de 8 segundos
// devuelve un array asociativo con las claves "id" y "data"
$html = $sqs->read('', options: 8);

// escribe un mensaje (en bruto)
$sqs->write('', $msgData);

// escribe varios mensajes (en bruto)
$sqs->mWrite([
    $user1data,
    $user2data,
    $user3data,
]);

// escribe un mensaje (en bruto) desde un archivo local
$sqs->copyTo('', '/path/to/file');

// escribe varios mensajes (en bruto) desde archivos locales
$sqs->mCopyTo([
    '/path/to/file1',
    '/path/to/file2',
    '/path/to/file3',
]);