从的版本 2 升级Amazon适用于 PHP 的开发工具包 - Amazon适用于 PHP 的开发工具包
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

从的版本 2 升级Amazon适用于 PHP 的开发工具包

本主题展示如何迁移代码,以使用的版本 3AmazonSDK for PHP 的开发工具包以及新版本与开发工具包版本 2 的不同之处。

注意

开发工具包的基本使用模式 (即 $result = $client->operation($params);) 从版本 2 到版本 3 并未改变,这样可确保顺利迁移。

Introduction

的版本 3AmazonSDK for PHP 的开发工具包展示出我们为提升开发工具包的功能做出的巨大努力,其中涵盖了客户在两年多时间中提供的反馈,升级了我们的依赖项、提升了性能、

版本 3 中有哪些新功能?

的版本 3AmazonSDK for PHP 遵循PSR-4 和 PSR-7 标准并将遵循SemVer标准后续操作。

其他新增功能包括

  • 用于自定义服务客户端行为的中间件系统

  • 灵活的分页工具,用于迭代分页结果

  • 能够利用 JMESPath结果分页工具对象查询数据

  • 通过 'debug' 配置选项轻松调试

分离的 HTTP 层

  • 默认使用 Guzzle 6 发送请求,但也支持 Guzzle 5。

  • 在 cURL 不可用的环境中开发工具包也可以工作。

  • 也支持自定义 HTTP 处理程序。

异步请求

  • Waiter分段上传工具等功能也可异步使用。

  • 使用 Promise 协同程序可创建异步工作流程。

  • 提升了并发或批处理请求的性能。

与版本 2 有何不同之处?

更新了项目依赖项

开发工具包在此版本中更改了依赖项。

  • 开发工具包现在需要使用 PHP 5.5+。可以自由地在开发工具包代码中使用生成器

  • 我们已经升级了 SDK 以使用Guzzle 6(或 5),提供开发工具包用于向Amazon服务。Guzzle 的最新版本引入了一系列改进,包括异步请求、可交换 HTTP 处理程序、PSR-7 合规性、更出色的性能等。

  • PHP-FIG 的 PSR-7 程序包 (psr/http-message) 定义代表 HTTP 请求、HTTP 响应、URL 和流的接口。这些接口是开发工具包和 Guzzle 通用的,可与兼容 PSR-7 的其他程序包互通。

  • Guzzle 的 PSR-7 实现 (guzzlehttp/psr7) 在 PSR-7 中提供接口实现,还提供若干有用的类和函数。开发工具包和 Guzzle 6 均在很大程度上依赖这个程序包。

  • Guzzle 的 Promises/A+ 实现 (guzzlehttp/promises) 是开发工具包和 Guzzle 通用的,可提供管理异步请求和协同程序的接口。尽管 Guzzle 的多 cURL HTTP 处理程序最终会实现支持异步请求的非阻塞 I/O 模型,但此程序包仍能够在该范例中进行编程。请参阅中的 PromiseAmazonSDK for PHP 版本 3有关更多详细信息。

  • 开发工具包中使用 JMESPath 的 PHP 实施 (mtdowling/jmespath.php),用于提供 Aws\Result::search()Aws\ResultPaginator::search() 方法的数据查询功能。请参阅中的 JMESPath 表达式AmazonSDK for PHP 版本 3有关更多详细信息。

现在要求提供区域和版本选项

如果要将任何服务的客户端实例化,请指定 'region''version' 选项。在的版本 2 中AmazonSDK for PHP,'version'是完全可选的,而且'region'有时是可选的。在版本 3 中,这两个选项都是必需的。明确介绍这两个选项可以锁定 API 版本和Amazon你正在编码的区域。何时创建新的 API 版本或新的 API 版本Amazon区域可用,会将潜在的破坏性更改与您隔离,直到您已做好显式更新配置的准备。

注意

如果您不关心所用的 API 版本,只需将 'version' 选项设为 'latest'。但是,我们建议您针对生产代码显式设置 API 版本号。

并非所有服务都可用Amazon地区。您可以参考区域和终端节点,找到可用区域的列表。

对于仅通过单个全局终端节点提供的服务(例如 Amazon Route 53,Amazon Identity and Access Management,和 Amazon CloudFront),实例化客户端的配置区域设置为us-east-1.

重要

开发工具包中还包含多区域客户端,可以将请求分派到不同的Amazon基于参数的区域 (@region) 作为命令参数提供。这些客户端默认使用的区域是由客户端构造函数提供的 region 选项指定的。

使用构造函数进行客户端实例化

在的版本 3 中AmazonSDK for PHP 的开发工具包,改变了客户端的实例化方式。您只需使用 factory 关键字即可将客户端实例化,而在版本 2 中需使用 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' ]);
注意

仍可使用 factory() 方法将客户端实例化。但这种方法已被弃用。

客户端配置已更改

版本 3 中的客户端配置选项AmazonSDK for PHP 与版本 2 稍有不同。请参阅的配置AmazonSDK for PHP 版本 3页面可查看所有支持的选项的描述。

