Actualización desde la versión 2 delAWS SDK for PHP - AWS SDK for PHP

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.

Actualización desde la versión 2 delAWS SDK for PHP

En este tema se muestra cómo migrar su código para utilizar la versión 3 de AWS SDK for PHP y las diferencias de la nueva versión frente a la versión 2 del SDK.

nota

El patrón de uso básico del SDK (es decir, $result = $client->operation($params);) no ha cambiado de la versión 2 a la 3, por lo que la migración debería realizarse sin problema.

Introducción

La versión 3 de AWS SDK for PHP representa una mejora importante de las capacidades del SDK, incorpora los comentarios realizados por nuestros clientes a lo largo de dos años, la actualización de nuestras dependencias, la mejora del rendimiento y la adopción de los estándares más recientes de PHP.

¿Qué novedades incluye la versión 3?

A partir de este momento, la versión 3 de AWS SDK for PHP sigue los estándares PSR-4 y PSR-7 y el estándar SemVer.

Otras nuevas características

  • Sistema de middleware para personalizar el comportamiento del cliente del servicio

  • Paginadores flexibles para iterar a través de los resultados paginados

  • Capacidad para consultar los datos de los objetos result y paginator con JMESPath

  • Depuración sencilla mediante la opción de configuración 'debug'

Capa HTTP desacoplada

  • Guzzle 6 se utiliza de forma predeterminada para enviar solicitudes, pero también se admite Guzzle 5.

  • El SDK funcionará en entornos donde cURL no está disponible.

  • También se admiten los controladores HTTP personalizados.

Solicitudes asíncronas

  • Las características como los esperadores y los cargadores multiparte también se pueden utilizar de forma asíncrona.

  • Los flujos de trabajo asíncronos se pueden crear utilizando promesas y corutinas.

  • El rendimiento de las solicitudes simultáneas o en lotes ha mejorado.

¿Cuáles son las diferencias con la versión 2?

Las dependencias del proyecto están actualizadas

En esta versión, las dependencias del SDK han cambiado.

  • El SDK ahora requiere PHP 5.5 y superior. Usamos numerosos generadores dentro del código del SDK.

  • Hemos actualizado el SDK para utilizarloGuzzle 6(o 5), que proporciona la implementación del cliente HTTP subyacente que utiliza el SDK para enviar solicitudes alAWSServicios de . La versión más reciente de Guzzle incluye una serie de mejoras, que engloba solicitudes asíncronas, controladores HTTP intercambiables, conformidad con PSR-7, mejora del rendimiento y mucho más.

  • El paquete PSR-7 de PHP-FIG (psr/http-message) define interfaces para que representen las solicitudes HTTP, las respuestas HTTP, las URL y los flujos. Estas interfaces se utilizan en el SDK y en Guzzle, y permiten operar internamente con otros paquetes compatibles con PSR-7.

  • La implementación de PSR-7 (guzzlehttp/psr7) de Guzzle proporciona una implementación de las interfaces en PSR-7 y varias clases y funciones útiles. Tanto el SDK como Guzzle 6 dependen fuertemente de este paquete.

  • La implementación de Promises/A+ de Guzzle (guzzlehttp/promises) se utiliza tanto en el SDK como en Guzzle para proporcionar interfaces para gestionar solicitudes y corutinas asíncronas. Mientras el controlador HTTP multi-cURL de Guzzle implementa en última instancia el modelo E/S sin bloqueo que permite las solicitudes asíncronas, este paquete ofrece la posibilidad de programar dentro de ese paradigma. ConsultePromesas deAWS SDK for PHPVersión 3para obtener más información.

  • La implementación de PHP de JMESPath (mtdowling/jmespath.php) se utiliza en el SDK para proporcionar los datos que consultan la capacidad de los métodos Aws\Result::search() y Aws\ResultPaginator::search(). ConsulteExpresiones JMESPath enAWS SDK for PHPVersión 3para obtener más información.

Ahora se requieren las opciones Region y Version

