全部產品
Search

搜尋本產品

    Object Storage Service：簡單下載OSS檔案

    文件中心

    Object Storage Service：簡單下載OSS檔案

    更新時間：Apr 23, 2025

    簡單下載指的是使用OSS API的GetObject介面，下載已上傳的檔案（Object），適用於一次HTTP請求互動即可完成下載的情境。

    前提條件

    • 已上傳檔案到OSS。具體操作，請參見上傳檔案。

    • 如果要下載Archive Storage類型的Object，請確保該Object已進入解凍狀態或Bucket已開啟歸檔直讀。具體操作，請參見解凍Object和歸檔直讀。

    • 如果要下載冷Archive Storage或者深度冷Archive Storage類型的Object，請確保該Object已進入解凍狀態。具體操作，請參見解凍Object。

    操作方式

    使用OSS控制台

    說明

    不支援通過OSS控制台下載檔案夾（包含子目錄）。如果需要下載檔案夾（包含子目錄），您可以使用ossbrowser、ossutil、SDK、API等方式進行下載。

    1. 登入OSS管理主控台。

    2. 單擊Bucket 列表，然後單擊目標Bucket名稱。

    3. 在左側導覽列，選擇文件管理>檔案清單。

    4. 下載檔案。

      • 下載單個檔案

        方式一：選擇目標檔案右側的more > 下載。

        說明

        如果您已將該操作項從預設的收藏進更多移到檔案常見操作，則無需展開more表徵圖即可直接查看到該操作項。

        方式二：單擊目標檔案的檔案名稱或其右側的詳情，在彈出的詳情面板中單擊下載。

      • 下載多個檔案

        選中多個檔案，然後單擊下方的下載。通過OSS控制台可一次批量下載最多100個檔案。

    使用圖形化管理工具ossbrowser

    ossbrowser支援Object層級的操作與控制台支援的操作類似，請按照ossbrowser介面指引完成簡單下載的操作。關於如何使用ossbrowser，請參見常用操作。

    使用阿里雲SDK

    以下僅列舉常見SDK的簡單下載的程式碼範例。關於其他SDK的簡單下載的程式碼範例，請參見SDK簡介。

    package com.aliyun.oss.demo;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        //從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫不包含Bucket名稱在內的Object完整路徑，例如testfolder/exampleobject.txt。
        String objectName = "testfolder/exampleobject.txt";
        // 填寫Object下載到本地的完整路徑。
        String pathName = "D:\\localpath\\examplefile.txt";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // 下載Object到本地檔案，並儲存到指定的本地路徑中。如果指定的本地檔案存在會覆蓋，不存在則建立。
            // 如果未指定本地路徑，則下載後的檔案預設儲存到樣本程式所屬專案對應本地路徑中。
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}   
    const OSS = require('ali-oss');

const client = new OSS({
  // yourregion填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou。
  region: 'yourRegion',
  // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // 填寫Bucket名稱。
  bucket: 'examplebucket'
});

async function get () {
  try {
    // 填寫Object完整路徑和本地檔案的完整路徑。Object完整路徑中不能包含Bucket名稱。
    // 如果指定的本地檔案存在會覆蓋，不存在則建立。
    // 如果未指定本地路徑，則下載後的檔案預設儲存到樣本程式所屬專案對應本地路徑中。
    const result = await client.get('exampleobject.txt', 'D:\\localpath\\examplefile.txt');
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

get(); 
    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <!--匯入SDK檔案-->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // yourRegion填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou。
        region: "yourRegion",
        authorizationV4: true,
        // 從STS服務擷取的臨時存取金鑰（AccessKey ID和AccessKey Secret）。
        accessKeyId: "yourAccessKeyId",
        accessKeySecret: "yourAccessKeySecret",
        // 從STS服務擷取的安全性權杖（SecurityToken）。
        stsToken: "yoursecurityToken",
        // 填寫Bucket名稱。
        bucket: "examplebucket",
      });

      // 配置回應標頭實現通過URL訪問時自動下載檔案，並設定下載後的檔案名稱。
      const filename = "examplefile.txt";
      const response = {
        "content-disposition": `attachment; filename=${encodeURIComponent(
          filename
        )}`,
      };
      // 填寫Object完整路徑。Object完整路徑中不能包含Bucket名稱。
      const url = client.signatureUrl("exampleobject.txt", { response });
      console.log(url);
    </script>
  </body>
