Amazon SDK for PHP 版本 3 的配置

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

请注意，一些配置选项将进行检查并根据环境变量或 Amazon 配置文件来使用默认值。默认情况下，所检查的配置文件是位于主目录中的 .aws/config，通常为 ~/.aws/config。但是，您可以使用环境变量 AWS_CONFIG_FILE 来设置默认配置文件所在的位置。例如，如果您使用 open_basedir 来限制对特定目录的文件访问，这可能特别有用。

有关共享 Amazon config 文件和 credentials 文件的位置和格式的更多信息，请参阅 Amazon SDK 和工具参考指南中的配置。

有关可以在 Amazon 配置文件中设置或作为环境变量来设置的所有全局配置设置的详细信息，请参阅 Amazon SDK 和工具参考指南中的配置和身份验证设置参考。

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

use Aws\S3\S3Client;

$options = [
    'region'            => 'us-west-2',
    'version'           => '2006-03-01',
    'signature_version' => 'v4'
];

$s3Client = new S3Client($options);

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

api_provider

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

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

凭证

传递 Aws\Credentials\CredentialsInterface 对象以使用特定凭证实例。以下内容指定应使用 IAM Identity Center 凭证提供程序。此提供程序也称为 SSO 凭证提供程序。

$credentials = Aws\Credentials\CredentialProvider::sso('profile default');

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

如果使用命名配置文件，请在上一个示例中用配置文件名称来替换“default”。要了解有关设置命名配置文件的更多信息，请参阅 Amazon SDK 和工具参考指南中的共享 config 和 credentials 文件。

如果没有指定待使用的凭证提供程序，而是依赖凭证提供程序链，则由于身份验证失败而产生的错误消息通常是通用的。其由正在检查有效凭证的源列表中的最后一个提供程序生成，该提供程序可能不是您尝试使用的提供程序。当您指定要使用哪个凭证提供程序时，任何由此产生的错误消息都更加有用和相关，因为其仅来自该提供程序。要详细了解检查凭证的来源链，请参阅 Amazon SDK 和工具参考指南中的凭证提供程序链。

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

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

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

use Aws\Credentials\CredentialProvider;

// Only load credentials from environment variables
$provider = CredentialProvider::env();

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

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

use Aws\Credentials\CredentialProvider;
use Aws\PsrCacheAdapter;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;


$cache = new PsrCacheAdapter(new FilesystemAdapter);
$provider = CredentialProvider::defaultProvider();
$cachedProvider = CredentialProvider::cache($provider, $cache);

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

您可以在 Amazon SDK for PHP 版本 3 的凭证指南中找到有关向客户端提供凭证的更多信息。

调试

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

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

$s3 = new Aws\S3\S3Client([
    'region'  => 'us-west-2',
    'debug'   => true
]);

// Perform an operation to see the debug output
$s3->listBuckets();

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