Al crear una instancia de un cliente para cualquier servicio, especifique las opciones 'region' y 'version'. En la versión 2 de AWS SDK for PHP, 'version' era totalmente opcional y 'region', a veces. En la versión 3, ambas son siempre necesarias. Al ser explícito sobre ambas opciones, le permite bloquear la versión de la API yAWSRegión en la que estás codificando. Cuando se crean nuevas versiones de API o nuevasAWSLas regiones están disponibles, estará aislado de posibles cambios rotos hasta que esté listo para actualizar su configuración de forma explícita.

nota

Si no le preocupa la versión de la API que está usando, establezca la opción 'version' en 'latest'. Sin embargo, le recomendamos que establezca los números de versión de la API de forma explícita para el código de producción.

No todos los servicios están disponibles en todosAWSRegiones. Para ver una lista de las regiones disponibles, consulte la referencia Regiones y puntos de enlace.

Para los servicios que solo están disponibles a través de un único punto de enlace global (por ejemplo, Amazon Route 53,AWS Identity and Access Managementy Amazon CloudFront), crea instancias de clientes con su región configurada enus-east-1.

importante

El SDK también incluye clientes de varias regiones, que pueden enviar solicitudes a diferentesAWSRegiones basadas en un parámetro (@region) suministrado como parámetro de comando. El parámetro Region que utilizan estos clientes de forma predeterminada se especifica en la opción region suministrada al constructor de clientes.

La creación de instancias del cliente utiliza el constructor

En la versión 3 de AWS SDK for PHP, la forma en la que crea la instancia de un cliente ha cambiado. En lugar de utilizar los métodos factory de la versión 2, aquí puede crear una instancia de un cliente utilizando la palabra clave new.

use Aws\DynamoDb\DynamoDbClient; // Version 2 style $client = DynamoDbClient::factory([ 'region' => 'us-east-2' ]); // Version 3 style $client = new DynamoDbClient([ 'region' => 'us-east-2', 'version' => '2012-08-10' ]);
nota

De todos modos, también se puede crear una instancia de un cliente utilizando el método factory(). Sin embargo, se considera obsoleto.

La configuración del cliente ha cambiado

Las opciones de configuración del cliente en la versión 3 de AWS SDK for PHP han cambiado un poco respecto a la versión 2. Consulte elConfiguración deAWS SDK for PHPVersión 3para ver una descripción de todas las opciones admitidas.

importante

En la versión 3, las opciones 'key' y 'secret' ya no son válidas en el nivel de raíz, pero las puede transferir como parte de la opción 'credentials'. Una razón por la que lo hemos hecho es para evitar que los desarrolladores codifiquen de forma rígida suAWScredenciales en sus proyectos.

El objeto Sdk

La versión 3 de AWS SDK for PHP presenta el objeto Aws\Sdk en sustitución del Aws\Common\Aws. El objeto Sdk actúa como una fábrica de cliente y se utiliza para administrar las opciones de configuración compartidas en varios clientes.

Aunque la clase Aws de la versión 2 del SDK funcionaba como un localizador de servicio (siempre devolvía la misma instancia de un cliente), la clase Sdk de la versión 3 devuelve una nueva instancia de un cliente cada vez que se utiliza.

El objeto Sdk tampoco admite el mismo formato de archivo de configuración de la versión 2 del SDK. Dicho formato de configuración era específico de Guzzle 3 y ya está obsoleto. La configuración se puede simplificar con matrices y se documenta en Uso de la clase Sdk.

Algunos resultados de la API han cambiado

Para ser coherentes en la forma en que el SDK analiza el resultado de una operación de la API, ahora Amazon ElastiCache, Amazon RDS y Amazon Redshift tienen un elemento de encapsulamiento adicional en algunas respuestas de la API.

Por ejemplo, llamar a Amazon RDSDescribeEngineDefaultParametersahora en versión 3 incluye un elemento de encapsulamiento «EngineDefaults». En la versión 2, este elemento no existía.

$client = new Aws\Rds\RdsClient([ 'region' => 'us-west-1', 'version' => '2014-09-01' ]); // Version 2 $result = $client->describeEngineDefaultParameters(); $family = $result['DBParameterGroupFamily']; $marker = $result['Marker']; // Version 3 $result = $client->describeEngineDefaultParameters(); $family = $result['EngineDefaults']['DBParameterGroupFamily']; $marker = $result['EngineDefaults']['Marker'];

