前提條件

• 已上傳文件到OSS。具體操作，請(qǐng)參見上傳文件。

• 如果要下載歸檔存儲(chǔ)類型的Object，請(qǐng)確保該Object已進(jìn)入解凍狀態(tài)或Bucket已開啟歸檔直讀。具體操作，請(qǐng)參見解凍Object和歸檔直讀。

• 如果要下載冷歸檔存儲(chǔ)或者深度冷歸檔存儲(chǔ)類型的Object，請(qǐng)確保該Object已進(jìn)入解凍狀態(tài)。具體操作，請(qǐng)參見解凍Object。

• 已具有oss:GetObject權(quán)限。具體操作，請(qǐng)參見RAM Policy常見示例。

使用場(chǎng)景

• 應(yīng)用資源更新：應(yīng)用僅在檢測(cè)到OSS文件ETag變更或最后修改時(shí)間更新時(shí)下載新資源，最小化數(shù)據(jù)使用，優(yōu)化用戶體驗(yàn)。

• 數(shù)據(jù)同步與增量備份：基于OSS的最后修改時(shí)間或ETag，確保只同步或備份更改過的文件，節(jié)省帶寬，保障數(shù)據(jù)的時(shí)效性和一致性。

• 文件共享和同步：使用ETag或最后修改時(shí)間進(jìn)行驗(yàn)證，僅在必要時(shí)同步文件，加速協(xié)作，降低數(shù)據(jù)消耗。

限定條件

OSS支持的限定條件如下：

操作步驟

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;
import java.util.Date;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請(qǐng)按實(shí)際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫B(tài)ucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫不包含Bucket名稱在內(nèi)的Object完整路徑，例如testfolder/exampleobject.txt。
        String objectName = "testfolder/exampleobject.txt";
        String pathName = "D:\\localpath\\examplefile.txt";

        // 創(chuàng)建OSSClient實(shí)例。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            // 假設(shè)Object最后修改時(shí)間為2023年9月26日13:27:04，當(dāng)填寫早于該時(shí)間的Data對(duì)象時(shí)（例如Tue Sep 25 13:27:04 CST 2023），將滿足If-Modified-Since的限定條件，并觸發(fā)下載行為。
            request.setModifiedSinceConstraint(new Date("Tue Sep 25 13:27:04 CST 2023"));

            // 下載OSS文件到本地文件。
            ossClient.getObject(request, 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();
            }
        }
    }
}
        

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

// 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州為例，其它Region請(qǐng)按實(shí)際情況填寫。
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 填寫B(tài)ucket名稱。
$bucket= "yourBucketName";
// 填寫Object名稱。Object名稱為不包含Bucket名稱在內(nèi)的Object的完整路徑，例如exampledir/exampleobject.txt。
$object = "yourObjectName";
// 填寫本地文件的完整路徑。例如D:\\localpath\\examplefile.txt。
$localfile = "yourLocalFile";

try{
    $options = array(
        OssClient::OSS_HEADERS => array(          
           // 指定下載實(shí)際修改時(shí)間晚于Fri, 9 Apr 2021 14:47:53 GMT的Object。
          OssClient::OSS_IF_MODIFIED_SINCE => "Fri, 9 Apr 2021 14:47:53 GMT",
          // 指定下載實(shí)際修改時(shí)間早于或者等于Wed, 13 Oct 2021 14:47:53 GMT的Object。
          OssClient::OSS_IF_UNMODIFIED_SINCE => "Fri, 13 Oct 2021 14:47:53 GMT",
          // 指定下載與傳入的ETag值不匹配的Object。
          OssClient::OSS_IF_NONE_MATCH => '"5B3C1A2E0563E1B002CC607C****"',
          // 指定下載與傳入的ETag值匹配的Object。
          OssClient::OSS_IF_MATCH => '"fba9dede5f27731c9771645a3986****"',          
          OssClient::OSS_FILE_DOWNLOAD => $localfile
        )

    );

    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);
    $ossClient->getObject($bucket, $object, $options);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

const OSS = require('ali-oss');

