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

AWS SDK for PHP版本 3 的配置

本指南描述了客户端构造函数选项。这些选项可在客户端构造函数中提供,也可以提供给 Aws\Sdk 类。为特定类型客户端提供的选项数组会因您创建的客户端而异。每个客户端的 API 文档中都介绍了这些自定义客户端配置选项。

以下示例显示如何将选项传入 Amazon S3 客户端构造函数。

use Aws\S3\S3Client; $options = [ 'region' => 'us-west-2', 'version' => '2006-03-01', 'signature_version' => 'v4' ]; $s3Client = new S3Client($options);

有关构造客户端的更多信息,请参阅基本用法指南

api_provider

类型

callable

可调用的 PHP,接受类型、服务和版本参数,并返回一组相应的配置数据。类型值可为 apiwaiterpaginator 之一。

默认情况下,开发工具包使用可从开发工具包的 Aws\Api\FileSystemApiProvider 文件夹加载 API 文件的 src/data 实例。

凭证

类型

array|Aws\CacheInterface|Aws\Credentials\CredentialsInterface|bool|callable

传递 Aws\Credentials\CredentialsInterface 对象以使用特定凭证实例。

$credentials = new Aws\Credentials\Credentials('key', 'secret'); $s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'credentials' => $credentials ]);

如果您不提供 credentials 选项,开发工具包将按以下顺序尝试从您的环境中加载凭证:

  1. 环境变量加载凭证。

  2. .ini 文件加载凭证。

  3. IAM 角色加载凭证。

传递 false 以使用空凭证并且不对请求签名。

$s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'credentials' => false ]);

传递可调用的凭证提供程序函数,以使用函数创建凭证。

use Aws\Credentials\CredentialProvider; // Only load credentials from environment variables $provider = CredentialProvider::env(); $s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'credentials' => $provider ]);

传递 Aws\CacheInterface 实例以缓存跨多个流程的默认提供程序链返回的值。

use Aws\DoctrineCacheAdapter; use Aws\S3\S3Client; use Doctrine\Common\Cache\ApcuCache; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'credentials' => new DoctrineCacheAdapter(new ApcuCache), ]);

您可以在适用于 PHP 的 AWS 开发工具包版本 3 的凭证指南中找到有关向客户端提供凭证的更多信息。

注意

加载凭证并在使用时延时验证。

debug

类型

bool|array

输出有关每次传输的调试信息。调试信息包含在准备和通过线路发送事务时事务的每个状态变更的信息。调试输出中还包括有关客户端所使用的特定 HTTP 处理程序的信息 (例如,调试 cURL 输出)。

设置为 true 以便在发送请求时显示调试信息。

$s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'debug' => true ]); // Perform an operation to see the debug output $s3->listBuckets();

您也可以提供包含以下键的关联数组。

logfn (可调用)

通过日志消息调用的函数。默认情况下,会使用 PHP 的 echo 函数。

stream_size (int)

当流的大小大于此数字时,将不记录流数据。设置为 0,以不记录任何流数据。

scrub_auth (bool)

设置为 false,以禁用记录的消息中的身份验证数据清理 (这意味着,您的 AWS 访问密钥 ID 和签名将会传递到 logfn)。

http (布尔)

设置为 false,以禁用低级 HTTP 处理程序的“调试”功能 (如详细 cURL 输出)。

auth_headers (数组)

设置为您要替换的标头映射到要将标头替换为的值的键/值映射。除非将 scrub_auth 设置为 true,否则不会使用这些值。

auth_strings (数组)

设置为要映射到替代项的正则表达式的键/值映射。如果将 scrub_auth 设置为 true,身份验证数据清除器将使用这些值。

$s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'debug' => [ 'logfn' => function ($msg) { echo $msg . "\n"; }, 'stream_size' => 0, 'scrub_auth' => true, 'http' => true, 'auth_headers' => [ 'X-My-Secret-Header' => '[REDACTED]', ], 'auth_strings' => [ '/SuperSecret=[A-Za-z0-9]{20}/i' => 'SuperSecret=[REDACTED]', ], ] ]); // Perform an operation to see the debug output $s3->listBuckets();

注意

调试输出对于在 AWS SDK for PHP 中诊断问题极其有用。在开发工具包中打开问题时,请为隔离的故障案例提供调试输出。

stats

类型

bool|array

将传输统计数据绑定到开发工具包操作返回的错误和结果。

设置为 true 以收集有关所发送请求的传输统计数据。