Estas son las operaciones afectadas y ahora contienen un elemento de encapsulamiento en la salida del resultado (incluido a continuación entre paréntesis):

  • Amazon ElastiCache

    • AuthorizeCacheSecurityGroupIngress (CacheSecurityGroup)

    • CopySnapshot (Snapshot)

    • CreateCacheCluster (CacheCluster)

    • CreateCacheParameterGroup (CacheParameterGroup)

    • CreateCacheSecurityGroup (CacheSecurityGroup)

    • CreateCacheSubnetGroup (CacheSubnetGroup)

    • CreateReplicationGroup (ReplicationGroup)

    • CreateSnapshot (Snapshot)

    • DeleteCacheCluster (CacheCluster)

    • DeleteReplicationGroup (ReplicationGroup)

    • DeleteSnapshot (Snapshot)

    • DescribeEngineDefaultParameters (EngineDefaults)

    • ModifyCacheCluster (CacheCluster)

    • ModifyCacheSubnetGroup (CacheSubnetGroup)

    • ModifyReplicationGroup (ReplicationGroup)

    • PurchaseReservedCacheNodesOffering (ReservedCacheNode)

    • RebootCacheCluster (CacheCluster)

    • RevokeCacheSecurityGroupIngress (CacheSecurityGroup)

  • Amazon RDS

    • AddSourceIdentifierToSubscription (EventSubscription)

    • AuthorizeDBSecurityGroupIngress (DBSecurityGroup)

    • CopyDBParameterGroup (DBParameterGroup)

    • CopyDBSnapshot (DBSnapshot)

    • CopyOptionGroup (OptionGroup)

    • CreateDBInstance (DBInstance)

    • CreateDBInstanceReadReplica (DBInstance)

    • CreateDBParameterGroup (DBParameterGroup)

    • CreateDBSecurityGroup (DBSecurityGroup)

    • CreateDBSnapshot (DBSnapshot)

    • CreateDBSubnetGroup (DBSubnetGroup)

    • CreateEventSubscription (EventSubscription)

    • CreateOptionGroup (OptionGroup)

    • DeleteDBInstance (DBInstance)

    • DeleteDBSnapshot (DBSnapshot)

    • DeleteEventSubscription (EventSubscription)

    • DescribeEngineDefaultParameters (EngineDefaults)

    • ModifyDBInstance (DBInstance)

    • ModifyDBSubnetGroup (DBSubnetGroup)

    • ModifyEventSubscription (EventSubscription)

    • ModifyOptionGroup (OptionGroup)

    • PromoteReadReplica (DBInstance)

    • PurchaseReservedDBInstancesOffering (ReservedDBInstance)

    • RebootDBInstance (DBInstance)

    • RemoveSourceIdentifierFromSubscription (EventSubscription)

    • RestoreDBInstanceFromDBSnapshot (DBInstance)

    • RestoreDBInstanceToPointInTime (DBInstance)

    • RevokeDBSecurityGroupIngress (DBSecurityGroup)

  • Amazon Redshift

    • AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)

    • AuthorizeSnapshotAccess (Snapshot)

    • CopyClusterSnapshot (Snapshot)

    • CreateCluster (Cluster)

    • CreateClusterParameterGroup (ClusterParameterGroup)

    • CreateClusterSecurityGroup (ClusterSecurityGroup)

    • CreateClusterSnapshot (Snapshot)

    • CreateClusterSubnetGroup (ClusterSubnetGroup)

    • CreateEventSubscription (EventSubscription)

    • CreateHsmClientCertificate (HsmClientCertificate)

    • CreateHsmConfiguration (HsmConfiguration)

    • DeleteCluster (Cluster)

    • DeleteClusterSnapshot (Snapshot)

    • DescribeDefaultClusterParameters (DefaultClusterParameters)

    • DisableSnapshotCopy (Cluster)

    • EnableSnapshotCopy (Cluster)

    • ModifyCluster (Cluster)

    • ModifyClusterSubnetGroup (ClusterSubnetGroup)

    • ModifyEventSubscription (EventSubscription)

    • ModifySnapshotCopyRetentionPeriod (Cluster)

    • PurchaseReservedNodeOffering (ReservedNode)

    • RebootCluster (Cluster)

    • RestoreFromClusterSnapshot (Cluster)

    • RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)

    • RevokeSnapshotAccess (Snapshot)

    • RotateEncryptionKey (Cluster)

