AWS SDK for PHP 版本 3 的配置

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

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

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

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

以下示例展示了如何将选项传入 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 之一。

默认情况下，SDK使用从Aws\Api\FileSystemApiProvider的src/data文件夹加载API文件的实例SDK。

凭证

传递 Aws\Credentials\CredentialsInterface 对象以使用特定凭证实例。以下内容指定应使用IAM身份中心凭证提供商。该提供商也称为SSO凭证提供商。

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

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

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

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

传递 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
]);

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

调试

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

设置为 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

绑定将统计数据传输到SDK操作返回的错误和结果。

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

端点

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

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

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 返回模拟结果或引发模拟异常。您将结果或异常排入队列，然后按 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-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选项SDK。

SDK支持以下配置选项：

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' => 'amzn-s3-demo-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' => 'amzn-s3-demo-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选项通过代理连接到 AWS 服务。

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

确认

您可以使用verifyhttp选项自定义的对等体SSL/TLS证书验证行为。SDK

如果找不到适用于您的系统的 CA 捆绑包并且您收到错误消息，请提供指向 CA 捆绑包的路径SDK。如果你不需要特定的 CA 捆绑包，Mozilla 会提供一个常用的 CA 捆绑包，你可以在这里下载（由 c URL 的维护者维护）。磁盘上有 CA 包可用后，可以将 openssl.cafile PHP .ini 设置设置为指向文件路径，从而可以省略verify请求选项。您可以在 c URL 网站上找到有关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选项用于SDK与其他HTTP客户端集成。http_handler 选项是一个函数，接受 Psr\Http\Message\RequestInterface 对象和一组应用于命令的 http 选项，并返回已完成并显示 GuzzleHttp\Promise\PromiseInterface 对象或已拒绝并显示以下一组异常数据的 Psr\Http\Message\ResponseInterface 对象：

通过用Aws\WrappedHttpHandler对象包装提供的handlerhttp_handler选项，SDK自动将给定的http_handler选项转换为普通选项。

默认情况下，SDK使用 Guzzle 作为其处理程序。HTTP您可以在此处提供不同的HTTP处理程序，也可以为 Guzzle 客户端提供您自己的自定义选项。

设置TLS版本

一个用例是使用 Curl 设置 Guzzle 使用的TLS版本，假设您的环境中安装了 Curl。请注意支持哪个版本的 Curl 版本限制。TLS默认情况下会使用最新版本。如果明确设置了TLS版本，而远程服务器不支持此版本，则会产生错误，而不是使用较早的TLS版本。

您可以通过将客户端选项设置为 true 并检查SSL连接输出来确定用于给定debug客户端操作的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
]);

配置文件

“profile” 选项指定从HOME目录中的凭据文件创建 AWS 凭据时要使用的配置文件（通常~/.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 文件格式的更多信息，请参阅 AWS SDK for PHP 版本 3 的凭据。

region

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

// 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连接时使用的方案。默认情况下SDK使用 “https” 端点（即使用SSL/TLS连接）。您可以通过将 scheme 设置为“http”，尝试通过未加密的“http”端点来连接服务。

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

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

服务

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

signature_provider

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

Aws\Signature\SignatureProvider类SDK中提供了各种函数，可用于创建自定义签名提供程序。

signature_version

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

以下示例展示了如何配置要使用签名版本 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’ and ‘~/.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]
]);

版本

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

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

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

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

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

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

可用API版本列表可在每个客户的API文档页面上找到。如果您无法加载特定API版本，则可能需要更新副本SDK。