Object Storage Service：OSS PHP SDK V2

快速接入

接入OSS PHP SDK V2的流程如下：

環境準備

要求 PHP 7.4 及以上版本，同時請參考composer官網下載包管理工具composer。

可以通過 php -version 命令查看 php 版本。如果當前環境沒有 php 或版本低於 php 7.4，請下載安裝PHP。

安裝SDK

1. 建立專案目錄，使用包管理工具composer執行以下命令擷取OSS PHP SDK V2。請根據需求選擇合適的OSS PHP SDK V2版本，推薦使用最新的版本，確保本文中的程式碼範例可以正常運行。

   mkdir oss-php-example && cd oss-php-example && composer require alibabacloud/oss-v2

2. 使用以下代碼引入OSS PHP SDK V2包。

   require_once __DIR__ . '/../vendor/autoload.php';
   
   use AlibabaCloud\Oss\V2 as Oss;

配置訪問憑證

使用 RAM 使用者的 AccessKey 配置訪問憑證。

1. 在 RAM 控制台，建立使用永久 AccessKey 訪問的 RAM 使用者，儲存 AccessKey，然後為該使用者授予 AliyunOSSFullAccess 許可權。

2. 使用 RAM 使用者 AccessKey 配置環境變數。

   Linux

   1. 在命令列介面執行以下命令來將環境變數設定追加到~/.bashrc 檔案中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. 執行以下命令使變更生效。

         source ~/.bashrc

      2. 執行以下命令檢查環境變數是否生效。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. 在終端中執行以下命令，查看預設Shell類型。

      echo $SHELL

      1. 根據預設Shell類型進行操作。

         Zsh

         1. 執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

         2. 執行以下命令使變更生效。

            source ~/.zshrc

         3. 執行以下命令檢查環境變數是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

         Bash

         1. 執行以下命令來將環境變數設定追加到 ~/.bash_profile 檔案中。

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

         2. 執行以下命令使變更生效。

            source ~/.bash_profile

         3. 執行以下命令檢查環境變數是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. 在CMD中運行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. 運行以下命令，檢查環境變數是否生效。

         echo %OSS_ACCESS_KEY_ID%
         echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. 在PowerShell中運行以下命令。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

      1. 運行以下命令，檢查環境變數是否生效。

         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

初始化用戶端

使用地區和訪問網域名稱初始化 OSSClient，並運行測試代碼。

<?php

/**
 * PHP SDK V2 用戶端配置完整說明
 *
 * ===========================================
 * V4簽名和Region配置
 * ===========================================
 * • PHP SDK V2預設使用V4簽名演算法
 * • 初始化Client時，必須指定阿里雲通用Region ID作為發起請求地區的標識
 * • 本樣本使用華東1（杭州）Region ID：cn-hangzhou，如需查詢其它 Region ID 請參見：OSS地區和訪問網域名稱
 *
 * ===========================================
 * Endpoint配置說明
 * ===========================================
 * • PHP SDK V2可以通過Endpoint參數自訂服務要求的訪問網域名稱
 * • 當不指定Endpoint時，SDK預設根據Region資訊構造公網訪問網域名稱
 * • 例如：Region為'cn-hangzhou'時，構造的訪問網域名稱為'https://oss-cn-hangzhou.aliyuncs.com'
 *
 * ===========================================
 * 協議選擇
 * ===========================================
 * • PHP SDK V2構造訪問網域名稱時預設採用HTTPS協議（推薦）
 * • 如需採用HTTP協議，請在指定網域名稱時明確指定為http
 * • HTTPS樣本：'https://oss-cn-hangzhou.aliyuncs.com'
 * • HTTP樣本：'http://oss-cn-hangzhou.aliyuncs.com'
 */

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// 方式一：只填寫Region（推薦）- SDK自動構造HTTPS網域名稱
// 華東1（杭州）：cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

// // 方式二：同時填寫Region和Endpoint
// $cfg->setRegion(region: 'cn-hangzhou')->setEndpoint(endpoint: 'https://oss-cn-hangzhou.aliyuncs.com');

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 要上傳的資料內容
$data = 'Hello OSS';

// 建立PutObjectRequest對象，用於上傳對象
$request = new Oss\Models\PutObjectRequest(
                bucket: "Your Bucket Name",
                key: "Your Object Key",
            );