</html>
    // 構造下載檔案請求。
// 依次填寫Bucket名稱（例如examplebucket）和Object完整路徑（例如exampledir/exampleobject.txt）。Object完整路徑中不能包含Bucket名稱。
GetObjectRequest get = new GetObjectRequest("examplebucket", "exampledir/exampleobject.txt");

oss.asyncGetObject(get, new OSSCompletedCallback<GetObjectRequest, GetObjectResult>() {
    @Override
    public void onSuccess(GetObjectRequest request, GetObjectResult result) {
// 開始讀取資料。
        long length = result.getContentLength();
        if (length > 0) {
            byte[] buffer = new byte[(int) length];
            int readCount = 0;
            while (readCount < length) {
                try{
                    readCount += result.getObjectContent().read(buffer, readCount, (int) length - readCount);
                }catch (Exception e){
                    OSSLog.logInfo(e.toString());
                }
            }
    // 將下載後的檔案存放在指定的本地路徑，例如D:\\localpath\\exampleobject.jpg。
            try {
                FileOutputStream fout = new FileOutputStream("download_filePath");
                fout.write(buffer);
                fout.close();
            } catch (Exception e) {
                OSSLog.logInfo(e.toString());
            }
        }
    }

    @Override
    public void onFailure(GetObjectRequest request, ClientException clientException,
                          ServiceException serviceException)  {

    }
});
    OSSGetObjectRequest * request = [OSSGetObjectRequest new];

// 填寫Bucket名稱，例如examplebucket。
request.bucketName = @"examplebucket";
// 填寫檔案完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
request.objectKey = @"exampledir/exampleobject.txt";

// 可選欄位。
request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
    // 當前下載段長度、當前已經下載總長度、一共需要下載的總長度。
    NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
};
// request.range = [[OSSRange alloc] initWithStart:0 withEnd:99]; // bytes=0-99，指定範圍下載。
// request.downloadToFileURL = [NSURL fileURLWithPath:@"<filepath>"]; // 如果需要直接下載到檔案，需要指明目標檔案地址。

OSSTask * getTask = [client getObject:request];

[getTask continueWithBlock:^id(OSSTask *task) {
    if (!task.error) {
        NSLog(@"download object success!");
        OSSGetObjectResult * getResult = task.result;
        NSLog(@"download result: %@", getResult.downloadedData);
    } else {
        NSLog(@"download object failed, error: %@" ,task.error);
    }
    return nil;
}];

// [getTask waitUntilFinished];

// [request cancel];
    #include <alibabacloud/oss/OssClient.h>
