Object Storage Service：使用預簽名URL下載（Python SDK V2）

注意事項

• 本文範例程式碼以華東1（杭州）的地區IDcn-hangzhou為例，預設使用外網Endpoint，如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。

• 預簽名URL無需許可權即可產生，但僅當您擁有oss:GetObject許可權時，第三方才能通過該預簽名URL成功下載檔案。具體授權操作，請參見為RAM使用者授權自訂的權限原則。

• 本文範例程式碼使用V4預簽名URL，有效期間最大為7天。更多資訊，請參見簽名版本4（推薦）。

使用過程

使用預簽名URL下載檔案的過程如下：

方法定義

您可以使用預簽名介面產生預簽名URL，授予對儲存空間中對象的限時存取權限。在到期時間之前，您可以多次使用預簽名URL。

預簽名URL方法定義如下：

presign(request: GetObjectRequest, **kwargs) → PresignResult

請求參數列表

傳回值列表

其中，PresignResult傳回值列舉如下：

關於預簽名方法的完整定義，請參見presign。

範例程式碼

1. 檔案擁有者產生GET方法的預簽名URL。

   import argparse
   import alibabacloud_oss_v2 as oss
   
   # 建立一個命令列參數解析器，並描述指令碼用途：產生GET方法的預簽名URL請求樣本
   parser = argparse.ArgumentParser(description="presign 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，表示對象（檔案）在OSS中的鍵名，必需參數
   parser.add_argument('--key', help='The name of the object.', required=True)
   
   def main():
       # 解析命令列提供的參數，擷取使用者輸入的值
       args = parser.parse_args()
   
       # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
       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用戶端，準備與OSS互動
       client = oss.Client(cfg)
   
       # 產生預簽名的GET請求
       pre_result = client.presign(
           oss.GetObjectRequest(
               bucket=args.bucket,  # 指定儲存空間名稱
               key=args.key,        # 指定對象鍵名
           )
       )
   
       # 列印預簽章要求的方法、到期時間和URL
       print(f'method: {pre_result.method},'
             f' expiration: {pre_result.expiration.strftime("%Y-%m-%dT%H:%M:%S.000Z")},'
             f' url: {pre_result.url}'
       )
   
       # 列印預簽章要求的已簽名頭資訊
       for key, value in pre_result.signed_headers.items():
           print(f'signed headers key: {key}, signed headers value: {value}')
   
   # 當此指令碼被直接執行時，調用main函數開始處理邏輯
   if __name__ == "__main__":
       main()  # 指令碼進入點，控製程序流程從這裡開始

2. 其他人使用GET方法的預簽名URL下載檔案。

   curl

   curl -SO "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************"

   Java

   import java.io.BufferedInputStream;
   import java.io.FileOutputStream;
   import java.io.IOException;
   import java.io.InputStream;
   import java.net.HttpURLConnection;
   import java.net.URL;
   
   public class Demo {
       public static void main(String[] args) {
           // 替換為產生的GET方法的預簽名URL。
           String fileURL = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************";
           // 填寫檔案儲存的目標路徑，包括檔案名稱和副檔名。
           String savePath = "C:/downloads/myfile.txt";
   
           try {
               downloadFile(fileURL, savePath);
               System.out.println("Download completed!");
           } catch (IOException e) {
               System.err.println("Error during download: " + e.getMessage());
           }
       }
   
       private static void downloadFile(String fileURL, String savePath) throws IOException {
           URL url = new URL(fileURL);
           HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
           httpConn.setRequestMethod("GET");
   
           // 檢查響應代碼
           int responseCode = httpConn.getResponseCode();
           if (responseCode == HttpURLConnection.HTTP_OK) {
               // 輸入資料流
               InputStream inputStream = new BufferedInputStream(httpConn.getInputStream());
               // 輸出資料流
               FileOutputStream outputStream = new FileOutputStream(savePath);
   
               byte[] buffer = new byte[4096]; // 緩衝區
               int bytesRead;
               while ((bytesRead = inputStream.read(buffer)) != -1) {
                   outputStream.write(buffer, 0, bytesRead);
               }
   
               outputStream.close();
               inputStream.close();
           } else {
               System.out.println("No file to download. Server replied HTTP code: " + responseCode);
           }
           httpConn.disconnect();
       }
   }

   Node.js

   const https = require('https');
   const fs = require('fs');
   
   const fileURL = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************";
   const savePath = "C:/downloads/myfile.txt";
   
   https.get(fileURL, (response) => {
       if (response.statusCode === 200) {
           const fileStream = fs.createWriteStream(savePath);
           response.pipe(fileStream);
           
           fileStream.on('finish', () => {
               fileStream.close();
               console.log("Download completed!");
           });
       } else {
           console.error(`Download failed. Server responded with code: ${response.statusCode}`);
       }
   }).on('error', (err) => {
       console.error("Error during download:", err.message);
   });

   Python

   import requests
   
   file_url = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************"
   save_path = "C:/downloads/myfile.txt"
   
   try:
       response = requests.get(file_url, stream=True)
       if response.status_code == 200:
           with open(save_path, 'wb') as f:
               for chunk in response.iter_content(4096):
                   f.write(chunk)
           print("Download completed!")
       else:
           print(f"No file to download. Server replied HTTP code: {response.status_code}")
   except Exception as e:
       print("Error during download:", e)

   Go

   package main
   
   import (
       "io"
       "net/http"
       "os"
   )
   
   func main() {
       fileURL := "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************"
       savePath := "C:/downloads/myfile.txt"
   
       response, err := http.Get(fileURL)
       if err != nil {
           panic(err)
       }
       defer response.Body.Close()
   
       if response.StatusCode == http.StatusOK {
           outFile, err := os.Create(savePath)
           if err != nil {
               panic(err)
           }
           defer outFile.Close()
   
           _, err = io.Copy(outFile, response.Body)
           if err != nil {
               panic(err)
           }
           println("Download completed!")
       } else {
           println("No file to download. Server replied HTTP code:", response.StatusCode)
       }
   }

   JavaScript

   const fileURL = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************";
   const savePath = "C:/downloads/myfile.txt"; // 檔案將在下載時使用的檔案名稱
   
   fetch(fileURL)
       .then(response => {
           if (!response.ok) {
               throw new Error(`Server replied HTTP code: ${response.status}`);
           }
           return response.blob(); // 將響應轉換為 blob
       })
       .then(blob => {
           const link = document.createElement('a');
           link.href = window.URL.createObjectURL(blob);
           link.download = savePath; // 設定下載檔案的名字
           document.body.appendChild(link); // 此步驟確保連結存在於文檔中
           link.click(); // 類比點擊下載連結
           link.remove(); // 完成後移除連結
           console.log("Download completed!");
       })
       .catch(error => {
           console.error("Error during download:", error);
       });

   Android-Java

   import android.os.AsyncTask;
   import android.os.Environment;
   import java.io.BufferedInputStream;
   import java.io.FileOutputStream;
   import java.io.InputStream;
   import java.net.HttpURLConnection;
   import java.net.URL;
   
   public class DownloadTask extends AsyncTask<String, String, String> {
       @Override
       protected String doInBackground(String... params) {
           String fileURL = params[0];
           String savePath = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS) + "/myfile.txt"; // 修改後的儲存路徑
           try {
               URL url = new URL(fileURL);
               HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
               httpConn.setRequestMethod("GET");
               int responseCode = httpConn.getResponseCode();
               if (responseCode == HttpURLConnection.HTTP_OK) {
                   InputStream inputStream = new BufferedInputStream(httpConn.getInputStream());
                   FileOutputStream outputStream = new FileOutputStream(savePath);
                   byte[] buffer = new byte[4096];
                   int bytesRead;
                   while ((bytesRead = inputStream.read(buffer)) != -1) {
                       outputStream.write(buffer, 0, bytesRead);
                   }
                   outputStream.close();
                   inputStream.close();
                   return "Download completed!";
               } else {
                   return "No file to download. Server replied HTTP code: " + responseCode;
               }
           } catch (Exception e) {
               return "Error during download: " + e.getMessage();
           }
       }
   }

   Objective-C

   #import <Foundation/Foundation.h>
   
   int main(int argc, const char * argv[]) {
       @autoreleasepool {
           // 定義檔案 URL 和儲存路徑（修改為有效路徑）
           NSString *fileURL = @"https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T092756Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************/20241112/cn-hangzhou/oss/aliyun_v4_request&x-oss-signature=ed5a******************************************************";
           NSString *savePath = @"/Users/your_username/Desktop/myfile.txt"; // 請替換為您的使用者名稱
           
           // 建立 URL 對象
           NSURL *url = [NSURL URLWithString:fileURL];
           
           // 建立下載任務
           NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithURL:url completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
               // 錯誤處理
               if (error) {
                   NSLog(@"Error during download: %@", error.localizedDescription);
                   return;
               }
               
               // 檢查資料
               if (!data) {
                   NSLog(@"No data received.");
                   return;
               }
               
               // 儲存檔案
               NSError *writeError = nil;
               BOOL success = [data writeToURL:[NSURL fileURLWithPath:savePath] options:NSDataWritingAtomic error:&writeError];
               if (success) {
                   NSLog(@"Download completed!");
               } else {
                   NSLog(@"Error saving file: %@", writeError.localizedDescription);
               }
           }];
           
           // 啟動任務
           [task resume];
           
           // 讓主線程繼續運行以便非同步請求能夠完成
           [[NSRunLoop currentRunLoop] run];
       }
       return 0;
   }