$request->body = Oss\Utils::streamFor($data); // 佈建要求體為資料流

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
printf(
    'status code: %s' . PHP_EOL . // HTTP狀態代碼
    'request id: %s' . PHP_EOL .  // 請求ID
    'etag: %s' . PHP_EOL,         // 對象的ETag
    $result->statusCode,
    $result->requestId,
    $result->etag
);

運行後將會輸出上傳檔案成功的結果：

status code: 200
request id: 687F2BEEDC44E0313527BA07
etag: "F0F18C2C66AE1DD512BDCD4366F76DA3"

用戶端配置

使用自訂網域名

使用OSS預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過通過自訂網域名訪問OSS，不僅支援瀏覽器直接預覽檔案，還可結合CDN加速分發。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
// 填寫您的自訂網域名。例如www.example-***.com，請注意，setUseCname設定true開啟CNAME選項，否則無法使用自訂網域名
// 調用putcname介面需要8以上的php版本
$cfg->setRegion('cn-hangzhou')->setEndpoint('www.example-***.com')->setUseCname(true);

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

逾時控制

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

# 設定建立串連的逾時時間
$cfg->setConnectTimeout(connectTimeout: 30);

# 設定應用讀寫資料的逾時時間
$cfg->setReadwriteTimeout(readwriteTimeout:30);

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

最大錯誤重試次數

請求異常時，OSSClient 預設重試 3 次。

高並發或網路不穩定時，使用 setRetryMaxAttempts 增加重試次數。這能提升請求成功率。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// 華東1（杭州）：cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

// 設定HTTP請求時的最大嘗試次數, 預設值為 3
$cfg->setRetryMaxAttempts(5);

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

HTTP/HTTPS 協議

使用 setDisableSSL(true) 設定不使用HTTPS協議。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// 華東1（杭州）：cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

// 禁用SSL
$cfg->setDisableSSL(true);

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

Swoole架構下使用協程

以下代碼示範了基於swoole架構下建立支援協程的 OSS 用戶端樣本。

<?php
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;
use GuzzleHttp\HandlerStack;
use Hyperf\Guzzle\CoroutineHandler;
use function Hyperf\Coroutine\co;

// 配置 OSS 用戶端
$region = 'cn-hangzhou'; // OSS 地區
$bucket = 'bucket-name'; // 目標 Bucket 名稱
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); // 從環境變數載入憑證
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者
$cfg->setRegion(region: $region); // 設定地區
$cfg->setEndpoint(endpoint: 'http://oss-cn-hangzhou.aliyuncs.com'); // 設定訪問網域名稱

// 建立支援協程的 OSS 用戶端
$client = new Oss\Client(config: $cfg, options: ['handler' => HandlerStack::create(handler: new CoroutineHandler())]);

// 協程任務 1：上傳 swoole.txt
co(function () use ($client, $bucket) {
    try {
        $key = 'swoole.txt'; // 對象名稱
        $data = 'Hello OSS'; // 對象內容
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // 建立上傳請求
        $request->body = Oss\Utils::streamFor($data); // 佈建要求體
        $result = $client->putObject(request: $request); // 執行上傳
        echo "Task 1 Result:\n" . var_export($result, true) . "\n"; // 輸出結果
    } catch (\Exception $e) {
        echo "Task 1 Error: " . $e->getMessage() . "\n"; // 捕獲異常
    }
});

// 協程任務 2：上傳 hyperf.txt
co(function () use ($client, $bucket) {
    try {
        $key = 'hyperf.txt'; // 對象名稱
        $data = 'Hello OSS'; // 對象內容
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // 建立上傳請求
        $request->body = Oss\Utils::streamFor($data); // 佈建要求體
        $result = $client->putObject($request); // 執行上傳
        echo "Task 2 Result:\n" . var_export($result, true) . "\n"; // 輸出結果
    } catch (\Exception $e) {
        echo "Task 2 Error: " . $e->getMessage() . "\n"; // 捕獲異常
    }
});

使用內網網域名稱

當您的應用部署在阿里雲的ECS執行個體上，並且需要頻繁訪問同地區的OSS資源時，使用內網網域名稱可以降低流量成本並提高訪問速度。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// 方式一： 填寫Region並設定setUseInternalEndpoint為true
// 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
$cfg->setRegion('cn-hangzhou')->setUseInternalEndpoint(true);

