适用于 PHP 的 AWS 开发工具包
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS SDK for PHP版本 3 的常见问题

在客户端上可以使用哪些方法?

AWS SDK for PHP使用服务描述和动态 magic __call() 方法执行 API 操作。您可以在 Web 服务客户端的 API 文档中找到该客户端提供的所有方法的完整列表。

遇到 cURL SSL 证书错误该怎么办?

如果包含 cURL 和 SSL 的 CA 捆绑包已过期,使用它会发生此问题。更新服务器上的 CA 捆绑包,或直接从 cURL 网站下载最新的 CA 捆绑包,可解决此问题。

默认情况下,AWS SDK for PHP 将使用编译 PHP 时配置的 CA 捆绑包。您可以修改 openssl.cafile PHP .ini 配置设置 (设为磁盘上 CA 文件的路径),更改 PHP 使用的默认 CA 捆绑包。

客户端提供哪些 API 版本?

创建客户端时必须提供 version 选项。在每个客户端的 API 文档页面 ::aws-php-class:<index.html> 上均可找到可用 API 版本的列表。如果您无法加载特定 API 版本,可能需要更新 AWS SDK for PHP 的副本。

您可以为 "version" (版本) 配置值提供 latest 字符串,使用客户端的 API 提供程序可以找到的最新可用 API 版本 (默认的 api_provider 将扫描开发工具包的 src/data 目录,寻找 API 模型)。

警告

我们不建议在生产应用程序中使用 latest,因为拉取包含 API 更新的开发工具包新次要版本会使您的生产应用程序崩溃。

客户端提供哪些区域的版本?

创建客户端时需提供 region 选项,使用字符串值指定。有关可用 AWS 区域和终端节点的列表,请参阅 Amazon Web Services General Reference 中的 AWS 区域和终端节点

// Set the Region to the EU (Frankfurt) Region. $s3 = new Aws\S3\S3Client([ 'region' => 'eu-central-1', 'version' => '2006-03-01' ]);

为什么我无法上传或下载超过 2 GB 的文件?

因为 PHP 的整数类型经过签名,许多平台使用 32 位整数,AWS SDK for PHP 无法在 32 位体系 (此处所指的“体系”包含 CPU、操作系统、Web 服务器和 PHP 二进制文件) 中正确处理超过 2 GB 的文件。这是一个常见的 PHP 问题。对于 Microsoft Windows,只有 PHP 7 的版本支持 64 位整数。

建议的解决方案是使用 64 位 Linux 体系,例如 64 位 Amazon Linux AMI,并安装最新版本的 PHP。

有关更多信息,请参阅 PHP 文件大小:返回值

如何查看已通过线路发送的数据?

您可以在客户端构造函数中使用 debug 选项,获得调试信息,其中包括通过线路发送的数据。如果此选项设为 true,执行的所有命令更改、发送的所有请求、接收到的所有响应以及处理的所有结果均会发送给 STDOUT。其中包括通过线路发送和接收的数据。

$s3Client = new Aws\S3\S3Client([ 'region' => 'us-standard', 'version' => '2006-03-01', 'debug' => true ]);

如何为请求设置任意标题?

您可以将自定义中间件添加到 Aws\HandlerListAws\CommandInterfaceAws\ClientInterface,为服务操作添加任意标题。以下示例说明如何使用 Aws\Middleware::mapRequest 帮助程序方法向特定 Amazon S3PutObject 操作添加 X-Foo-Baz 标头。

有关更多信息,请参阅 mapRequest

如何针对任意请求签名?

您可使用开发工具包的 :aws-php-class: SignatureV4 类 </class-Aws.Signature.SignatureV4.html> 为一个任意 :aws-php-class: PSR-7 请求 </class-Psr.Http.Message.RequestInterface.html>进行签名。

请参阅使用适用于 PHP 的 AWS 开发工具包版本 3 对自定义 Amazon CloudSearch 域请求签名,了解操作方法的完整示例。

如何在发送命令之前修改命令?

您可以将自定义中间件添加到 Aws\HandlerListAws\CommandInterfaceAws\ClientInterface,在发送命令之前修改命令。以下示例展示如何在发送命令之前为其添加自定义命令参数,即添加默认选项。此示例使用 Aws\Middleware::mapCommand 帮助程序方法。

有关更多信息,请参阅 mapCommand

什么是 CredentialsException?

如果您在使用AWS SDK for PHP时看到 Aws\Exception\CredentialsException,这就意味着没有为开发工具包提供任何凭证,也无法在环境中找到凭证。

