AWS SDK for PHP バージョン 3 での JMESPath 式 - AWS SDK for PHP
結果からのデータの抽出ページネーターからのデータの抽出

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS SDK for PHP バージョン 3 での JMESPath 式

JMESPath により JSON ドキュメントから要素を抽出する方法を宣言により指定できます。AWS SDK for PHP は AWS SDK for PHP バージョン 3 でのページネーターや AWS SDK for PHP バージョン 3 でのウェーターなど、一部の高レベルの抽象化を行うために jmespath.php に依存しますが、Aws\ResultInterface や Aws\ResultPaginator を検索する JMESPath も公開します。

オンラインの JMESPath の例を試すことにより、ブラウザで JMESPath を実際に操作してみることができます。言語の詳細 (使用可能な式と関数など) については、JMESPath の仕様を参照してください。

AWS CLI は JMESPath をサポートしています。CLI 出力用に記述した式は、AWS SDK for PHP 用に記述した式と 100 パーセントの互換性があります。

結果からのデータの抽出

Aws\ResultInterface インターフェイスには、JMESPath 式に基づいて結果モデルからデータを抽出する search($expression) メソッドがあります。結果オブジェクトからデータをクエリする JMESPath 式を使用すると、共通条件付きコードを削除し、抽出対象データを簡潔に表現できます。

この機能を示すため、最初に以下のデフォルトの JSON 出力で開始します。この出力では、2 つの Amazon Elastic Block Store (Amazon EBS) ボリュームが個別の 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"
        }
    }
}

最初に、次のコマンドで、ボリュームリストの最初のボリュームのみを取得できます。

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

ここで、wildcard-index 式 [*] を使用して、リスト全体を反復的に処理し、3 つの要素を抽出します。 VolumeId は ID に、AvailabilityZone は AZ に変更され、Size は Size のままです。multi-hash 式を wildcard-index 式の後ろに配置してこれらの要素を抽出して名前を変更できます。

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

これにより、PHP データの配列は次のようになります。

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

multi-hash 表記では、key1.key2[0].key3 など連鎖キーを使用して、構造内で深く入れ子になった要素を抽出することもできます。以下の例では、単純に Attachments[0].InstanceId に対して InstanceId キーのエイリアスを作成して、これを示します。(ほとんどの場合、JMESPath 式は空白を無視します)。

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

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

前の式では、次のデータを出力します。

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

multi-list 式: [key1, key2] で複数の要素をフィルタリングすることもできます。これにより、フィルタリングされたすべての属性が、型に関係なく、オブジェクトごとに 1 つの順序付きリスト形式になります。

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

前の検索を実行すると、次のデータが生成されます。

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

特定のフィールドの値によって結果をフィルタリングする、filter 式を使用します。次のクエリの例では、us-west-2a アベイラビリティーゾーンのボリュームのみを出力します。

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

JMESPath は関数式もサポートしています。例えば、上記と同じクエリを実行する場合、すべてのボリュームを取得する代わりに、「us-」で始まる AWS リージョン内のボリュームを取得します。次の式では、starts_with 関数を使用して、文字列リテラル us- を渡します。この関数の結果は JSON のリテラル値 true と比較されます。フィルタ処理を通じて true を返したフィルタ述語の結果のみを渡します。

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

ページネーターからのデータの抽出

AWS SDK for PHP バージョン 3 でのページネーターガイドにあるように、Aws\ResultPaginator オブジェクトではページング可能な API オペレーションの結果を出力します。AWS SDK for PHP により Aws\ResultPaginator オブジェクトからフィルタリングされたデータを抽出し、それを繰り返すことができます。特に JMESPath 式の結果がマップ関数であるイテレーターに flat-map を実装します。

たとえば、1 MB より大きなバケットにあるオブジェクトのみを出力する iterator を作成する場合です。これを実現するには、最初に ListObjects ページネーターを作成し、search() 関数をページネーターに適用します。さらにページ分割されたデータにフラットマップイテレーターを作成します。

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