$s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'stats' => true ]); // Perform an operation $result = $s3->listBuckets(); // Inspect the stats $stats = $result['@metadata']['transferStats'];

您也可以提供包含以下键的关联数组。

retries (布尔)

设置为 true 以对尝试的重试启用报告。默认情况下,会收集并返回重试统计数据。

http (布尔)

设置为 true 以允许从低级别 HTTP 适配器收集统计数据 (例如,在 GuzzleHttpTransferStats 中返回的值)。HTTP 处理程序必须支持 __on_transfer_stats 选项,此设置才会生效。HTTP 统计数据以关联数组的索引数组的形式返回;每个关联数组都包含客户端的 HTTP 处理程序为请求返回的传输统计数据。默认情况下禁用。

如果重试了某个请求,则会返回每个请求的传输统计数据,$result['@metadata']['transferStats']['http'][0] 包含第一个请求的统计数据,$result['@metadata']['transferStats']['http'][1] 包含第二个请求的统计数据,以此类推。

timer (布尔)

设置为 true 以启用命令计时器,可报告某一操作所用的总挂钟时间 (以秒为单位)。默认情况下禁用。

$s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'stats' => [ 'retries' => true, 'timer' => false, 'http' => true, ] ]); // Perform an operation $result = $s3->listBuckets(); // Inspect the HTTP transfer stats $stats = $result['@metadata']['transferStats']['http']; // Inspect the number of retries attempted $stats = $result['@metadata']['transferStats']['retries_attempted']; // Inspect the total backoff delay inserted between retries $stats = $result['@metadata']['transferStats']['total_retry_delay'];

endpoint

类型

string