#include <memory>
#include <fstream>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion填寫Bucket所在地區對應的Region。以華東1（杭州）為例，Region填寫為cn-hangzhou。*/
    std::string Region = "yourRegion";
    /* 填寫Bucket名稱，例如examplebucket。*/
    std::string BucketName = "examplebucket";
    /* 填寫Object完整路徑，完整路徑中不能包含Bucket名稱，例如exampledir/exampleobject.txt。*/
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* 下載Object到本地檔案examplefile.txt，並儲存到指定的本地路徑中（D:\\localpath）。如果指定的本地檔案存在會覆蓋，不存在則建立。*/
    /* 如果未指定本地路徑，則下載後的檔案預設儲存到樣本程式所屬專案對應本地路徑中。*/
    std::string FileNametoSave = "D:\\localpath\\examplefile.txt";

    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* 下載Object到本地檔案。*/
    GetObjectRequest request(BucketName, ObjectName);
    request.setResponseStreamFactory([=]() {return std::make_shared<std::fstream>(FileNametoSave, std::ios_base::out | std::ios_base::in | std::ios_base::trunc| std::ios_base::binary); });

    auto outcome = client.GetObject(request);

    if (outcome.isSuccess()) {    
        std::cout << "GetObjectToFile success" << outcome.result().Metadata().ContentLength() << std::endl;
    }
    else {
        /* 異常處理。*/
        std::cout << "GetObjectToFile fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}
    #include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";

/* 填寫Bucket名稱，例如examplebucket。*/
const char *bucket_name = "examplebucket";
/* 填寫Object完整路徑，完整路徑中不能包含Bucket名稱，例如exampledir/exampleobject.txt。*/
const char *object_name = "exampledir/exampleobject.txt";
/* 填寫本地檔案的完整路徑。*/
const char *local_filename = "yourLocalFilename";
/* yourRegion填寫Bucket所在地區對應的Region。以華東1（杭州）為例，Region填寫為cn-hangzhou。*/
const char *region = "yourRegion";
void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*類型的字串初始化aos_string_t類型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/    
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    //需要額外配置以下兩個參數
    aos_str_set(&options->config->region, region);
    options->config->signature_version = 4;
    /* 是否使用了CNAME。0表示不使用。*/
    options->config->is_cname = 0;
    /* 用於設定網路相關參數，比如逾時時間等。*/
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main(int argc, char *argv[])
{
    /* 在程式入口調用aos_http_io_initialize方法來初始化網路、記憶體等全域資源。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }
    /* 用於記憶體管理的記憶體池（pool），等價於apr_pool_t。其實現代碼在apr庫中。*/
    aos_pool_t *pool;
    /* 重新建立一個記憶體池，第二個參數是NULL，表示沒有繼承其它記憶體池。*/
    aos_pool_create(&pool, NULL);
    /* 建立並初始化options，該參數包括endpoint、access_key_id、acces_key_secret、is_cname、curl等全域配置資訊。*/
    oss_request_options_t *oss_client_options;
    /* 在記憶體池中分配記憶體給options。*/
    oss_client_options = oss_request_options_create(pool);
    /* 初始化Client的選項oss_client_options。*/
    init_options(oss_client_options);
    /* 初始化參數。*/
    aos_string_t bucket;
    aos_string_t object;
    aos_string_t file;
    aos_table_t *params;
    aos_table_t *headers = NULL;
    aos_table_t *resp_headers = NULL; 
    aos_status_t *resp_status = NULL; 
    aos_str_set(&bucket, bucket_name);
    aos_str_set(&object, object_name);
    aos_str_set(&file, local_filename);
    params = aos_table_make(pool, 0);
    /* 下載檔案。如果指定的本地檔案存在會覆蓋，不存在則建立。*/
    resp_status = oss_get_object_to_file(oss_client_options, &bucket, &object, headers, params, &file, &resp_headers);
    if (aos_status_is_ok(resp_status)) {
        printf("Get object from file succeeded\n");
    } else {
        printf("Get object from file failed\n");
    }  
    /* 釋放記憶體池，相當於釋放了請求過程中各資源分派的記憶體。*/
    aos_pool_destroy(pool);
    /* 釋放之前分配的全域資源。*/
    aos_http_io_deinitialize();
    return 0;
}
    require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  access_key_id: ENV['OSS_ACCESS_KEY_ID'],
  access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)
# 填寫Bucket名稱，例如examplebucket。
bucket = client.get_bucket('examplebucket')
# 將Object下載至本地。
bucket.get_object('exampleobject.txt', :file => 'D:\\localpath\\examplefile.txt')
    package main

