Fonte de dados: SQS

1Apresentação

Amazon SQS (Simple Queue Service) é uma fila de mensagens usada para registrar ordens de processamento de um lado, e recuperar essas ordens para processamento do outro.

Se você configurou corretamente os parâmetros de conexão do SQS, o Temma cria automaticamente um objeto do tipo \Temma\Datasources\Sqs. Por convenção, vamos supor que você nomeou essa conexão sqs no arquivo etc/temma.php (veja a documentação de configuração).

A conexão fica então disponível no controlador da seguinte forma: 

$sqs = $this->sqs;

Nos demais objetos gerenciados pelo componente de injeção de dependências, a conexão SQS é acessível da seguinte forma: 

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

2Instalação

Para se conectar à AWS (Amazon Web Services), o Temma precisa de acesso ao AWS PHP SDK. Isso pode ser feito instalando-o com o Composer, ou instalando-o manualmente.

2.1Instalação com o Composer

Para instalar o AWS PHP SDK com o Composer, basta digitar este comando a partir da raiz do projeto: 

$ composer require aws/aws-sdk-php

2.2Instalação manual

Para instalar o AWS PHP SDK manualmente, baixe o arquivo aws.phar e coloque-o no diretório lib/ do projeto. Por exemplo, executando o seguinte comando: 

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

Você também pode optar por instalar o AWS PHP SDK em nível de sistema, para não ter que reinstalá-lo para cada projeto. Para isso, basta copiar o arquivo aws.phar para um diretório que faça parte dos caminhos de inclusão, como /usr/share/php (em vez de colocá-lo no diretório lib/ do seu projeto).

3Configuração

No arquivo etc/temma.php (veja a documentação de configuração), você declara o DSN (Data Source Name) usado para se conectar ao SQS.

O DSN usado para se conectar ao SQS é escrito como: sqs://ACCESS_KEY:PRIVATE_KEY@QUEUE_URL[#WAIT_POLLING]

  • A chave de acesso e a chave privada são fornecidas pela AWS.
  • QUEUE_URL corresponde à URL da fila de mensagens, sem o prefixo "https://".
    Exemplo: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name
  • WAIT_POLLING é o tempo (opcional, em segundos) que a leitura aguardará para receber uma mensagem antes de falhar e retornar uma mensagem vazia. Pode assumir um valor entre 1 e 20.
    Exemplo: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name#8

4Características específicas das filas de mensagens

Diferentemente de outras fontes de dados, as mensagens são adicionadas a uma fila de mensagens sem fornecer um identificador (nome, chave, caminho, etc.). O identificador é criado automaticamente pelo SQS. Quando uma mensagem é lida, seu identificador é retornado junto com seus dados; esse identificador é usado posteriormente para excluir a mensagem da fila.

Consequentemente, o SQS não permite verificar a existência de uma mensagem com base em seu identificador, nem selecionar uma mensagem, nem definir um valor padrão ao recuperar uma mensagem.

Observe que, diferentemente do Beanstalk, no qual as leituras ficam bloqueadas até que uma mensagem esteja disponível, as leituras no SQS não são bloqueantes. É possível realizar long polling definindo um tempo limite de até 20 segundos. No entanto, se a chamada de leitura retornar um valor nulo, será necessário tentar novamente.

5Chamadas unificadas

5.1Acesso tipo array

// grava uma mensagem (serializada)
$sqs[''] = $data;

// lê uma mensagem (desserializada)
// retorna um array associativo com as chaves "id" e "data"
$msg = $sqs[''];

// exclusão da mensagem
unset($sqs[$msg['id']]);

// contagem de mensagens em espera
$cnt = count($sqs);

5.2Métodos gerais

// exclui uma mensagem
$sqs->remove($msg['id']);

// exclui todas as mensagens
$sqs->flush();

5.3Gerenciamento de dados serializados complexos

// lê uma mensagem (desserializada)
// retorna um array associativo com as chaves "id" e "data"
$msg = $sqs->get('');

// lê uma mensagem (desserializada) com uma espera máxima de 8 segundos
// retorna um array associativo com as chaves "id" e "data"
$msg = $sqs->get('', options: 8);

// grava uma mensagem (serializada)
$sqs->set('', $msgData);

// grava múltiplas mensagens (serializadas)
$sqs->mSet([
    $user1data,
    $user2data,
    $user3data,
]);

5.4Gerenciamento de dados brutos

// lê uma mensagem (bruta)
// retorna um array associativo com as chaves "id" e "data"
$html = $sqs->read('');

// lê uma mensagem (bruta) com uma espera máxima de 8 segundos
// retorna um array associativo com as chaves "id" e "data"
$html = $sqs->read('', options: 8);

// grava uma mensagem (bruta)
$sqs->write('', $msgData);

// grava múltiplas mensagens (brutas)
$sqs->mWrite([
    $user1data,
    $user2data,
    $user3data,
]);

// grava uma mensagem (bruta) a partir de um arquivo local
$sqs->copyTo('', '/path/to/file');

// grava múltiplas mensagens (brutas) a partir de arquivos locais
$sqs->mCopyTo([
    '/path/to/file1',
    '/path/to/file2',
    '/path/to/file3',
]);