Object Storage Service：限定最後修改時間或ETag下載OSS檔案

前提條件

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

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

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

• 已具有oss:GetObject許可權。具體操作，請參見RAM Policy常見樣本。

使用情境

• 應用資源更新：應用僅在檢測到OSS檔案ETag變更或最後修改時間更新時下載新資源，最小化資料使用，最佳化使用者體驗。

• 資料同步與增量備份：基於OSS的最後修改時間或ETag，確保只同步或備份更改過的檔案，節省頻寬，保障資料的時效性和一致性。

• 檔案分享權限設定和同步：使用ETag或最後修改時間進行驗證，僅在必要時同步檔案，加速協作，降低資料消耗。

限定條件

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請按實際情況填寫。
        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";
        String pathName = "D:\\localpath\\examplefile.txt";

        // 建立OSSClient執行個體。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            // 假設Object最後修改時間為2023年9月26日13:27:04，當填寫早於該時間的Data對象時（例如Tue Sep 25 13:27:04 CST 2023），將滿足If-Modified-Since的限定條件，並觸發下載行為。
            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;

// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州為例，其它Region請按實際情況填寫。
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket名稱。
$bucket= "yourBucketName";
// 填寫Object名稱。Object名稱為不包含Bucket名稱在內的Object的完整路徑，例如exampledir/exampleobject.txt。
$object = "yourObjectName";
// 填寫本地檔案的完整路徑。例如D:\\localpath\\examplefile.txt。
$localfile = "yourLocalFile";

try{
    $options = array(
        OssClient::OSS_HEADERS => array(          
           // 指定下載實際修改時間晚於Fri, 9 Apr 2021 14:47:53 GMT的Object。
          OssClient::OSS_IF_MODIFIED_SINCE => "Fri, 9 Apr 2021 14:47:53 GMT",
          // 指定下載實際修改時間早於或者等於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填寫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,
  // 填寫Bucket名稱。
  bucket: 'examplebucket'
});

async function main() {
  try {
    // 向目標Bucket上傳名為exampleobject.txt的檔案，檔案內容自訂。
    await client.put("exampleobject.txt", Buffer.from("contenttest"));
    // 在要求標頭If-Modified-Since中指定時間，如果指定的時間早於檔案實際修改時間，則下載檔案。
    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);

    // 如果指定的時間等於或者晚於檔案實際修改時間，則返回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

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫Bucket名稱，例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填寫不包含Bucket名稱在內的Object完整路徑，例如exampledir/exampleobject.txt。關於Object名稱命名規範的更多資訊，請參見Object。
object_name = 'exampledir/exampleobject.txt'

headers = dict()
# 如果指定的時間早於Object實際修改時間，則正常下載Object，否則返回錯誤304 Not modified。
headers['If-Modified-Since'] = 'Mon, 13 Dec 2021 14:47:53 GMT'
# 如果指定的時間等於或者晚於Object實際修改時間，則正常下載Object，否則返回錯誤412 Precondition failed。
# headers['If-Unmodified-Since'] = 'Mon, 13 Dec 2021 14:47:53 GMT'
# 如果傳入的ETag和Object的ETag匹配，則正常下載Object，否則返回錯誤412 Precondition failed。
# headers['If-Match'] = 'DC21493F505BA3739562D8CC452C****'
# 如果傳入的ETag值和Object的ETag不匹配，則正常下載Object，否則返回錯誤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>
    <!--匯入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填寫Bucket所在地區。以華東1（杭州）為例，yourRegion填寫為oss-cn-hangzhou。
         region: 'yourRegion',
         // 從STS服務擷取的臨時存取金鑰（AccessKey ID和AccessKey Secret）。
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // 從STS服務擷取的安全性權杖（SecurityToken）。
        stsToken: 'yourSecurityToken',
        // 填寫Bucket名稱，例如examplebucket。
        bucket: "examplebucket",
      });

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

    // 上傳檔案。  
    upload.addEventListener('click', () => {
      // 指定待上傳的檔案內容。
      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', () => {
      // 指定待下載的位元組範圍。
      const start = 1, end = 5
      client.get('exampledir/exampleobject.txt', {
        headers: {
          // 在要求標頭If-Modified-Since中指定時間，如果指定的時間早於檔案實際修改時間，則下載檔案。如果指定的時間等於或者晚於檔案實際修改時間，則返回304 Not Modified。
          "If-Modified-Since": new Date("1970-01-01").toGMTString()
          // 在要求標頭If-Unmodified-Since中指定時間，如果指定的時間等於或者晚於檔案實際修改時間，則下載檔案。如果指定的時間早於檔案實際修改時間，則返回412 Precondition Failed。
          //"If-Unmodified-Since": new Date(1970-01-01).toGMTString()
          // 在要求標頭If-Match中傳入ETag，如果傳入的ETag和檔案的ETag匹配，則下載檔案。如果傳入的ETag和檔案的ETag不匹配，則返回412 Precondition Failed。
          //"If-Match": '5B3C1A2E0563E1B002CC607C****'
          // 在要求標頭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('錯誤碼', r.res.status)
          console.log('沒有合格下載項')
        }
      })
    })

  </script>