如果您将一个没有凭证的客户端实例化,则在首次执行服务操作时,开发工具包会尝试寻找凭证。它首先会检查一些特定的环境变量,然后寻找实例配置文件凭证 (仅在经过配置的 Amazon EC2 实例上提供)。如果绝对没有提供或无法找到凭证,将会引发 Aws\Exception\CredentialsException

如果您看到此错误,并且希望使用实例配置文件凭证,则需要确保运行开发工具包的 Amazon EC2 实例配置了适当的 IAM 角色。

如果您看到这种错误,且希望使用实例配置文件凭证,则需要为开发工具包提供适当的凭证。

有关更多信息,请参阅适用于 PHP 的 AWS 开发工具包版本 3 的凭证

AWS SDK for PHP 是否适用于 HHVM?

AWS SDK for PHP目前无法在 HHVM 上运行,在 HHVM 中的生成语义问题得到解决之前,将不会支持 HHVM。

如何禁用 SSL?

将客户端工厂方法的 scheme 参数设为 'http',可禁用 SSL。请务必注意,并不是所有服务都支持 http 访问。请参阅 Amazon Web Services General Reference 中的 AWS 区域和终端节点,了解区域、终端节点和支持的方案的列表。

$client = new Aws\DynamoDb\DynamoDbClient([ 'version' => '2012-08-10', 'region' => 'us-west-2', 'scheme' => 'http' ]);

警告

与 TCP 相比,SSL 要求所有数据均需加密,完成连接握手需要的 TCP 数据包数也更多,因此禁用 SSL 可能会小幅提升性能。但禁用 SSL 后,通过线路发送的所有数据均不会加密。在禁用 SSL 之前,您必须仔细考虑安全隐患,以及通过网络窃取的潜在可能。

出现“解析错误”该怎么办?

PHP 引擎如果遇到不理解的语法,将引发解析错误。如果尝试运行使用其他版本的 PHP 编写的代码,总会遇到这种错误。

如果您遇到解析错误,请检查系统,确保满足开发工具包的适用于 PHP 的 AWS 开发工具包版本 3 的要求和建议

为什么 Amazon S3 客户端会解压缩使用 gzipp 进行压缩的文件?

一些 HTTP 处理程序,包括默认的 Guzzle 6 HTTP 处理程序,在默认情况下会扩大经过压缩的响应正文。您可以将 decode_content HTTP 选项设置为 false,覆盖这一行为。为了向后兼容,此默认值无法改变,但我们建议您在 S3 客户端级别禁用内容解码。

请参阅 decode_content,了解如何禁用内容自动解码的示例。

如何在 Amazon S3 中禁用正文签名?

您可以将命令对象中的 ContentSHA256 参数设置为 Aws\Signature\S3SignatureV4::UNSIGNED_PAYLOAD,禁用正文签名。然后 AWS SDK for PHP 将在规范请求中用它作为 'x-amz-content-sha-256' 标题和正文校验和。

$s3Client = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'us-standard' ]); $params = [ 'Bucket' => 'foo', 'Key' => 'baz', 'ContentSHA256' => Aws\Signature\S3SignatureV4::UNSIGNED_PAYLOAD ]; // Using operation methods creates command implicitly $result = $s3Client->putObject($params); // Using commands explicitly. $command = $s3Client->getCommand('PutObject', $params); $result = $s3Client->execute($command);

如何重试在 AWS SDK for PHP 中处理的方案?

AWS SDK for PHP的 RetryMiddleware 可处理重试行为。对于 5xx HTTP 服务器错误状态代码,开发工具包会重试 500、502、503 和 504。

限制异常也会进行重试,包括 RequestLimitExceededThrottlingProvisionedThroughputExceededExceptionThrottlingExceptionRequestThrottledBandwidthLimitExceeded

AWS SDK for PHP 还在重试方案中将指数延迟与退避和抖动算法集成。而且,所有服务的默认重试行为均配置为 3,只有 Amazon DynamoDB 配置为 10

如何处理具有错误代码的异常?

除了AWS SDK for PHP的自定义 Exception 类,每个 AWS 服务客户端都有其各自的异常类,该类继承自 AwsExceptionAwsException。您可以根据每种方法 Errors 部分列出的特定于 API 的错误,确定要捕获的更多具体错误类型。

Aws\Exception\AwsExceptiongetAwsErrorCode() 可提供错误代码信息。

$sns = new \Aws\Sns\SnsClient([ 'region' => 'us-west-2', 'version' => 'latest', ]); try { $sns->publish([ // parameters ... ]); // Do something } catch (SnsException $e) { switch ($e->getAwsErrorCode()) { case 'EndpointDisabled': case 'NotFound': // Do something break; } }