Amazon SDK for PHP版本 3 的配置

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

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

有关共享Amazonconfig和credentials文件的位置和格式的更多信息，请参阅《软件开发工具包和Amazon工具参考指南》中的配置。

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

以下示例介绍如何将选项传递到 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 对象以使用特定凭证实例。

$credentials = new Aws\Credentials\Credentials('key', 'secret');

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

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

传递 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\Credentials\CredentialProvider;
use Aws\DoctrineCacheAdapter;
use Doctrine\Common\Cache\ApcuCache;

$cache = new DoctrineCacheAdapter(new ApcuCache);
$provider = CredentialProvider::defaultProvider();
$cachedProvider = CredentialProvider::cache($provider, $cache);

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

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

debug

输出有关每次传输的调试信息。调试信息包含在准备和通过线路发送事务时事务的每个状态变更的信息。调试输出中还包括有关客户端所使用的特定 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();

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

$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();

stats

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

设置为 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'];

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

$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

Web 服务的完整 URI。这对于使用账户特定终端节点的服务（例如 MediaConvert）是必需的。对于这些服务，请使用describeEndpoints方法请求此端点。

只有在连接到自定义终端节点（例如，本地版本的 Amazon S3 或 Amazon DynamoDB Local）时，才需要这样做。

示例如下 Amazon DynamoDB Config：

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

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

endpoint_provider

一个 EndpointProvider V2 或 PHP 可调用的可选实例，它接受一系列选项，包括 “服务” 和 “区域” 密钥。它会返回 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

终端节点发现识别并连接到支持终端节点发现的服务 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

一个处理程序，接受命令对象和请求对象，并返回已完成并显示 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-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

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

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

cert

指定 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

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

decode_content

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

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

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

expect

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

progress

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

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

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

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

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

synchronous

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

stream

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

timeout

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

use Aws\DynamoDb\DynamoDbClient;

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

verify

您可以使用 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',
    '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

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',
    'version' => 'latest',
    'http_handler' => $handler
]);

profile

允许您指定在从 HOME 目录中的证书文件创建Amazon证书时要使用的配置文件。此设置将覆盖 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 的凭据。

区域

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

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

重试

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

三种重试模式是：* legacy – 默认的旧式重试实施 * standard – 添加重试配额系统，以防止不太可能成功的

重试

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

优先顺序

重试配置的优先级顺序如下所示（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([
    'version' => 'latest',
    'region' => 'us-east-2',
    'retries' => $config,
]);

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

use Aws\S3\S3Client;

$s3 = new S3Client([
    'version'     => 'latest',
    '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([
    'version'     => 'latest',
    '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区域和终端节点。

service

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

signature_provider

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

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

signature_version

一个字符串，表示要用于服务的自定义签名版本 (例如 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'
]);

ua_append

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

use_aws_shared_config_files

设置为 faw./.aws.aws.aws.aws.aw.aws.aw.aws.aw.aws.aw.aws.aw.aws.aw 这将覆盖 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)。

“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'
]);