Se han eliminado las clases Enum

Hemos eliminado las clases Enum (por ejemplo, Aws\S3\Enum\CannedAcl) de la versión 2 de AWS SDK for PHP. Las clases Enum eran clases concretas dentro de la API pública del SDK que incluían constantes que representan grupos de valores de parámetros válidos. Dado que estos objetos Enum son específicos de las versiones de la API, pueden cambiar con el paso del tiempo, pueden entrar en conflicto con palabras reservadas de PHP y acabar no siendo muy útiles, los hemos eliminado de la versión 3. Esto es compatible con la naturaleza agnóstica de la versión de la API y basada en datos de la versión 3.

En lugar de utilizar valores de objetos Enum, utilice los valores literales directamente (por ejemplo, CannedAcl::PUBLIC_READ'public-read').

Se han eliminado las clases de excepción detalladas

Hemos eliminado las clases de excepción detalladas que existían en los espacios de nombres de cada servicio (por ejemplo, Aws\Rds\Exception\{SpecificError}Exception) por motivos muy similares por los que hemos eliminado los objetos Enum. Las excepciones que lanza un servicio u operación dependen de la versión de la API que se utiliza (pueden cambiar de versión a versión). Además, la lista completa de excepciones que puede lanzar una operación determinada no está disponible, lo que provocaba que las clases de excepción detalladas de la versión 2 fueran incompletas.

Gestione los errores capturando la clase de excepción raíz de cada servicio (por ejemplo, Aws\Rds\Exception\RdsException). Puede utilizar el método getAwsErrorCode() de la excepción para comprobar si hay códigos de error específicos. Desde el punto de vista funcional, es similar a la captura de diferentes clases de excepción pero proporciona dicha función sin añadir sobredimensionamiento al SDK.

Se han eliminado las clases Facade estáticas

En la versión 2 de AWS SDK for PHP, había una característica oculta inspirada por Laravel que permitía llamar a enableFacades() en la clase Aws para habilitar el acceso estático a los distintos clientes de servicios. Esta característica es contraria a las prácticas recomendadas de PHP, por lo que dejamos de documentarla hace más de un año. En la versión 3, esta característica se ha eliminado por completo. Recupere sus objetos de cliente del objeto Aws\Sdk y utilícelos como instancias de objeto, no como clases estáticas.

Los paginadores sustituyen a los iteradores

La versión 2 de AWS SDK for PHP tenía una característica llamada *iteradores*. Estos objetos se utilizaban para la iteración de los resultados paginados. Una de las quejas que recibimos al respecto era que no eran suficientemente flexibles, ya que el iterador solo emitía valores específicos de cada resultado. Si necesitaba otros valores de los resultados, solo se podían recuperar a través de los agentes de escucha.

En la versión 3, los iteradores se han sustituido por Paginadores. Su finalidad es similar, pero los paginadores son más flexibles. Esto se debe a que generaban objetos Result en lugar de valores de una respuesta.

En los siguientes ejemplos se muestra la diferencia entre los paginadores y los iteradores, y se explica cómo recuperar resultados paginados para la operación S3 ListObjects tanto en la versión 2 como en la versión 3.

// Version 2 $objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($objects as $object) { echo $object['Key'] . "\n"; }
// Version 3 $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results as $result) { // You can extract any data that you want from the result. foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } }

Los objetos del paginador tienen un método search() que le permite utilizar expresiones JMESPath para extraer datos más fácilmente del conjunto de resultados.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results->search('Contents[].Key') as $key) { echo $key . "\n"; }
nota

El método getIterator() sigue siendo compatible para que la transición a la versión 3 sea suave, pero le recomendamos que migre su código para utilizar paginadores.

Han cambiado muchas abstracciones de nivel superior