常見使用情境

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：產生GET方法的預簽名URL請求樣本
parser = argparse.ArgumentParser(description="presign 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，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    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用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 產生預簽名的GET請求
    # 注意：version_id 參數是可選的，僅當您的儲存桶啟用了版本控制時才需要使用
    pre_result = client.presign(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定儲存空間名稱
            key=args.key,        # 指定對象鍵名
            version_id='yourVersionId'  # 替換為實際的版本ID，如果適用
        )
    )

    # 列印預簽章要求的方法、到期時間和URL
    print(f'method: {pre_result.method},'
          f' expiration: {pre_result.expiration.strftime("%Y-%m-%dT%H:%M:%S.000Z")},'
          f' url: {pre_result.url}'
    )

    # 列印預簽章要求的已簽名頭資訊
    for key, value in pre_result.signed_headers.items():
        print(f'signed headers key: {key}, signed headers value: {value}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：產生預簽名GET請求樣本
parser = argparse.ArgumentParser(description="presign 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，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的預設配置建立設定物件，並設定認證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 設定設定物件的地區屬性，根據使用者提供的命令列參數
    cfg.region = args.region

    # 設定自訂網域名，例如“http://static.example.com”
    cfg.endpoint = "http://static.example.com"
    
    # 設定使用CNAME
    cfg.use_cname = True

    # 使用上述配置初始化OSS用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 產生預簽名的GET請求
    pre_result = client.presign(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定儲存空間名稱
            key=args.key,        # 指定對象鍵名
        )
    )

    # 列印預簽章要求的方法、到期時間和URL
    print(f'method: {pre_result.method},'
          f' expiration: {pre_result.expiration.strftime("%Y-%m-%dT%H:%M:%S.000Z")},'
          f' url: {pre_result.url}'
    )

    # 列印預簽章要求的已簽名頭資訊
    for key, value in pre_result.signed_headers.items():
        print(f'signed headers key: {key}, signed headers value: {value}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

相關文檔

• 關於使用預簽名URL下載的完整範例程式碼，請參見presigner_get_object.py。