// // 方式二： 直接填寫Region和Endpoint
// // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
// // 填寫Bucket所在地區對應的內網Endpoint。以華東1（杭州）為例，Endpoint填寫為'https://oss-cn-hangzhou-internal.aliyuncs.com',
// // 如需指定為http協議，請在指定網域名稱時填寫為'http://oss-cn-hangzhou-internal.aliyuncs.com'
// $cfg->setRegion('cn-hangzhou')->setEndpoint('https://oss-cn-hanghzou-internal.aliyuncs.com');

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

使用傳輸加速網域名稱

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// 方式一： 填寫Region並設定setUseAccelerateEndpoint為true
// 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
$cfg->setRegion('cn-hangzhou')->setUseAccelerateEndpoint(true);

// // 方式二： 直接填寫Region和Endpoint
// // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
// // 填寫Bucket所在地區對應的傳輸加速Endpoint。以華東1（杭州）為例，Endpoint填寫為'https://oss-accelerate.aliyuncs.com',
// $cfg->setRegion('cn-hangzhou')->setEndpoint('https://oss-accelerate.aliyuncs.com');

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

使用專有域

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
// 填寫您的專有域。例如：https://service.corp.example.com
$cfg->setRegion('cn-hangzhou')->setEndpoint('https://service.corp.example.com');

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

使用政務雲網域名稱

以下是使用政務雲網域名稱配置OSSClient的範例程式碼。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 載入SDK的預設配置，並設定憑證提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 設定憑證提供者

// Region填寫Bucket所在地區。以華北2 阿里政務雲1為例，Region填寫為cn-north-2-gov-1
// 填寫Bucket所在地區對應的內網Endpoint。以華北2 阿里政務雲1為例，Endpoint填寫為'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
// 如需指定為http協議，請在指定網域名稱時填寫為'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'
$cfg->setRegion('cn-north-2-gov-1')->setEndpoint('https://oss-cn-north-2-gov-1-internal.aliyuncs.com');

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

訪問憑證配置

OSS 提供多種憑證初始化方式。請根據您的認證和授權需求選擇合適的初始化方式。

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

# 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
$region = "cn-hangzhou";

# 建立靜態憑證提供者，顯式設定存取金鑰和密鑰密碼，請替換為您的RAM使用者的AccessKey ID和AccessKey Secret
$credentialsProvider = new Oss\Credentials\StaticCredentialsProvider("RAM AccessKey ID","RAM AccessKey Secret");

// 使用SDK的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定Bucket所在的地區

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

使用STS臨時訪問憑證

如果您的應用程式需要臨時訪問OSS，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問OSS，您需要手動重新整理STS Token。

<?php

// 引入自動負載檔案，確保依賴庫能夠正確載入
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

# 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
$region = "cn-hangzhou";

# 填寫擷取的臨時存取金鑰AccessKey ID和AccessKey Secret，非阿里雲帳號AccessKey ID和AccessKey Secret
# 請注意區分STS服務擷取的Access Key ID是以STS開頭，如下所示
$stsAccessKeyId = 'STS.****************';
$stsAccessKeySecret = 'yourAccessKeySecret';
# 填寫擷取的STS安全性權杖（SecurityToken）
$stsSecurityToken = 'yourSecurityToken';

# 建立靜態憑證提供者，顯式設定臨時存取金鑰AccessKey ID和AccessKey Secret，以及STS安全性權杖
$credentialsProvider = new Oss\Credentials\StaticCredentialsProvider($stsAccessKeyId, $stsAccessKeySecret, $stsSecurityToken);

// 使用SDK的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定Bucket所在的地區

// 建立OSS用戶端執行個體
$client = new Oss\Client($cfg);

// 使用建立好的client執行後續操作...

使用RAMRoleARN

如果您的應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

1. 添加阿里雲憑證庫credentials-php。

   composer require alibabacloud/credentials