重要

在版本 3 中,'key''secret' 不再是根级别的有效选项,但可以作为 'credentials' 选项的一部分进行传递。我们做出这种更改的原因是,反对开发人员硬编码Amazon证书进入他们的项目。

Sdk 对象

的版本 3AmazonSDK for PHP 介绍了Aws\Sdk对象作为替代品Aws\Common\Aws. Sdk 对象可作为客户端工厂,用于管理多个客户端的共享配置选项。

开发工具包版本 2 中的 Aws 类像一个服务定位器(它总是会返回客户端的同一实例),而版本 3 中的 Sdk 类在每次使用时都会返回客户端的一个新实例。

Sdk 对象也不支持与开发工具包版本 2 相同的配置文件格式。原来的配置格式是 Guzzle 3 的特定格式,现已过时。可利用基本数组更轻松地进行配置,配置方法在使用 Sdk 类中进行了记录。

更改了一些 API 结果

为了确保开发工具包解析 API 操作结果的方式具有一致性,Amazon ElastiCache、Amazon RDS 和 Amazon Redshift 现已针对一些 API 响应提供额外的包装元素。

例如,调用 Amazon RDSDescribeEngineDefaultParameters版本 3 中的结果会包含包装 “EngineDefaults” 元素。在版本 2 中没有此元素。

$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'];

以下操作会受到影响,在结果输出中会包含包装元素 (在下文的括号中提供):

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

已删除 Enum 类

我们已经删除了Enum类(例如,Aws\S3\Enum\CannedAcl) 在的版本 2 中存在AmazonSDK for PHP。Enum 是开发工具包公共 API 中的具体类,其中包含的常量代表有效参数值的组合。由于这些枚举是特定于某一 API 版本的,是可变的,可能与 PHP 保留关键字冲突,因此并不是非常有用,所以我们在版本 3 中删除了它们,从而支持版本 3 的数据驱动特性,以及与 API 版本无关的特性。

请直接使用文本值,而不是使用 Enum 对象的值(例如,CannedAcl::PUBLIC_READ'public-read')。

已删除精细异常类

我们已基于与删除 Enum 非常类似的原因,删除了每项服务的命名空间中存在的精细异常类(例如 Aws\Rds\Exception\{SpecificError}Exception)。服务或操作引发的异常依赖于所用的 API 版本 (各版本可能有变化)。另外,也无法提供给定操作可引发异常的完整列表,从而使版本 2 的精细异常类不完整。

通过捕获每个服务的根异常类来处理错误(例如 Aws\Rds\Exception\RdsException)。您可以使用异常的 getAwsErrorCode() 方法查看具体的错误代码。它的功能与抓住不同的异常类等效,但不会为开发工具包增加多余内容。

删除了静态 Facade 类

在的版本 2 中AmazonSDK for PHP 的开发工具包,有一项模糊的功能,受到 Laravel 的启发,允许您打电话enableFacades()Aws类以启用对各种服务客户端的静态访问。此功能不符合 PHP 最佳实践,我们在一年多前停止为此功能提供文档。在版本 3 中完全删除了此功能。请从 Aws\Sdk 对象中检索客户端对象,并将其用作对象实例,而不是静态类。

分页工具取代迭代器

版本 2AmazonSDK for PHP 有名为 * 迭代器 * 的功能。这些对象用于迭代分页结果。我们收到反馈,表示它们不够灵活,因为迭代器只会发出每个结果的特定值。如果您需要结果的其他值,只能通过事件侦听器进行检索。

在版本 3 中,分页工具替代了迭代器。它们的用途类似,但分页工具更灵活。这是因为分页工具可生成结果对象,而不是响应值。

以下示例演示了在版本 2 和版本 3 中如何检索 S3 ListObjects 操作的分页结果,从而展示了分页工具与迭代器的不同之处。

// 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"; } }

分页工具对象拥有 search() 方法,支持您使用 JMESPath 表达式更轻松地从结果集中提取数据。

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

我们仍支持 getIterator() 方法,从而确保更顺畅地过渡到版本 3,但我们鼓励您迁移代码,以使用分页工具。

更改了许多高级抽象

总体而言,我们改进或更新了许多高级抽象 (除客户端之外,特定服务的帮助程序对象)。还删除了一些。

比较开发工具包这两个版本的代码示例

以下示例展示版本 3 的一些方法。AmazonSDK for PHP 可能与版本 2 不同。

例如:Amazon S3 ListObjects 操作

开发工具包版本 2

<?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"; }

开发工具包版本 3

主要区别:

  • 使用 new 将客户端实例化,而不是 factory()

  • 在实例化的过程中需要 'version''region' 选项。

<?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"; }

例如:实例化具有全局配置的客户端

开发工具包版本 2

<?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.

开发工具包版本 3

主要区别:

  • 使用 Aws\Sdk 类,而不是 Aws\Common\Aws

  • 没有配置文件。使用一组配置。

  • 在实例化期间需要 'version' 选项。

  • 使用 create<Service>() 方法,而不是 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.