const client = new OSS({
  // yourregion填寫B(tài)ucket所在地域。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou。
  region: 'yourRegion',
  // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填寫B(tài)ucket名稱。
  bucket: 'examplebucket'
});

async function main() {
  try {
    // 向目標(biāo)Bucket上傳名為exampleobject.txt的文件，文件內(nèi)容自定義。
    await client.put("exampleobject.txt", Buffer.from("contenttest"));
    // 在請(qǐng)求頭If-Modified-Since中指定時(shí)間，如果指定的時(shí)間早于文件實(shí)際修改時(shí)間，則下載文件。
    let result = await client.get("exampleobject.txt", {
      headers: {
        "If-Modified-Since": new Date("1970-01-01").toGMTString(),
      },
    });
    console.log(result.content.toString() === "contenttest");
    console.log(result.res.status === 200);

    // 如果指定的時(shí)間等于或者晚于文件實(shí)際修改時(shí)間，則返回304 Not Modified。
    result = await client.get("exampleobject.txt", {
      headers: {
        "If-Modified-Since": new Date().toGMTString(),
      },
    });
    console.log(result.content.toString() === "");
    console.log(result.res.status === 304);
  } catch (e) {
    console.log(e.code === "Not Modified");
  }
}

main();

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫B(tài)ucket名稱，例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填寫不包含Bucket名稱在內(nèi)的Object完整路徑，例如exampledir/exampleobject.txt。關(guān)于Object名稱命名規(guī)范的更多信息，請(qǐng)參見Object。
object_name = 'exampledir/exampleobject.txt'

headers = dict()
# 如果指定的時(shí)間早于Object實(shí)際修改時(shí)間，則正常下載Object，否則返回錯(cuò)誤304 Not modified。
headers['If-Modified-Since'] = 'Mon, 13 Dec 2021 14:47:53 GMT'
# 如果指定的時(shí)間等于或者晚于Object實(shí)際修改時(shí)間，則正常下載Object，否則返回錯(cuò)誤412 Precondition failed。
# headers['If-Unmodified-Since'] = 'Mon, 13 Dec 2021 14:47:53 GMT'
# 如果傳入的ETag和Object的ETag匹配，則正常下載Object，否則返回錯(cuò)誤412 Precondition failed。
# headers['If-Match'] = 'DC21493F505BA3739562D8CC452C****'
# 如果傳入的ETag值和Object的ETag不匹配，則正常下載Object，否則返回錯(cuò)誤304 Not modified。
# headers['If-None-Match'] = 'DC21493F505BA3739562D8CC452C****'
object_stream = bucket.get_object(object_name, headers=headers)
print(object_stream.read())

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id='upload'>上傳</button>
  <button id='download'>下載</button>
    <!--導(dǎo)入SDK文件-->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
      const client = new OSS({
         // yourRegion填寫B(tài)ucket所在地域。以華東1（杭州）為例，yourRegion填寫為oss-cn-hangzhou。
         region: 'yourRegion',
         // 從STS服務(wù)獲取的臨時(shí)訪問密鑰（AccessKey ID和AccessKey Secret）。
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // 從STS服務(wù)獲取的安全令牌（SecurityToken）。
        stsToken: 'yourSecurityToken',
        // 填寫B(tài)ucket名稱，例如examplebucket。
        bucket: "examplebucket",
      });

    const download = document.getElementById('download')
    const upload = document.getElementById('upload')

    // 上傳文件。  
    upload.addEventListener('click', () => {
      // 指定待上傳的文件內(nèi)容。
      const file = new Blob(['examplecontent'])
      // 指定待上傳文件的完整路徑，例如exampledir/exampleobject.txt。
      const fileName = 'exampledir/exampleobject.txt'
      const result = client.put(fileName, file).then(r => console.log(r))
    })

    // 下載文件。
    download.addEventListener('click', () => {
      // 指定待下載的字節(jié)范圍。
      const start = 1, end = 5
      client.get('exampledir/exampleobject.txt', {
        headers: {
          // 在請(qǐng)求頭If-Modified-Since中指定時(shí)間，如果指定的時(shí)間早于文件實(shí)際修改時(shí)間，則下載文件。如果指定的時(shí)間等于或者晚于文件實(shí)際修改時(shí)間，則返回304 Not Modified。
          "If-Modified-Since": new Date("1970-01-01").toGMTString()
          // 在請(qǐng)求頭If-Unmodified-Since中指定時(shí)間，如果指定的時(shí)間等于或者晚于文件實(shí)際修改時(shí)間，則下載文件。如果指定的時(shí)間早于文件實(shí)際修改時(shí)間，則返回412 Precondition Failed。
          //"If-Unmodified-Since": new Date(1970-01-01).toGMTString()
          // 在請(qǐng)求頭If-Match中傳入ETag，如果傳入的ETag和文件的ETag匹配，則下載文件。如果傳入的ETag和文件的ETag不匹配，則返回412 Precondition Failed。
          //"If-Match": '5B3C1A2E0563E1B002CC607C****'
          // 在請(qǐng)求頭If-None-Match中傳入ETag，如果傳入的ETag和文件的ETag不匹配，則下載文件。如果傳入的ETag和文件的ETag匹配，則返回304 Not Modified。
          //"If-None-Match": '5B3C1A2E0563E1B002CC607C****'
        },
      }).then(r => {
        if (r.content.length > 0) {                
          const newBlob = new Blob([r.content], { type: r.res.headers['content-type'] });
          const link = document.createElement('a')
          link.href = window.URL.createObjectURL(newBlob)
          link.download = 'foo.txt'
          link.click()
          window.URL.revokeObjectURL(link.href)
        } else {
          console.log('錯(cuò)誤碼', r.res.status)
          console.log('沒有符合條件的下載項(xiàng)')
        }
      })
    })

  </script>
