Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Expresiones JMESPath en el versión 3 de AWS SDK for PHP

JMESPath permite especificar de forma declarativa el modo de extraer elementos de un documento JSON. ElAWS SDK for PHP depende de jmespath.php para potenciar algunas de las abstracciones de alto nivel como paginadores en la versión 3 de AWS SDK for PHP y los esperadores en la versión 3 de AWS SDK for PHP, pero también expone la búsqueda de JMESPath en Aws\ResultInterface y Aws\ResultPaginator.

Para practicar con JMESPath en su navegador puede probar los ejemplos de JMESPath online. Para saber más sobre este lenguaje, incluidas las expresiones y funciones disponibles, consulte la especificación de JMESPath.

La AWS CLI es compatible con JMESPath. Las expresiones que escribe para la salida de la CLI son completamente compatibles con las expresiones escritas para AWS SDK for PHP.

Extraer datos de los resultados

La interfaz Aws\ResultInterface tiene un método search($expression) que extrae datos desde un modelo de resultado en una expresión JMESPath. El uso de expresiones JMESPath para consultar los datos de un objeto de resultado puede ayudar a eliminar el código condicional reutilizable y expresar con mayor concisión los datos que se extraen.

Para demostrar cómo funciona, comenzaremos con el valor de salida JSON predeterminado que se muestra a continuación, que describe dos volúmenes de Amazon Elastic Block Store (Amazon EBS) adjuntos a instancias de Amazon EC2 independientes.

$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"
        }
    }
}

En primer lugar, podemos obtener solo el primer volumen de la lista Volumes con el comando siguiente.

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

Ahora, utilizamos la expresión wildcard-index [*] para iterar por toda la lista, extrayendo y cambiando el nombre de tres elementos: VolumeId cambia a ID, AvailabilityZone cambia a AZy Size se mantiene como Size. Podemos extraer y cambiar el nombre de estos elementos mediante una expresión multi-hash situada después de la expresión wildcard-index.

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

Esto resulta en una matriz de datos PHP como la siguiente:

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)
  }
}

En la notación multi-hash también puede utilizar claves encadenadas como key1.key2[0].key3 para extraer los elementos profundamente anidados en la estructura. El ejemplo siguiente lo ilustra con la clave Attachments[0].InstanceId a la que se aplica simplemente el alias InstanceId. (En la mayoría de los casos, las expresiones JMESPath no tendrán en cuenta los espacios).

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

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

La expresión anterior devolverá los datos siguientes:

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)
  }
}

También puede filtrar varios elementos con la expresión multi-list: [key1, key2]. Con ella todos los atributos filtrados adoptan la forma de una única lista ordenada por cada objeto, independientemente de su tipo.

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

La ejecución de la búsqueda anterior produce los datos siguientes:

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)
  }
}

Utilice una expresión filter para filtrar los resultados por el valor de un campo específico. El siguiente ejemplo de consulta devuelve únicamente los volúmenes de la zona de disponibilidad us-west-2a.

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

JMESPath también admite expresiones de función. Supongamos que desea ejecutar la misma consulta que en el ejemplo anterior, pero obteniendo todos los volúmenes de las regiones de AWS que comiencen por "us-". La expresión siguiente utiliza la función starts_with y le pasa la cadena literal us-. El resultado de esta función se compara entonces con el valor literal JSON true, pasando solo los resultados del predicado de filtro que hayan devuelto true en la proyección del filtro.

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

Extraer datos de paginadores

Como se indicó en el apartado Paginadores de la guía de la versión 3 de, AWS SDK for PHP, los objetos Aws\ResultPaginator objects se utilizan para obtener resultados de una operación paginable de la API. AWS SDK for PHP permite extraer e iterar por datos filtrados de los objetos Aws\ResultPaginator, básicamente mediante la implementación de un mapa plano del iterador en el que el resultado de una expresión JMESPath es la función de mapa.

Supongamos que desea crear un objeto iterator que solo devuelva los objetos de un bucket con un tamaño superior a 1 MB. Esto puede conseguirse creando primero un paginador ListObjects y aplicándole entonces una función search() para crear un iterador de mapa plano para los datos 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);
}