import (
	"context"
	"flag"
	"log"
	"net/http"
	"time"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// 定義全域變數
var (
	region     string // 儲存地區
	bucketName string // 儲存空間名稱
	objectName string // 對象名稱
)

// init函數用於初始化命令列參數
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// 解析命令列參數
	flag.Parse()

	// 檢查bucket名稱是否為空白
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// 檢查region是否為空白
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// 檢查object名稱是否為空白
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// 載入預設配置並設定憑證提供者和地區
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// 建立OSS用戶端
	client := oss.NewClient(cfg)

	// 指定本地檔案路徑
	localFile := "download.file"

	// 假設Object最後修改時間為2024年10月21日18:43:02，則填寫的UTC早於該時間時，將滿足IfModifiedSince的限定條件，並觸發下載行為。
	date := time.Date(2024, time.October, 21, 18, 43, 2, 0, time.UTC)

	// 假設ETag為e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855，則填寫的ETag與Object的ETag值相等時，將滿足IfMatch的限定條件，並觸發下載行為。
	etag := "\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\""

	// 建立下載對象到本地檔案的請求
	getRequest := &oss.GetObjectRequest{
		Bucket:          oss.Ptr(bucketName),                   // 儲存空間名稱
		Key:             oss.Ptr(objectName),                   // 對象名稱
		IfModifiedSince: oss.Ptr(date.Format(http.TimeFormat)), // 指定IfModifiedSince參數
		IfMatch:         oss.Ptr(etag),                         // 指定IfMatch參數
	}

	// 執行下載對象到本地檔案的操作並處理結果
	result, err := client.GetObjectToFile(context.TODO(), getRequest, localFile)
	if err != nil {
		log.Fatalf("failed to get object to file %v", err)
	}

	log.Printf("get object to file result:%#v\n", result)
}

    import argparse
import alibabacloud_oss_v2 as oss
import os

# 建立命令列參數解析器
parser = argparse.ArgumentParser(description="get object sample")

# 添加命令列參數 --region，表示儲存空間所在的地區，必需參數
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令列參數 --bucket，表示儲存空間的名稱，必需參數
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令列參數 --endpoint，表示其他服務可用來訪問OSS的網域名稱，非必需參數
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令列參數 --key，表示對象的名稱，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # 解析命令列參數
    args = parser.parse_args()

    # 從環境變數中載入憑證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 載入SDK的預設配置，並設定憑證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 設定配置中的地區資訊
    cfg.region = args.region

    # 如果提供了endpoint參數，則設定配置中的endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 執行擷取對象的請求，指定儲存空間名稱和對象名稱
    result = client.get_object(oss.GetObjectRequest(
        bucket=args.bucket,  # 指定儲存空間名稱
        key=args.key,  # 指定對象鍵名
    ))

    # 輸出擷取對象的結果資訊，用於檢查請求是否成功
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content length: {result.content_length},'
          f' content range: {result.content_range},'
          f' content type: {result.content_type},'
          f' etag: {result.etag},'
          f' last modified: {result.last_modified},'
          f' content md5: {result.content_md5},'
          f' cache control: {result.cache_control},'
          f' content disposition: {result.content_disposition},'
          f' content encoding: {result.content_encoding},'
          f' expires: {result.expires},'
          f' hash crc64: {result.hash_crc64},'
          f' storage class: {result.storage_class},'
          f' object type: {result.object_type},'
          f' version id: {result.version_id},'
          f' tagging count: {result.tagging_count},'
          f' server side encryption: {result.server_side_encryption},'
          f' server side data encryption: {result.server_side_data_encryption},'
          f' next append position: {result.next_append_position},'
          f' expiration: {result.expiration},'
          f' restore: {result.restore},'
          f' process status: {result.process_status},'
          f' delete marker: {result.delete_marker},'
    )

    # ========== 方式1：完整讀取 ==========
    with result.body as body_stream:
        data = body_stream.read()
        print(f"檔案讀取完成，資料長度：{len(data)} bytes")

        path = "./get-object-sample.txt"
        with open(path, 'wb') as f:
            f.write(data)
        print(f"檔案下載完成，儲存至路徑：{path}")

    # # ========== 方式2：分塊讀取 ==========
    # with result.body as body_stream:
    #     chunk_path = "./get-object-sample-chunks.txt"
    #     total_size = 0

    #     with open(chunk_path, 'wb') as f:
    #         # 使用256KB塊大小（可根據需要調整block_size參數）
    #         for chunk in body_stream.iter_bytes(block_size=256 * 1024):
    #             f.write(chunk)
    #             total_size += len(chunk)
    #             print(f"已接收資料區塊：{len(chunk)} bytes | 累計：{total_size} bytes")

    #     print(f"檔案下載完成，儲存至路徑：{chunk_path}")

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數
    <?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);