En general, muchas de las abstracciones de nivel superior (objetos auxiliares específicos de servicios, aparte de los clientes) se han mejorado o actualizado. Y algunas se han eliminado.

  • Actualizaciones:
    • Ha cambiado la manera de utilizar la Carga multiparte de Amazon S3. La carga multiparte de Amazon S3 Glacier se ha modificado de forma parecida.

    • La manera en que se crean las URL prefirmadas de Amazon S3 ha cambiado.

    • El espacio de nombres Aws\S3\Sync se ha sustituido por la clase Aws\S3\Transfer. Los métodos S3Client::uploadDirectory() y S3Client::downloadBucket() siguen estando disponibles, pero tienen diferentes opciones. Consulte la documentación deAmazon S3 Transfer Manager conAWS SDK for PHPVersión 3.

    • Aws\S3\Model\ClearBucket y Aws\S3\Model\DeleteObjectsBatch se han sustituido por Aws\S3\BatchDelete y S3Client::deleteMatchingObjects().

    • Las opciones y comportamientos delUso del administrador de sesiones de DynamoDB conAWS SDK for PHPVersión 3han cambiado ligeramente.

    • El espacio de nombres Aws\DynamoDb\Model\BatchRequest se ha sustituido por Aws\DynamoDb\WriteRequestBatch. Consulte la documentación de WriteRequestBatch de DynamoDB.

    • Aws\Ses\SesClient ahora se encarga de la codificación base64 de RawMessage cuando se utiliza la operación SendRawEmail.

  • Eliminaciones:
    • Amazon DynamoDBItem,Attribute, yItemIteratorclases - Anteriormente se habían quedado obsoletas enVersion 2.7.0.

    • Validador de mensajes de Amazon SNS: ahoraun proyecto independiente y ligeroque no requiere que SDK como una dependencia. Sin embargo, este proyecto se incluye en las distribuciones Phar y ZIP del SDK. Encontrará una guía de introducciónen elAWSBlog de desarrollo de PHP.

    • Amazon S3AcpBuilderSe han eliminado de y los objetos relacionados.

Comparación de ejemplos de código de ambas versiones del SDK

Los siguientes ejemplos muestran algunos ejemplos de cómo trabajar con la versión 3 de AWS SDK for PHP puede variar respecto a cómo se trabaja con la versión 2.

Ejemplo: Operación ListObjects de Amazon S3

En la versión 2 del SDK

<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = S3Client::factory([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }

En la versión 3 del SDK

Diferencias clave:

  • Se utiliza new en lugar de factory() para crear instancias del cliente.

  • Las opciones 'version' y 'region' son obligatorias para crear instancias.

<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = new S3Client([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1', 'version' => '2006-03-01' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }

Ejemplo: Creación de instancias de un cliente con configuración global

En la versión 2 del SDK

<?php return array( 'includes' => array('_aws'), 'services' => array( 'default_settings' => array( 'params' => array( 'profile' => 'my_profile', 'region' => 'us-east-1' ) ), 'dynamodb' => array( 'extends' => 'dynamodb', 'params' => array( 'region' => 'us-west-2' ) ), ) );
<?php require '/path/to/vendor/autoload.php'; use Aws\Common\Aws; $aws = Aws::factory('path/to/my/config.php'); $sqs = $aws->get('sqs'); // Note: SQS client will be configured for us-east-1. $dynamodb = $aws->get('dynamodb'); // Note: DynamoDB client will be configured for us-west-2.

En la versión 3 del SDK

Diferencias clave:

  • Se utiliza la clase Aws\Sdk en lugar de Aws\Common\Aws.

  • No hay ningún archivo de configuración. En su lugar, utilice una matriz para configurar.

  • La opción 'version' es obligatoria durante la creación de instancias.

  • Utilice los métodos create<Service>() en lugar de get('<service>').

<?php require '/path/to/vendor/autoload.php'; $sdk = new Aws\Sdk([ 'profile' => 'my_profile', 'region' => 'us-east-1', 'version' => 'latest', 'DynamoDb' => [ 'region' => 'us-west-2', ], ]); $sqs = $sdk->createSqs(); // Note: Amazon SQS client will be configured for us-east-1. $dynamodb = $sdk->createDynamoDb(); // Note: DynamoDB client will be configured for us-west-2.