</body>

</html>

// 依次填寫B(tài)ucket名稱（例如examplebucket）、Object完整路徑（例如exampledir/exampleobject.txt）。
// Object完整路徑中不能包含Bucket名稱。
String bucketName = "examplebucket";
String objectKey = "exampledir/exampleobject.txt";
// 構(gòu)造下載文件請(qǐng)求。
Map<String, String> headers = new HashMap<>();
// 如果指定的時(shí)間早于實(shí)際修改時(shí)間，則正常傳輸文件，否則返回錯(cuò)誤（304 Not modified）。
headers.put(OSSHeaders.GET_OBJECT_IF_MODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// 如果指定的時(shí)間等于或者晚于文件實(shí)際修改時(shí)間，則正常傳輸文件，否則返回錯(cuò)誤（412 Precondition failed）
// headers.put(OSSHeaders.GET_OBJECT_IF_UNMODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// 如果指定的ETag和OSS文件的ETag匹配，則正常傳輸文件，否則返回錯(cuò)誤（412 Precondition failed）
// headers.put(OSSHeaders.GET_OBJECT_IF_MATCH, "5B3C1A2E0563E1B002CC607C*****");
// 如果指定的ETag和OSS文件的ETag不匹配，則正常傳輸文件，否則返回錯(cuò)誤（304 Not modified）
// headers.put(OSSHeaders.GET_OBJECT_IF_NONE_MATCH, "5B3C1A2E0563E1B002CC607C*****");
GetObjectRequest get = new GetObjectRequest(bucketName, objectKey);
get.setRequestHeaders(headers);

OSSAsyncTask task = oss.asyncGetObject(get, new OSSCompletedCallback<GetObjectRequest, GetObjectResult>() {
    @Override
    public void onSuccess(GetObjectRequest request, GetObjectResult result) {
        // 請(qǐng)求成功。
        InputStream inputStream = result.getObjectContent();
        byte[] buffer = new byte[2048];
        int len;
        try {
            while ((len = inputStream.read(buffer)) != -1) {
                // 處理下載的數(shù)據(jù)。
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFailure(GetObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // 請(qǐng)求異常。
        if (clientExcepion != null) {
            // 本地異常如網(wǎng)絡(luò)異常等。
            clientExcepion.printStackTrace();
        }
        if (serviceException != null) {
            // 服務(wù)異常。
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

package main

import (
    "fmt"
    "os"
    "time"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 創(chuàng)建OSSClient實(shí)例。
    // yourEndpoint填寫B(tài)ucket對(duì)應(yīng)的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請(qǐng)按實(shí)際情況填寫。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // yourBucketName填寫存儲(chǔ)空間名稱。
    bucket, err := client.Bucket("yourBucketName")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 假設(shè)Object最后修改時(shí)間為2023年11月21日18:43:02，則填寫的UTC早于該時(shí)間時(shí)，將滿足IfModifiedSince的限定條件，并觸發(fā)下載行為。
    date := time.Date(2023, time.November, 21, 10, 40, 02, 0, time.UTC)

    // 不滿足限定條件，不下載文件。
    // yourObjectName填寫不包含Bucket名稱在內(nèi)的Object的完整路徑。
    err = bucket.GetObjectToFile("yourObjectName", "LocalFile", oss.IfUnmodifiedSince(date))    
    if err == nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 滿足限定條件，下載文件。
    err = bucket.GetObjectToFile("yourObjectName", "LocalFile", oss.IfModifiedSince(date))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
}

OSSGetObjectRequest *get = [OSSGetObjectRequest new];
// 填寫B(tài)ucket名稱。關(guān)于Bucket名稱命名規(guī)范的更多信息，請(qǐng)參見Bucket。
get.bucketName = @"examplebucket";
// 填寫不包含Bucket名稱在內(nèi)的Object完整路徑。關(guān)于Object名稱命名規(guī)范的更多信息，請(qǐng)參見Object。
get.objectKey = @"exampledir/exampleobject.txt";
NSMutableDictionary *headerFields = [NSMutableDictionary dictionary];
// 指定下載實(shí)際修改時(shí)間晚于Fri, 9 Apr 2021 14:47:53 GMT的Object。
[headerFields setValue:@"Fri, 13 Oct 2021 14:47:53 GMT" forKey:@"If-Modified-Since"];
// 指定下載實(shí)際修改時(shí)間早于或者等于當(dāng)前時(shí)間的Object。
[headerFields setValue:[[NSDate new] oss_asStringValue] forKey:@"If-Unmodified-Since"];
// 指定下載與傳入的ETag值不匹配的Object。
[headerFields setValue:@"5B3C1A2E0563E1B002CC607C****" forKey:@"If-None-Match"];
// 指定下載與傳入的ETag值匹配的Object。
[headerFields setValue:@"fba9dede5f27731c9771645a3986****" forKey:@"If-Match"];
get.headerFields = headerFields;

[[[_client getObject:get] continueWithBlock:^id _Nullable(OSSTask * _Nonnull task) {
    if (!task.error) {
        NSLog(@"get object success!");
    } else {
        NSLog(@"get object error: %@", task.error);
    }
    return nil;
}] waitUntilFinished];

相關(guān)文檔

• 如何在開啟了版本控制的Bucket中下載文件，請(qǐng)參見開啟版本控制下Object的操作。

• 如何在暫停了版本控制的Bucket中下載文件，請(qǐng)參見暫停版本控制下Object的操作。

• 為了防止第三方未經(jīng)授權(quán)從您的Bucket里下載數(shù)據(jù)，OSS提供了Bucket和Object級(jí)別的訪問權(quán)限控制。更多信息，請(qǐng)參見訪問控制概述。

• 如果您希望直接下載文件，您可以使用簡(jiǎn)單下載。具體操作，請(qǐng)參見簡(jiǎn)單下載。

• 如果您希望在下載大文件過程中，從下載中斷的位置繼續(xù)下載未完成的部分，您可以使用斷點(diǎn)續(xù)傳。具體操作，請(qǐng)參見斷點(diǎn)續(xù)傳下載。

• 如果您希望將私有Bucket的Object提供給第三方進(jìn)行下載，請(qǐng)通過STS臨時(shí)訪問憑證或簽名URL的方式授權(quán)第三方下載文件。具體操作，請(qǐng)參見授權(quán)給第三方下載。