第 3 AWS SDK for PHP 版的組態

用戶端建構器選項可在用戶端建構器中提供，或提供給 Aws\Sdk類別。提供給特定類型用戶端的選項陣列可能不同，取決於您所建立的用戶端。這些自訂用戶端組態選項會在每個用戶端的 API 文件中說明。

請注意，某些組態選項會根據環境變數或 AWS 組態檔案來檢查並使用預設值。依預設，正在檢查的組態檔案會位於您主目錄中的 .aws/config，通常為 ~/.aws/config。但是，您可以使用環境變數 AWS_CONFIG_FILE 來設訂預設組態檔案的位置。例如，如果您使用 限制對特定目錄的檔案存取，這可能很有用open_basedir。

如需共用 AWS 和credentials檔案的位置config和格式的詳細資訊，請參閱 AWS SDKs and Tools 參考指南中的組態。

如需您可以在組態檔案或環境變數中 AWS 設定的所有全域組態設定的詳細資訊，請參閱 Word and Tools 參考指南中的組態和身分驗證設定參考。 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，該執行個體會從 API 的src/data資料夾載入 SDK 檔案。

登入資料

傳遞 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」。若要進一步了解如何設定具名設定檔，請參閱 AWS SDKs and Tools 參考指南中的共用和configcredentials檔案。

如果您未指定要使用的憑證提供者，並依賴憑證提供者鏈，則驗證失敗所產生的錯誤訊息通常是一般的。這是從正在檢查有效憑證的來源清單中的最後一個提供者產生，這可能不是您嘗試使用的提供者。當您指定要使用的憑證提供者時，任何產生的錯誤訊息都更實用且相關，因為其僅由該提供者產生。若要進一步了解檢查憑證的來源鏈，請參閱 AWS SDKs and Tools 參考指南中的憑證提供者鏈。

傳遞 false 以使用 null 登入資料，而且不簽署請求。

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

您可以在第 3 AWS SDK for PHP 版的憑證指南中找到有關提供憑證給用戶端的詳細資訊。

偵錯

輸出各個傳輸的偵錯資訊。偵錯資訊包含有關交易在準備及透過網路傳送時每個狀態變更的資訊。偵錯輸出中也包含用戶端使用的特定 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();

統計資料

繫結會將統計資料傳輸到 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'];

端點

Web 服務的完整 URI。對於使用帳戶特定端點的服務，例如 AWS Elemental MediaConvert ，這是必要的。對於這些服務，請使用 describeEndpoints方法請求此端點。

只有在連線至自訂端點 （例如 Amazon S3 或 Amazon DynamoDB Local 的本機版本） 時才需要此功能。

以下是連線至 Amazon DynamoDB Local 的範例：

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

如需可用AWS 區域和端點的清單，請參閱 AWS 區域和端點。

endpoint_provider

選用的 EndpointProviderV2 或 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([
    '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
    ],
]);

處理常式

接受命令物件和請求物件的處理常式，而且會傳回承諾 (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

延遲

在傳送請求之前的延遲毫秒數。這通常用於重試請求之前的延遲。

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 選項控制將操作的回應資料下載至何處。

同步

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選項自訂 SDK 的對等 SSL/TLS 憑證驗證行為。

如果找不到系統的 CA 套件，且您收到錯誤，請將 CA 套件的路徑提供給 SDK。如果您不需要特定的 CA 套件，Mozilla 會提供常用的 CA 套件，您可以在這裡下載 （這會由 cURL 的維護者維護）。一旦磁碟上有可用的 CA 套件，您可以設定 openssl.cafile PHP .ini 設定以指向檔案的路徑，讓您省略verify請求選項。您可以在 cSSL 網站上找到有關 Word 憑證的詳細資訊。 URL

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 物件或遭到拒絕並附帶以下例外狀況資料：

SDK 會自動將提供的 轉換為一般handler選項http_handler，方法是將 http_handler 物件隨附的 包裝起來Aws\WrappedHttpHandler。

根據預設，SDK 會使用 Guzzle 作為其 HTTP 處理常式。您可以在這裡提供不同的 HTTP 處理常式，或提供 Guzzle 用戶端您自己的自訂定義選項。

設定 TLS 版本

其中一個使用案例是設定 Guzzle 搭配 Curl 使用的 TLS 版本，假設 Curl 已安裝在您的環境中。請注意支援哪些 TLS 版本的 Curl 版本限制。根據預設會使用最新版本。如果明確設定 TLS 版本，且遠端伺服器不支援此版本，則會產生錯誤，而不是使用較早的 TLS 版本。

您可以將debug用戶端選項設定為 true 並檢查 TLS 連線輸出，以判斷用於指定用戶端操作的 SSL 版本。該行可能看起來如下：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'
]);

retries

設定用戶端的重試模式和允許重試次數上限。傳遞 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),
]);

結構描述

連線時要使用的URI配置。根據預設，SDK 會使用「https」端點 （即使用 SSL/TLS 連線）。您可以藉由將 scheme 設為 “http”，來嘗試透過未加密的 “http” 端點連線到服務。

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

如需端點清單AWS ，以及服務是否支援 方案，請參閱 區域和端點。 http

服務

要使用的名稱服務。使用 SDK 提供的用戶端 （即 Aws\S3\S3Client) 時，預設會提供此值。此選項在測試尚未在 SDK 中發佈，但磁碟上有可用的服務時非常有用。

signature_provider

可呼叫，可接受簽章版本名稱 （例如 v4)、服務名稱和 AWS 區域，並傳回Aws\Signature\SignatureInterface物件，或者NULL如果提供者能夠為指定參數建立簽署者。此供應商用於建立由用戶端使用的簽署者。

Aws\Signature\SignatureProvider 類別中的 SDK 提供各種函數，可用於建立自訂簽章提供者。

signature_version

字串，表示要搭配服務 (例如，v4 等) 使用的自訂簽章版本。如有需要，每個操作簽章版本 MAY 會覆寫此請求的簽章版本。

下列範例示範如何設定 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

設定為 false，以停用 ‘~/.aws/config’ and ‘~/.aws/credentials’ 中的共用組態檔案檢查。這將覆寫 AWS_CONFIG_FILE 環境變數。

validate

設定為 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 版本，您可能需要更新 SDK 的副本。