2. 配置AK和RAMRoleARN作為訪問憑證。

   <?php
   
   // 引入自動負載檔案，確保依賴庫能夠正確載入
   require_once __DIR__ . '/../vendor/autoload.php';
   
   use AlibabaCloud\Oss\V2 as Oss;
   use AlibabaCloud\Credentials\Credential;
   
   // 建立設定物件，用於定義憑證類型及相關資訊
   $config = new Credential\Config([
       // 指定憑證類型，這裡使用的是 RAM 角色的 ARN 類型
       'type' => 'ram_role_arn',
   
       // AccessKeyId 是阿里雲帳號的存取金鑰 ID
       'accessKeyId' => 'AccessKeyId',
   
       // AccessKeySecret 是阿里雲帳號的存取金鑰
       'accessKeySecret' => 'AccessKeySecret',
   
       // RoleArn 是 RAM 角色的 ARN 格式，例如：acs:ram::USER_Id:role/ROLE_NAME
       'roleArn' => 'RoleArn',
   
       // RoleSessionName 是角色會話名稱，用於標識當前會話
       'roleSessionName' => 'yourRoleSessionName',
   
       // 選擇性參數，用於限制 STS Token 的許可權範圍
       'policy' => 'Policy',
   ]);
   
   // 使用設定物件初始化憑證執行個體
   $credential = new Credential($config);
   
   // 載入SDK預設配置
   $cfg = Oss\Config::loadDefault();
   
   // 設定憑證提供者，通過回呼函數動態產生憑證
   $cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
       // 擷取臨時憑證（STS Token）
       $cred = $credential->getCredential();
   
       // 返回包含 AccessKeyId、AccessKeySecret 和 SecurityToken 的憑證對象
       return new Oss\Credentials\Credentials(
           accessKeyId: $cred->getAccessKeyId(),       // 臨時存取金鑰 ID
           accessKeySecret: $cred->getAccessKeySecret(),   // 臨時存取金鑰
           securityToken: $cred->getSecurityToken()      // 安全性權杖（STS Token）
       );
   }));
   
   // 設定 OSS 用戶端的地區資訊，以華東1（杭州）為例，Region 填寫為 cn-hangzhou
   $region = 'cn-hangzhou';
   $cfg->setRegion($region);
   
   // 建立OSS用戶端執行個體
   $client = new Oss\Client($cfg);
   
   // 使用建立好的client執行後續操作...

使用ECSRAMRole

如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

1. 添加阿里雲憑證庫credentials-php。

   composer require alibabacloud/credentials

2. 配置ECSRAMRole作為訪問憑證。

   <?php
   
   // 引入自動負載檔案，確保依賴庫能夠正確載入
   require_once 'vendor/autoload.php';
   
   use AlibabaCloud\Oss\V2 as Oss;
   use AlibabaCloud\Credentials\Credential;
   
   // 建立設定物件，用於定義憑證類型及相關資訊
   $config = new Credential\Config([
       // 指定憑證類型，這裡使用的是 ECS 執行個體 RAM 角色類型，固定值為 ecs_ram_role
       'type' => 'ecs_ram_role',
   
       // 填寫 ECS 執行個體綁定的 RAM 角色名稱
       'roleName' => "<role_name>",  // 替換為實際的 RAM 角色名稱
   ]);
   
   // 使用設定物件初始化憑證執行個體
   $credential = new Credential($config);
   
   // 載入預設配置並擷取 OSS 設定物件
   $cfg = Oss\Config::loadDefault();
   
   // 設定憑證提供者，通過回呼函數動態產生憑證
   $cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
       // 擷取臨時憑證（STS Token）
       $cred = $credential->getCredential();
   
       // 返回包含 AccessKeyId、AccessKeySecret 和 SecurityToken 的憑證對象
       return new Oss\Credentials\Credentials(
           accessKeyId: $cred->getAccessKeyId(),       // 臨時存取金鑰 ID
           accessKeySecret: $cred->getAccessKeySecret(), // 臨時存取金鑰
           securityToken: $cred->getSecurityToken()   // 安全性權杖（STS Token）
       );
   }));
   
   // 設定 OSS 用戶端的地區資訊，以華東1（杭州）為例，Region 填寫為 cn-hangzhou
   $region = 'cn-hangzhou';
   $cfg->setRegion($region);
   
   // 建立OSS用戶端執行個體
   $client = new Oss\Client($cfg);
   
   // 使用建立好的client執行後續操作...
   

使用OIDCRoleARN

在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見基於RRSA的Pod許可權隔離。

使用自訂訪問憑證

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。SDK 支援多種實現方式。