// 建立GetObjectRequest對象，用於擷取指定對象的內容
$request = new Oss\Models\GetObjectRequest(bucket: $bucket, key: $key);

// 執行擷取對象操作
$result = $client->getObject($request);


// 執行擷取對象操作
$result = $client->getObject($request);

// 定義要儲存的本地檔案路徑
$localFilePath = 'path/to/local/file.txt'; // 請替換為實際的檔案路徑

// 將內容寫入本地檔案
file_put_contents( $localFilePath, $result->body->getContents());

// 列印擷取結果
// 輸出HTTP狀態代碼、請求ID以及對象的內容
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP狀態代碼，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL  // 請求ID，用於調試或追蹤請求
);

    使用命令列工具ossutil

    您可以使用命令列工具ossutil來下載檔案，ossutil的安裝請參見安裝ossutil。

    以下命令用於擷取examplebucket儲存空間下的exampleobject檔案。

    ossutil api get-object --bucket examplebucket --key exampleobject

    關於該命令的更多資訊，請參見get-object。

    相關API

    以上操作方式底層基於API實現，如果您的程式自訂要求較高，您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多資訊，請參見GetObject。

    許可權說明

    阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

    API

    Action

    說明

    GetObject

    oss:GetObject

    下載Object。

    oss:GetObjectVersion

    下載Object時，如果通過versionId指定了Object的版本，則需要授予此操作的許可權。

    kms:Decrypt

    下載Object時，如果Object的中繼資料套件含X-Oss-Server-Side-Encryption: KMS，則需要此操作的許可權。

    計費說明

    簡單下載操作會產生以下計費項目。有關計費項目的定價詳情，請參見OSS產品定價。

    API

    計費項目

    說明

    GetObject

    GET 類型請求

    根據成功的請求次數計算請求費用。

    外網流出流量費用

    如果是通過外網Endpoint（樣本值oss-cn-hangzhou.aliyuncs.com）或者傳輸加速Endpoint（樣本值oss-accelerate.aliyuncs.com）調用GetObject介面時，會產生外網流出流量費用，根據資料容量大小計費。

    低頻訪問資料取回容量

    如果取回的資料是低頻訪問資料，會產生低頻訪問資料取回容量的費用，按資料取回量計費。

    歸檔直讀資料取回容量

    如果讀取的是歸檔的Object且Bucket開啟了歸檔直讀，會產生歸檔直讀資料取回容量費用，根據取回的資料容量大小計費。

    傳輸加速

    如果開啟了傳輸加速功能且使用傳輸加速網域名稱訪問您的Bucket會產生傳輸加速費用，根據資料容量大小計費。

    相關文檔

    • 如何在開啟了版本控制的Bucket中下載檔案，請參見開啟版本控制下Object的操作。

    • 如何在暫停了版本控制的Bucket中下載檔案，請參見暫停版本控制下Object的操作。

    • 為了防止第三方未經授權從您的Bucket裡下載資料，OSS提供了Bucket和Object層級的存取權限控制。更多資訊，請參見許可權控制。

    • 如果您希望在下載大檔案過程中，從下載中斷的位置繼續下載未完成的部分，您可以使用斷點續傳。具體操作，請參見斷點續傳下載。

    • 如果您希望將私人Bucket的Object提供給第三方進行下載，請通過STS臨時訪問憑證或簽名URL的方式授權第三方下載檔案。具體操作，請參見授權給第三方下載。

    • 如果您希望在下載檔案時，滿足限定條件則下載，不滿足限定條件則返回錯誤且不會觸發下載行為，您可以在下載檔案時指定限制條件。具體操作，請參見限定條件下載。