Extração de dados dos resultados Extração de dados dos paginadores

Expressões do JMESPath no AWS SDK for PHP versão 3

O JMESPath permite especificar de forma declarativa como extrair elementos de um documento JSON. O AWS SDK for PHP tem uma dependência do jmespath.php para potencializar algumas das abstrações de alto nível, como Paginadores no AWS SDK for PHP Versão 3 e Waiters no AWS SDK for PHP Versão 3, mas também expõe o JMESPath pesquisando em Aws\ResultInterface e Aws\ResultPaginator.

Você pode experimentar o JMESPath no navegador, testando os Exemplos do JMESPath online. Saiba mais sobre a linguagem, inclusive as expressões e funções disponíveis, na Especificação do JMESPath.

A AWS CLI é compatível com o JMESPath. As expressões que você escreve para saída da CLI são 100% compatíveis com expressões escritas para o AWS SDK for PHP.

Extração de dados dos resultados

A interface Aws\ResultInterface tem um método search($expression) que extrai dados de um modelo de resultados com base em uma expressão do JMESPath. O uso de expressões do JMESPath para consultar dados de um objeto de resultado pode ajudar a remover código condicional boilerplate e expressar de forma muito mais concisa os dados que estão sendo extraídos.

Para demonstrar como funciona, começaremos com a saída JSON padrão abaixo, que descreve dois volumes do Amazon Elastic Block Store (Amazon EBS) anexados a instâncias separadas do Amazon EC2.


$result = $ec2Client->describeVolumes();
// Output the result data as JSON (just so we can clearly visualize it)
echo json_encode($result->toArray(), JSON_PRETTY_PRINT);


{
    "Volumes": [
        {
            "AvailabilityZone": "us-west-2a",
            "Attachments": [
                {
                    "AttachTime": "2013-09-17T00:55:03.000Z",
                    "InstanceId": "i-a071c394",
                    "VolumeId": "vol-e11a5288",
                    "State": "attached",
                    "DeleteOnTermination": true,
                    "Device": "/dev/sda1"
                }
            ],
            "VolumeType": "standard",
            "VolumeId": "vol-e11a5288",
            "State": "in-use",
            "SnapshotId": "snap-f23ec1c8",
            "CreateTime": "2013-09-17T00:55:03.000Z",
            "Size": 30
        },
        {
            "AvailabilityZone": "us-west-2a",
            "Attachments": [
                {
                    "AttachTime": "2013-09-18T20:26:16.000Z",
                    "InstanceId": "i-4b41a37c",
                    "VolumeId": "vol-2e410a47",
                    "State": "attached",
                    "DeleteOnTermination": true,
                    "Device": "/dev/sda1"
                }
            ],
            "VolumeType": "standard",
            "VolumeId": "vol-2e410a47",
            "State": "in-use",
            "SnapshotId": "snap-708e8348",
            "CreateTime": "2013-09-18T20:26:15.000Z",
            "Size": 8
        }
    ],
    "@metadata": {
        "statusCode": 200,
        "effectiveUri": "https:\/\/ec2.us-west-2.amazonaws.com",
        "headers": {
            "content-type": "text\/xml;charset=UTF-8",
            "transfer-encoding": "chunked",
            "vary": "Accept-Encoding",
            "date": "Wed, 06 May 2015 18:01:14 GMT",
            "server": "AmazonEC2"
        }
    }
}

Primeiro, podemos recuperar somente o primeiro volume da lista Volumes com o seguinte comando.


$firstVolume = $result->search('Volumes[0]');

Agora, usamos a expressão wildcard-index [*] para iterar sobre a lista inteira e também para extrair e renomear três elementos: VolumeId é renomeado para ID, AvailabilityZone é renomeada para AZ e Size permanece Size. Podemos extrair e renomear esses elementos usando uma expressão multi-hash colocada depois da expressão wildcard-index.


$data = $result->search('Volumes[*].{ID: VolumeId, AZ: AvailabilityZone, Size: Size}');

Isso fornece uma matriz de dados do PHP, como a seguinte:


array(2) {
  [0] =>
  array(3) {
    'AZ' =>
    string(10) "us-west-2a"
    'ID' =>
    string(12) "vol-e11a5288"
    'Size' =>
    int(30)
  }
  [1] =>
  array(3) {
    'AZ' =>
    string(10) "us-west-2a"
    'ID' =>
    string(12) "vol-2e410a47"
    'Size' =>
    int(8)
  }
}

Na notação multi-hash, também é possível usar chaves encadeadas, como key1.key2[0].key3 para extrair elementos altamente aninhados na estrutura. O exemplo a seguir demonstra isso com a chave Attachments[0].InstanceId, com o alias simples InstanceId. (Na maioria dos casos, as expressões do JMESPath ignoram espaços em branco.)


$expr = 'Volumes[*].{ID: VolumeId,
                     InstanceId: Attachments[0].InstanceId,
                     AZ: AvailabilityZone,
                     Size: Size}';

$data = $result->search($expr);
var_dump($data);

A saída da expressão anterior conterá os seguintes dados:


array(2) {
  [0] =>
  array(4) {
    'ID' =>
    string(12) "vol-e11a5288"
    'InstanceId' =>
    string(10) "i-a071c394"
    'AZ' =>
    string(10) "us-west-2a"
    'Size' =>
    int(30)
  }
  [1] =>
  array(4) {
    'ID' =>
    string(12) "vol-2e410a47"
    'InstanceId' =>
    string(10) "i-4b41a37c"
    'AZ' =>
    string(10) "us-west-2a"
    'Size' =>
    int(8)
  }
}

Você também pode filtrar vários elementos com a expressão multi-list: [key1, key2]. Isso formata todos os atributos filtrados em uma única lista ordenada por objeto, independentemente do tipo.


$expr = 'Volumes[*].[VolumeId, Attachments[0].InstanceId, AvailabilityZone, Size]';
$data = $result->search($expr);
var_dump($data);

A execução da pesquisa anterior produz os seguintes dados:


array(2) {
  [0] =>
  array(4) {
    [0] =>
    string(12) "vol-e11a5288"
    [1] =>
    string(10) "i-a071c394"
    [2] =>
    string(10) "us-west-2a"
    [3] =>
    int(30)
  }
  [1] =>
  array(4) {
    [0] =>
    string(12) "vol-2e410a47"
    [1] =>
    string(10) "i-4b41a37c"
    [2] =>
    string(10) "us-west-2a"
    [3] =>
    int(8)
  }
}

Use uma expressão filter para filtrar os resultados de um campo específico. A consulta de exemplo a seguir produz apenas volumes na zona de disponibilidade us-west-2a.


$data = $result->search("Volumes[?AvailabilityZone ## 'us-west-2a']");

O JMESPath também oferece suporte a expressões de função. Vamos supor que você queira executar a mesma consulta acima, mas recuperar todos os volumes que estão em uma região da AWS que começa com "us-". A expressão a seguir usa a função starts_with, passando uma sequência literal de us-. O resultado dessa função é comparado com o valor literal true do JSON passando apenas os resultados do predicado do filtro que retornou true por meio da projeção do filtro.


$data = $result->search('Volumes[?starts_with(AvailabilityZone, 'us-') ## `true`]');

Extração de dados dos paginadores

Como você sabe, no guia Paginadores no AWS SDK for PHP Versão 3, os objetos Aws\ResultPaginator são usados para gerar resultados de uma operação de API paginável. O AWS SDK for PHP permite que você extraia e itere em dados filtrados de objetos Aws\ResultPaginator, essencialmente implementando um mapa plano sobre o iterador em que o resultado de uma expressão do JMESPath é a função do mapa.

Vamos supor que você queira criar um iterator que produza apenas objetos de um bucket maior que um MB. Isso pode ser obtido criando um paginador ListObjects primeiro e, em seguida, aplicando uma função search() ao paginador, criando um iterador com mapa plano sobre os dados paginados.


$result = $s3Client->getPaginator('ListObjects', ['Bucket' => 't1234']);
$filtered = $result->search('Contents[?Size > `1048576`]');

// The result yielded as $data will be each individual match from
// Contents in which the Size attribute is > 1048576
foreach ($filtered as $data) {
    var_dump($data);
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Waiters

Use a extensão AWS CRT