Web 服务的完整 URI。这是 MediaConvert 等服务所必需的,这些服务使用账户特定的终端节点。对于这些服务,使用 :doc`describeEndpoints`<emc-examples-getendpoint>` 方法请求此终端节点。

仅在连接到自定义终端节点(例如,Amazon S3 的本地版本或本地 Amazon DynamoDB)时需要。

以下是连接到本地 Amazon DynamoDB 的示例:

$client = new Aws\DynamoDb\DynamoDbClient([ 'version' => '2012-08-10', 'region' => 'us-east-1' 'endpoint' => 'http://localhost:8000' ]);

有关可用 AWS 区域和终端节点的列表,请参阅 AWS 区域和终端节点

endpoint_provider

类型

callable

可调用的可选 PHP,接受哈希选项,包括“service”和“region”键。它返回 NULL 或终端节点数据的哈希值,需要其“endpoint”键。

以下示例演示如何创建最简单的终端节点提供程序。

$provider = function (array $params) { if ($params['service'] == 'foo') { return ['endpoint' => $params['region'] . '.example.com']; } // Return null when the provider cannot handle the parameters return null; });

endpoint_discovery

类型

array|Aws\CacheInterface|Aws\EndpointDiscovery\ConfigurationInterface|callable

终端节点发现识别并连接到支持终端节点发现的服务 API 的正确终端节点。对于支持但无需终端节点发现的服务,请在客户端创建期间启用 endpoint_discovery。如果服务不支持终端节点发现,则忽略此配置。

Aws\EndpointDiscovery\ConfigurationInterface

一个可选配置提供程序,可针对服务指定的操作实现自动连接到服务 API 的相应终端节点。

Aws\EndpointDiscovery\Configuration 对象接受两个选项,包括布尔值“enabled”(指示是否启用终端节点发现)和整数“cache_limit”(指示终端节点缓存中键的最大数量)。

对于创建的每个客户端,传递一个 Aws\EndpointDiscovery\Configuration 对象以使用终端节点发现的特定配置。

use Aws\EndpointDiscovery\Configuration; use Aws\S3\S3Client; $enabled = true; $cache_limit = 1000; $config = new Aws\EndpointDiscovery\Configuration ( $enabled, $cache_limit ); $s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-east-2', 'endpoint_discovery' => $config, ]);

传递 Aws\CacheInterface 的实例以缓存终端节点发现在多个流程中返回的值。

use Aws\DoctrineCacheAdapter; use Aws\S3\S3Client; use Doctrine\Common\Cache\ApcuCache; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'endpoint_discovery' => new DoctrineCacheAdapter(new ApcuCache), ]);

将数组传递到终端节点发现。

use Aws\S3\S3Client; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-west-2', 'endpoint_discovery' => [ 'enabled' => true, 'cache_limit' => 1000 ], ]);

handler

类型

callable

一个处理程序,接受命令对象和请求对象,并返回已完成并显示 GuzzleHttp\Promise\PromiseInterface 对象或者已拒绝并显示 Aws\ResultInterface 的承诺 (Aws\Exception\AwsException)。处理程序不接受下一个处理程序,因为它是终端,预期应执行命令。如果未提供任何处理程序,则使用默认的 Guzzle 处理程序。

您可以使用 Aws\MockHandler 返回模拟结果或引发模拟异常。您对结果或异常排队,MockHandler 将按 FIFO 顺序对它们取消排队。

use Aws\Result; use Aws\MockHandler; use Aws\DynamoDb\DynamoDbClient; use Aws\CommandInterface; use Psr\Http\Message\RequestInterface; use Aws\Exception\AwsException; $mock = new MockHandler(); // Return a mocked result $mock->append(new Result(['foo' => 'bar'])); // You can provide a function to invoke; here we throw a mock exception $mock->append(function (CommandInterface $cmd, RequestInterface $req) { return new AwsException('Mock exception', $cmd); }); // Create a client with the mock handler $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'handler' => $mock ]); // Result object response will contain ['foo' => 'bar'] $result = $client->listTables(); // This will throw the exception that was enqueued $client->listTables();

http

类型

array

设置为一组 HTTP 选项,这些选项将应用于开发工具包所创建的 HTTP 请求和传输。

开发工具包支持以下配置选项:

cert

类型

string|array

指定 PEM 格式的客户端证书。

  • 设置为一个字符串,此字符串表示仅到证书文件的路径。

use Aws\S3\S3Client; $client = new S3Client([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => ['cert' => '/path/to/cert.pem'] ]);
  • 设置为包含路径和密码的数组。

use Aws\S3\S3Client; $client = new S3Client([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'cert' => ['/path/to/cert.pem', 'password'] ] ]);

connect_timeout

一个浮点数,描述在尝试连接服务器时要等待的秒数。使用 0 无限期等待 (默认行为)。

use Aws\DynamoDb\DynamoDbClient; // Timeout after attempting to connect for 5 seconds $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'connect_timeout' => 5 ] ]);

debug

类型

bool|resource

指示基础 HTTP 处理程序输出调试信息。不同 HTTP 处理程序提供的调试信息会有所不同。

  • 传递 true 以将调试输出写入 STDOUT。

  • 传递 resource 返回的 fopen,以将调试输出写入特定的 PHP 流资源。

decode_content

类型

bool

指示基础 HTTP 处理程序扩大压缩响应的正文。如果不启用,压缩的响应正文可能用 GuzzleHttp\Psr7\InflateStream 来扩大。

注意

默认情况下,在开发工具包的默认 HTTP 处理程序中会启用内容解码。为了实现向后兼容性,此默认设置无法更改。如果在 Amazon S3 中存储压缩文件,我们建议您在 S3 客户端级别禁用内容解码。

use Aws\S3\S3Client; use GuzzleHttp\Psr7\InflateStream; $client = new S3Client([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => ['decode_content' => false], ]); $result = $client->getObject([ 'Bucket' => 'my-bucket', 'Key' => 'massize_gzipped_file.tgz' ]); $compressedBody = $result['Body']; // This content is still gzipped $inflatedBody = new InflateStream($result['Body']); // This is now readable

delay

类型

int

在发送请求之前要延迟的毫秒数。这通常用于重试请求之前的延迟。

expect

类型

bool|string

此选项将传递至基础 HTTP 处理程序。默认情况下,将在请求的正文超过 1 MB 时设置“Expect: 100-Continue”标头。truefalse 在所有请求上启用或禁用该标头。如果使用整数,则仅其正文超出此设置的请求将使用该标头。用作整数时,如果正文大小未知,则将发送 Expect 标头。

警告

禁用 Expect 标头可防止服务返回身份验证或其他错误。应小心地配置此选项。

progress

类型

callable

定义要在有了传输进度时调用的函数。该函数接受以下参数:

  1. 预计要下载的总字节数。

  2. 到目前为止下载的字节数。

  3. 预计要上传的字节数。

  4. 到目前为止上传的字节数。

use Aws\S3\S3Client; $client = new S3Client([ 'region' => 'us-west-2', 'version' => 'latest' ]); // Apply the http option to a specific command using the "@http" // command parameter $result = $client->getObject([ 'Bucket' => 'my-bucket', 'Key' => 'large.mov', '@http' => [ 'progress' => function ($expectedDl, $dl, $expectedUl, $ul) { printf( "%s of %s downloaded, %s of %s uploaded.\n", $expectedDl, $dl, $expectedUl, $ul ); } ] ]);

proxy

类型

string|array

您可以使用 proxy 选项通过代理连接至 AWS 服务。

  • 为所有类型的 URI 提供用于连接代理的字符串值。该代理字符串值可以包含方案、用户名和密码。例如:"http://username:password@192.168.16.1:10"

  • 提供关联的代理设置数组,其中密钥是 URI 的方案,值是给定 URI 的代理 (您可以为“http”和“https”终端节点提供不同代理)。

use Aws\DynamoDb\DynamoDbClient; // Send requests through a single proxy $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'proxy' => 'http://192.168.16.1:10' ] ]); // Send requests through a different proxy per scheme $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'proxy' => [ 'http' => 'tcp://192.168.16.1:10', 'https' => 'tcp://192.168.16.1:11', ] ] ]);

您可以使用 HTTP_PROXY 环境变量来配置“http”协议特定的代理,使用 HTTPS_PROXY 环境变量来配置“https”特定代理。

sink

类型

resource|string|Psr\Http\Message\StreamInterface

sink 选项控制要将操作的响应数据下载到的位置。

  • 提供 resource 返回的 fopen,以将响应正文下载到 PHP 流。

  • string 值的形式提供文件在磁盘上的路径,以将响应正文下载到磁盘上的特定文件。

  • 提供 Psr\Http\Message\StreamInterface,以将响应正文下载到特定的 PSR 流对象。

注意

默认情况下,开发工具包会将响应正文下载到 PHP 临时流。这意味着,数据会一直保留在内存中,直到正文大小达到 2 MB,此时数据将被写入磁盘上的临时文件中。

synchronous

类型

bool

synchronous 选项会告知基础 HTTP 处理程序,您打算阻止结果。

stream

类型

bool

设置为 true,以告知基础 HTTP 处理程序,您要从 Web 服务流式传输响应的响应正文,而不是预先进行下载。例如,Amazon S3 流包装类中依赖此选项来确保对数据进行流式传输。

timeout

类型

float

一个浮点数,描述请求超时 (以秒为单位)。使用 0 无限期等待 (默认行为)。

use Aws\DynamoDb\DynamoDbClient; // Timeout after 5 seconds $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'timeout' => 5 ] ]);

verify

类型

bool|string

您可以使用 verify http 选项自定义开发工具包的对等 SSL/TLS 证书验证行为。

  • 设置为 true 以启用 SSL/TLS 对等证书验证并使用操作系统提供的默认 CA 捆绑包。

  • 设置为 false 以禁用对等证书验证。(这样不安全!)

  • 设置为一个字符串,以提供 CA 证书捆绑包的路径,从而使用自定义 CA 捆绑包启用验证。

如果找不到系统的 CA 捆绑包并且收到错误,请向开发工具包提供 CA 捆绑包的路径。如果您不需要特定的 CA 捆绑包,Mozilla 提供了可从此处下载的常用 CA 捆绑包(由 cURL 的维护者维护)。一旦您的磁盘中具有 CA 捆绑包,则可将 openssl.cafile PHP.ini 设置为指向该文件的路径,从而忽略 verify 请求选项。您可以在 cURL 网站上了解有关 SSL 证书的更多详细信息。

use Aws\DynamoDb\DynamoDbClient; // Use a custom CA bundle $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'verify' => '/path/to/my/cert.pem' ] ]); // Disable SSL/TLS verification $client = new DynamoDbClient([ 'region' => 'us-west-2', 'version' => 'latest', 'http' => [ 'verify' => false ] ]);

http_handler

类型

callable

http_handler 选项用于将开发工具包与其他 HTTP 客户端集成。http_handler 选项是一个函数,接受 Psr\Http\Message\RequestInterface 对象和一组应用于命令的 http 选项,并返回已完成并显示 GuzzleHttp\Promise\PromiseInterface 对象或已拒绝并显示以下一组异常数据的 Psr\Http\Message\ResponseInterface 对象:

  • exception - (\Exception) 遇到的异常。

  • response - (Psr\Http\Message\ResponseInterface) 收到的响应 (如果有)。

  • connection_error - (布尔) 设置为 true 以将错误标记为连接错误。将此值设置为 true 还允许开发工具包自动重试该操作 (如果需要)。

开发工具包通过用 http_handler 对象包装所提供的 handler 来将给定的 http_handler 转换为正常 Aws\WrappedHttpHandler 选项。

注意

此选项将取代所提供的任何 handler 选项。

profile

类型

string

使您能够指定在根据主目录中的 AWS 凭证文件创建凭证时使用哪个配置文件。此设置将覆盖 AWS_PROFILE 环境变量。

注意

指定“profile”将导致“credentials”密钥被忽略。

// Use the "production" profile from your credentials file $ec2 = new Aws\Ec2\Ec2Client([ 'version' => '2014-10-01', 'region' => 'us-west-2', 'profile' => 'production' ]);

有关配置凭证和 .ini 文件格式的更多信息,请参阅适用于 PHP 的 AWS 开发工具包版本 3 的凭证

区域

类型

string

必需

true

要连接的 AWS 区域。有关可用区域的列表,请参阅 AWS 区域和终端节点

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

retries

类型

int

默认值

int(3)

配置对客户端允许的最大重试次数。传递 0 以禁用重试。

下面的示例将对 Amazon DynamoDB 客户端禁用重试。

// Disable retries by setting "retries" to 0 $client = new Aws\DynamoDb\DynamoDbClient([ 'version' => '2012-08-10', 'region' => 'us-west-2', 'retries' => 0 ]);

scheme

类型

string

默认值

string(5) "https"

连接时要使用的 URI 方案。默认情况下,开发工具包会使用“https”终端节点 (即使用 SSL/TLS 连接)。您可以通过将 scheme 设置为“http”尝试通过未加密的“http”终端节点来连接服务。

$s3 = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'us-west-2', 'scheme' => 'http' ]);

有关终端节点列表以及服务是否支持 http 方案,请参阅 AWS 区域和终端节点

service

类型

string

必需

true

要使用的服务的名称。在使用开发工具包提供的客户端时,默认情况下会提供此值 (即 Aws\S3\S3Client)。在测试开发工具包中尚未发布但磁盘中已提供的服务时,此选项很有用。

signature_provider

类型

callable

可调用,能接受签名版本名称 (例如,v4)、服务名称和 AWS 区域,如果提供程序能够为给定参数创建签署人,则会返回 Aws\Signature\SignatureInterface 对象或 NULL。此提供程序用于创建供客户端使用的签署人。

开发工具包在 Aws\Signature\SignatureProvider 类中提供了可用于创建自定义签名提供程序的不同函数。

signature_version

类型

string

一个字符串,表示要用于服务的自定义签名版本 (例如 v4 等)。如果需要,每个操作签名版本均可能覆盖此请求的签名版本。

以下示例演示如何配置 Amazon S3 客户端以使用签名版本 4

// Set a preferred signature version $s3 = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'us-west-2', 'signature_version' => 'v4' ]);

注意

客户端使用的 signature_provider 必须能够创建您提供的 signature_version 选项。开发工具包使用的默认 signature_provider 可为“v4”和“匿名”签名版本创建签名对象。

ua_append

类型

string|string[]

默认值

[]

添加到传递给 HTTP 处理程序的用户代理字符串的字符串或字符串数组。

验证

类型

bool|array

默认值

bool(true)

设置为 false 以禁用客户端参数验证。您可能会发现,关闭验证会略微提高性能,但区别可以忽略不计。

// Disable client-side validation $s3 = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'eu-west-1', 'validate' => false ]);

设置为关联的验证选项数组,以启用特定的验证约束:

  • required - 验证必需的参数是否存在 (默认启用)。

  • min - 验证值的最小长度 (默认启用)。

  • max - 验证值的最大长度。

  • pattern - 验证值是否与正则表达式匹配。

// Validate only that required values are present $s3 = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'eu-west-1', 'validate' => ['required' => true] ]);

version

类型

string

必需

true

要使用的 Web 服务的版本 (例如,2006-03-01)。

“version”配置值是必需的。指定版本约束可确保对服务所做的重大更改不会影响您的代码。例如,在使用 Amazon S3 时,您可以将您的 API 版本锁定为 2006-03-01

$s3 = new Aws\S3\S3Client([ 'version' => '2006-03-01', 'region' => 'us-east-1' ]);

在每个客户端的 API 文档页面中均可找到可用 API 版本的列表。如果您无法加载特定 API 版本,则可能需要更新开发工具包副本。

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

// Use the latest version available $s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]);

警告

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