1. 通過 Oss\Credentials\CredentialsProviderFunc

   Oss\Credentials\CredentialsProviderFunc 是 Oss\Credentials\CredentialsProvider 的易用性封裝。

   <?php
   
   // 引入自動負載檔案，確保依賴庫能夠正確載入
   require_once 'vendor/autoload.php';
   
   // 引入必要的命名空間
   use AlibabaCloud\Oss\V2 as Oss;
   use AlibabaCloud\Oss\V2\Credentials\Credentials;
   
   // 建立一個憑證提供者，通過匿名函數動態產生憑證
   $provider = new Oss\Credentials\CredentialsProviderFunc(
       function () {
           // 返回長期憑證（僅包含 AccessKeyId 和 AccessKeySecret）
           return new Credentials(
               accessKeyId: 'id',         // 替換為實際的RAM AccessKeyId
               accessKeySecret: 'secret'  // 替換為實際的RAM AccessKeySecret
           );
   
           // 如果需要返回臨時憑證（包含 SecurityToken），可以取消以下代碼的注釋並替換實際值
           /*
           return new Credentials(
               accessKeyId: 'id',          // 替換為實際的STS臨時憑證 AccessKeyId
               accessKeySecret: 'secret', // 替換為實際的STS臨時憑證 AccessKeySecret
               securityToken: 'token'     // 替換為實際的STS臨時憑證安全性權杖（STS Token）
           );
           */
       }
   );
   
   // 載入預設配置並擷取 OSS 設定物件
   $cfg = Oss\Config::loadDefault();
   
   // 設定憑證提供者為動態產生的憑證提供者
   $cfg->setCredentialsProvider($provider);
   
   // 設定 OSS 用戶端的地區資訊，以華東1（杭州）為例，Region 填寫為 cn-hangzhou
   $region = 'cn-hangzhou';
   $cfg->setRegion($region);
   
   // 建立 OSS 用戶端執行個體
   $client = new Oss\Client($cfg);
   
   // 使用建立好的 client 執行後續操作...
   

2. 實現 Oss\Credentials\CredentialsProvider

   <?php
   
   // 引入自動負載檔案，確保依賴庫能夠正確載入
   require_once 'vendor/autoload.php';
   
   // 引入必要的命名空間
   use AlibabaCloud\Oss\V2 as Oss;
   use AlibabaCloud\Oss\V2\Credentials\Credentials;
   
   // 自訂憑證提供者類，實現 CredentialsProvider 介面
   class CustomerCredentialsProvider implements Oss\Credentials\CredentialsProvider
   {
       /**
        * 擷取憑證的方法，返回長期或臨時憑證
        *
        * @return Credentials 返回包含存取金鑰資訊的憑證對象
        */
       public function getCredentials(): Credentials
       {
           // 返回長期憑證（僅包含 AccessKeyId 和 AccessKeySecret）
           return new Credentials(
               accessKeyId: 'id',         // 替換為實際的RAM AccessKeyId
               accessKeySecret: 'secret'  // 替換為實際的RAM AccessKeySecret
           );
   
           // 如果需要返回臨時憑證（包含 SecurityToken），可以取消以下代碼的注釋並替換實際值
           /*
           return new Credentials(
               accessKeyId: 'id',          // 替換為實際的STS臨時憑證AccessKeyId
               accessKeySecret: 'secret', // 替換為實際的STS臨時憑證 AccessKeySecret
               securityToken: 'token'     // 替換為實際的STS臨時憑證安全性權杖（STS Token）
           );
           */
       }
   }
   
   // 執行個體化自訂憑證提供者
   $provider = new CustomerCredentialsProvider();
   
   // 載入預設配置並擷取 OSS 設定物件
   $cfg = Oss\Config::loadDefault();
   
   // 設定憑證提供者為自訂的憑證提供者
   $cfg->setCredentialsProvider($provider);
   
   // 設定 OSS 用戶端的地區資訊，以華東1（杭州）為例，Region 填寫為 cn-hangzhou
   $region = 'cn-hangzhou';
   $cfg->setRegion($region);
   
   // 建立 OSS 用戶端執行個體
   $client = new Oss\Client($cfg);
   
   // 使用建立好的 client 執行後續操作...
   

錯誤自助排查

使用PHP SDK V2訪問OSS出現錯誤時，OSS會返回HTTP Code、Message、RequestId、EC錯誤碼等資訊，其中EC碼對應一個具體的錯誤原因，可以使用EC碼自助進行錯誤排查。

範例程式碼

OSS PHP SDK V2提供豐富的範例程式碼供參考或直接使用。