PHP檔案下載管理員 - Object Storage Service

本文針對檔案的傳輸情境，介紹如何使用PHP SDK V2新增的下載管理員Downloader模組進行檔案下載。

注意事項

本文範例程式碼以華東1（杭州）的地區IDcn-hangzhou為例，預設使用外網Endpoint，如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。
本文以從環境變數讀取存取憑證為例。更多配置訪問憑證的樣本，請參見PHP配置訪問憑證。
要進行檔案下載，您必須有oss:GetObject許可權。具體操作，請參見為RAM使用者授予自訂的權限原則。

方法定義

下載管理員功能簡介

PHP SDK V2新增下載管理員Downloader提供了通用的下載介面，隱藏了底層介面的實現細節，提供便捷的檔案下載能力。

下載管理員Downloader底層利用範圍下載，把檔案自動分成多個較小的分區進行並發下載，提升下載的效能。
下載管理員Downloader同時提供了斷點續傳的能力，即在下載過程中，記錄已完成的分區狀態，如果出現網路中斷、程式異常退出等問題導致檔案下載失敗，甚至重試多次仍無法完成下載，再次下載時，可以通過斷點記錄檔案恢複下載。

下載管理員Downloader的常用方法如下：

final class Downloader
{
	...
    public function __construct($client, array $args = [])
    
    public function downloadFile(Models\GetObjectRequest $request, string $filepath, array $args = []): Models\DownloadResult   
    
    public function downloadTo(Models\GetObjectRequest $request, \Psr\Http\Message\StreamInterface $stream, array $args = []): Models\DownloadResult
}

請求參數列表

參數名	類型	說明
request	GetObjectRequest	下載對象的請求參數，和 GetObject 介面的請求參數一致
filePath	string	本地檔案路徑
args	array	（可選）配置選項

其中，args常用參數說明列舉如下：

參數名	類型	說明
part_size	int	指定分區大小，預設值為 6MiB
parallel_num	int	指定下載任務的並發數，預設值為 3。針對的是單次調用的並發限制，而不是全域的並發限制
use_temp_file	bool	下載檔案時，是否使用臨時檔案，預設使用。先下載到臨時檔案上，當成功後，再重新命名為目標檔案

當使用Downloader執行個體化執行個體時，您可以指定多個配置選項來自訂對象的下載行為。也可以在每次調用下載介面時，指定多個配置選項來自訂每次下載對象的行為。

設定Downloader的配置參數：

$d = $client->newDownloader(['part_size' => 10 * 1024 * 1024]);

設定每次下載請求的配置參數：

$d->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: 'bucket',
        key: 'key'
    ),
    filepath: '/local/dir/example',
    args: ['part_size' => 10 * 1024 * 1024]
);

範例程式碼

您可以使用以下代碼將儲存空間中的檔案下載到本地。

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// 定義命令列參數的描述資訊
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地區（必填）
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 訪問網域名稱（可選）
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名稱（必填）
    "key" => ['help' => 'The name of the object', 'required' => True], // 對象名稱（必填）
];

// 將參數描述轉換為getopt所需的長選項格式
// 每個參數後面加上":"表示該參數需要值
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 解析命令列參數
$options = getopt("", $longopts);

// 驗證必填參數是否存在
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // 擷取參數的協助資訊
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 如果必填參數缺失，則退出程式
    }
}

// 從解析的參數中提取值
$region = $options["region"]; // Bucket所在的地區
$bucket = $options["bucket"]; // Bucket名稱
$key = $options["key"];       // 對象名稱

// 載入環境變數中的憑證資訊
// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 使用SDK的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定Bucket所在的地區
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // 如果提供了訪問網域名稱，則設定endpoint
}

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

// 建立下載器執行個體
$downloader = $client->newDownloader();

// 定義本地檔案路徑，用於儲存下載的內容
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑
touch($filename); // 建立一個空檔案，確保檔案存在

// 執行分區下載操作
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename
);

// 列印下載結果
printf(
    'download status code:' . $result->statusCode . PHP_EOL .
    'download request id:' . $result->requestId . PHP_EOL .
    'download result:' . var_export($result, true) . PHP_EOL
);

常見使用情境

使用下載管理員設定分區大小和並發數

您可以使用以下代碼配置下載管理員，設定分區大小和並發數。

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// 定義命令列參數的描述資訊
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地區（必填）
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 訪問網域名稱（可選）
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名稱（必填）
    "key" => ['help' => 'The name of the object', 'required' => True], // 對象名稱（必填）
];

// 將參數描述轉換為getopt所需的長選項格式
// 每個參數後面加上":"表示該參數需要值
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 解析命令列參數
$options = getopt("", $longopts);

// 驗證必填參數是否存在
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // 擷取參數的協助資訊
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 如果必填參數缺失，則退出程式
    }
}

// 從解析的參數中提取值
$region = $options["region"]; // Bucket所在的地區
$bucket = $options["bucket"]; // Bucket名稱
$key = $options["key"];       // 對象名稱

// 載入環境變數中的憑證資訊
// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 使用SDK的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定Bucket所在的地區
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // 如果提供了訪問網域名稱，則設定endpoint
}

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

// 建立下載器執行個體
$downloader = $client->newDownloader();

// 定義分區下載的相關參數
$partSize = 100 * 1024; // 分區大小，單位為位元組（此處設定為100KB）

// 定義本地檔案路徑，用於儲存下載的內容
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑
touch($filename); // 建立一個空檔案，確保檔案存在

// 執行分區下載操作
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename,
    args: [ // 選擇性參數，用於自訂分區下載行為
        'part_size' => $partSize, // 自訂分區大小
        'parallel_num' => 1,      // 並發下載的分區數量
    ]
);

// 列印下載結果
printf(
    'download status code:' . $result->statusCode . PHP_EOL .
    'download request id:' . $result->requestId . PHP_EOL .
    'download result:' . var_export($result, true) . PHP_EOL
);

使用下載管理員下載到流中

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// 定義命令列參數的描述資訊
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地區（必填）
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 訪問網域名稱（可選）
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名稱（必填）
    "key" => ['help' => 'The name of the object', 'required' => True], // 對象名稱（必填）
];

// 將參數描述轉換為getopt所需的長選項格式
// 每個參數後面加上":"表示該參數需要值
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 解析命令列參數
$options = getopt("", $longopts);

// 驗證必填參數是否存在
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // 擷取參數的協助資訊
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 如果必填參數缺失，則退出程式
    }
}

// 從解析的參數中提取值
$region = $options["region"]; // Bucket所在的地區
$bucket = $options["bucket"]; // Bucket名稱
$key = $options["key"];       // 對象名稱

// 載入環境變數中的憑證資訊
// 使用EnvironmentVariableCredentialsProvider從環境變數中讀取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 使用SDK的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定Bucket所在的地區
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // 如果提供了訪問網域名稱，則設定endpoint
}

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

// 建立下載器執行個體
$downloader = $client->newDownloader();

// 定義一個緩衝流，用於儲存下載的內容
$stream = new \GuzzleHttp\Psr7\BufferStream(1 * 1024 * 1024); // 緩衝區大小為1MB

// 執行下載操作，將對象內容下載到緩衝流中
$result = $downloader->downloadTo(
    request: new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key // 指定要下載的對象名稱
    ),
    stream: $stream, // 指定目標流，用於儲存下載的內容
);

// 列印下載的內容
printf(
    'download to body:' . $stream->getContents() . PHP_EOL // 輸出緩衝流中的內容
);

Object Storage Service：檔案下載管理員（PHP SDK V2）