$s3 = new Aws\S3\S3Client([
    '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();

stats

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

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

$s3 = new Aws\S3\S3Client([
    'region'  => 'us-west-2',
    'stats'   => true
]);

// Perform an operation
$result = $s3->listBuckets();
// Inspect the stats
$stats = $result['@metadata']['transferStats'];

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

$s3 = new Aws\S3\S3Client([
    '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'];

端点

Web 服务的完整 URI。这是 AWS Elemental MediaConvert 等服务所必需的，这些服务使用账户特定的端点。对于这些服务，请使用 describeEndpoints 方法请求此端点。

仅在连接到自定义端点（例如，Amazon S3 的本地版本或本地 Amazon DynamoDB）时需要。

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

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

有关可用 Amazon 区域和端点的列表，请参阅 Amazon 区域和端点。

endpoint_provider

EndpointProviderV2 或 PHP 的可调用实例，它接受选项的哈希值，包括 “服务” 和 “区域” 密钥。它会返回 NULL 或端点数据的哈希值，其中“端点”键是必需的。

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

$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

端点发现识别并连接到支持端点发现的服务 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([
    'region' => 'us-east-2',
    'endpoint_discovery' => $config,

]);

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

use Aws\DoctrineCacheAdapter;
use Aws\S3\S3Client;
use Doctrine\Common\Cache\ApcuCache;

$s3 = new S3Client([
    'region'      => 'us-west-2',
    'endpoint_discovery' => new DoctrineCacheAdapter(new ApcuCache),
]);

将数组传递到端点发现。

use Aws\S3\S3Client;

$s3 = new S3Client([
    'region'      => 'us-west-2',
    'endpoint_discovery' => [
        'enabled' => true,
        'cache_limit' => 1000
    ],
]);

handler

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

您可以使用 Aws\MockHandler 返回模拟结果或引发模拟异常。您将结果或异常入队，然后将按照 FIFO 顺序 MockHandler 将它们出队。

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-east-1',
    'handler' => $mock
]);

// Result object response will contain ['foo' => 'bar']
$result = $client->listTables();

// This will throw the exception that was enqueued
$client->listTables();

http

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

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

cert

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

use Aws\S3\S3Client;

$client = new S3Client([
    'region'  => 'us-west-2',
    'http'    => ['cert' => '/path/to/cert.pem']
]);

use Aws\S3\S3Client;

$client = new S3Client([
    'region'  => 'us-west-2',
    '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',
    'http'    => [
        'connect_timeout' => 5
    ]
]);

调试

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

decode_content

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

use Aws\S3\S3Client;
use GuzzleHttp\Psr7\InflateStream;

$client = new S3Client([
    'region'  => 'us-west-2',
    '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

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

expect

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

进度

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

use Aws\S3\S3Client;

$client = new S3Client([
    'region'  => 'us-west-2'
]);

// 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

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

use Aws\DynamoDb\DynamoDbClient;

// Send requests through a single proxy
$client = new DynamoDbClient([
    'region'  => 'us-west-2',
    'http'    => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

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

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

sink

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

synchronous

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

流

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

timeout

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

use Aws\DynamoDb\DynamoDbClient;

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

确认

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

如果找不到系统的 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',
    'http'    => [
        'verify' => '/path/to/my/cert.pem'
    ]
]);

// Disable SSL/TLS verification
$client = new DynamoDbClient([
    'region'  => 'us-west-2',
    'http'    => [
        'verify' => false
    ]
]);

http_handler

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

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

默认情况下，开发工具包使用 Guzzle 作为其 HTTP 处理程序。您可以在这里提供不同的 HTTP 处理程序，或者为 Guzzle 客户端提供您自己的自定义选项。

设置 TLS 版本

一种使用情形是使用 Curl 来设置 Guzzle 使用的 TLS 版本，前提是您的环境中已安装了 Curl。请注意 Curl 对于所支持的 TLS 版本的版本约束。默认情况下会使用最新版本。如果明确设置了 TLS 版本，但是远程服务器不支持此版本，则会产生错误，而不是使用更低的 TLS 版本。

您可以通过将 debug 客户端选项设置为 true 并检查 SSL 连接输出，确定用于给定客户端操作的 TLS 版本。此行看起来类似于：SSL connection using TLSv1.2

设置 Guzzle 6 使用 TLS 1.2 的示例：

use Aws\DynamoDb\DynamoDbClient;
use Aws\Handler\GuzzleV6\GuzzleHandler;
use GuzzleHttp\Client;

$handler = new GuzzleHandler(
    new Client([
        'curl' => [
            CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2
        ]
    ])
);

$client = new DynamoDbClient([
    'region'  => 'us-west-2',
    'http_handler' => $handler
]);

配置文件

“配置文件”选项指定从主目录中的 Amazon 凭证文件（通常为 ~/.aws/credentials）创建凭证时要使用的配置文件。此设置将覆盖 AWS_PROFILE 环境变量。

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

有关配置凭证和 .ini 文件格式的更多信息，请参阅 Amazon SDK for PHP 版本 3 的凭证。

region

要连接的 Amazon 区域。有关可用区域的列表，请参阅 Amazon 区域和端点。

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

重试

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

三种重试模式是：

重试的配置由每个请求使用的模式和最大尝试次次数组成。配置可以按以下优先顺序在几个不同的位置进行设置。

优先顺序

重试配置的优先级顺序如下所示（1 覆盖 2-3，等等）：

环境变量

共享的配置文件密钥

客户端配置

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

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

以下示例传入一个整数，这将默认为 legacy 模式并使用传入整数作为重试次数

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

用于重试配置的 Aws\Retry\Configuration 对象。

use Aws\EndpointDiscovery\Configuration;
use Aws\S3\S3Client;

$enabled = true;
$cache_limit = 1000;

$config = new Aws\Retry\Configuration('adaptive', 10);

$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-2',
    'retries' => $config,
]);

此示例传入一个用于重试配置的数组。

use Aws\S3\S3Client;

$s3 = new S3Client([
    'region' => 'us-west-2',
    'retries' => [
        'mode' => 'standard',
        'max_attempts' => 7
    ],
]);

此示例传递 Aws\CacheInterface 的实例以缓存默认重试配置提供程序返回的值。

use Aws\DoctrineCacheAdapter;
use Aws\S3\S3Client;
use Doctrine\Common\Cache\ApcuCache;

$s3 = new S3Client([
    'region' => 'us-west-2',
    'endpoint_discovery' => new DoctrineCacheAdapter(new ApcuCache),
]);

scheme

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

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

有关端点列表以及服务是否支持 http 方案，请参阅 Amazon 区域和端点。

服务

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

signature_provider

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

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

signature_version

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

以下示例展示了如何配置要使用签名版本 4 的 Amazon S3 客户端：

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

ua_append

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

use_aws_shared_config_files

设置为 false，以禁用在“~/.aws/config”和“~/.aws/credentials”中检查共享配置文件。这会覆盖 AWS_CONFIG_FILE 环境变量。

验证

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

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

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

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

version

此选项指定要使用的 Web 服务的版本（例如，2006-03-01）。

从 SDK 的版本 3.277.10 开始，“版本”选项不再是必需的。如果没有指定“版本”选项，则 SDK 使用服务客户端的最新版本。

在创建服务客户端时，有两种情况需要“版本”参数。

例如，以下代码段使用了 SDK 的版本 3.279.7，但不是 Ec2Client 的最新版本。

$ec2Client = new \Aws\Ec2\Ec2Client([
    'version' => '2015-10-01',
    'region' => 'us-west-2'
]);

指定版本约束可确保对服务所做的重大更改不会影响您的代码。

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