</body>

</html>

// 依次填寫Bucket名稱（例如examplebucket）、Object完整路徑（例如exampledir/exampleobject.txt）。
// Object完整路徑中不能包含Bucket名稱。
String bucketName = "examplebucket";
String objectKey = "exampledir/exampleobject.txt";
// 構造下載檔案請求。
Map<String, String> headers = new HashMap<>();
// 如果指定的時間早於實際修改時間，則正常傳輸檔案，否則返回錯誤（304 Not modified）。
headers.put(OSSHeaders.GET_OBJECT_IF_MODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// 如果指定的時間等於或者晚於檔案實際修改時間，則正常傳輸檔案，否則返回錯誤（412 Precondition failed）
// headers.put(OSSHeaders.GET_OBJECT_IF_UNMODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// 如果指定的ETag和OSS檔案的ETag匹配，則正常傳輸檔案，否則返回錯誤（412 Precondition failed）
// headers.put(OSSHeaders.GET_OBJECT_IF_MATCH, "5B3C1A2E0563E1B002CC607C*****");
// 如果指定的ETag和OSS檔案的ETag不匹配，則正常傳輸檔案，否則返回錯誤（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) {
        // 請求成功。
        InputStream inputStream = result.getObjectContent();
        byte[] buffer = new byte[2048];
        int len;
        try {
            while ((len = inputStream.read(buffer)) != -1) {
                // 處理下載的資料。
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFailure(GetObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // 請求異常。
        if (clientExcepion != null) {
            // 本地異常如網路異常等。
            clientExcepion.printStackTrace();
        }
        if (serviceException != null) {
            // 服務異常。
            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() {
    // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 建立OSSClient執行個體。
    // yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

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

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

    // 不滿足限定條件，不下載檔案。
    // yourObjectName填寫不包含Bucket名稱在內的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];
// 填寫Bucket名稱。關於Bucket名稱命名規範的更多資訊，請參見Bucket。
get.bucketName = @"examplebucket";
// 填寫不包含Bucket名稱在內的Object完整路徑。關於Object名稱命名規範的更多資訊，請參見Object。
get.objectKey = @"exampledir/exampleobject.txt";
NSMutableDictionary *headerFields = [NSMutableDictionary dictionary];
// 指定下載實際修改時間晚於Fri, 9 Apr 2021 14:47:53 GMT的Object。
[headerFields setValue:@"Fri, 13 Oct 2021 14:47:53 GMT" forKey:@"If-Modified-Since"];
// 指定下載實際修改時間早於或者等於目前時間的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];

相關文檔

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

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

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

• 如果您希望直接下載檔案，您可以使用簡單下載。具體操作，請參見簡單下載。

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

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