簽名URL允許第三方用戶在沒有安全憑證或者授權的情況下進行上傳操作。第三方用戶使用簽名URL上傳文件后,OSS將在指定的Bucket生成該文件。
注意事項
生成PUT方法的簽名URL時,您必須具有
oss:PutObject
權限。具體操作,請參見RAM Policy常見示例。說明生成簽名URL過程中,SDK利用本地存儲的密鑰信息,根據特定算法計算出簽名(signature),然后將其附加到URL上,以確保URL的有效性和安全性。這一系列計算和構造URL的操作都是在客戶端完成,不涉及網絡請求到服務端。因此,生成簽名URL時不需要授予調用者特定權限。但是,為避免第三方用戶無法對簽名URL授權的資源執行相關操作,需要確保調用生成簽名URL接口的身份主體被授予對應的權限。
生成私有文件URL時涉及設置URL的有效時長。超出簽名URL設置的有效時長后,通過簽名URL上傳文件時會提示簽名URL已過期,導致無法正常上傳文件。如果您希望繼續使用簽名URL上傳文件,需要重新獲取簽名URL。
簽名URL上傳不支持上傳FormData格式,若需使用FormData上傳數據,建議使用OSS表單上傳。
操作步驟
生成簽名URL。
以下僅列舉常見SDK的生成簽名URL的代碼示例。關于其他SDK的生成簽名URL代碼示例,請參見SDK簡介。
Java
import com.aliyun.oss.*; import com.aliyun.oss.common.auth.*; import com.aliyun.oss.common.comm.SignVersion; import com.aliyun.oss.model.GeneratePresignedUrlRequest; import java.net.URL; import java.util.*; import java.util.Date; public class GetSignUrl { public static void main(String[] args) throws Throwable { // 以華東1(杭州)的外網Endpoint為例,其它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"; // 填寫Object完整路徑,例如exampleobject.txt。Object完整路徑中不能包含Bucket名稱。 String objectName = "exampleobject.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(); URL signedUrl = null; try { // 指定生成的簽名URL過期時間,單位為毫秒。本示例以設置過期時間為1小時為例。 Date expiration = new Date(new Date().getTime() + 3600 * 1000L); // 生成簽名URL。 GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, objectName, HttpMethod.PUT); // 設置過期時間。 request.setExpiration(expiration); // 通過HTTP PUT請求生成簽名URL。 signedUrl = ossClient.generatePresignedUrl(request); // 打印簽名URL。 System.out.println("signed url for putObject: " + signedUrl); } 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()); } } }
PHP
<?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; use OSS\Core\OssException; use OSS\Http\RequestCore; use OSS\Http\ResponseCore; // 運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 $provider = new EnvironmentVariableCredentialsProvider(); // yourEndpoint填寫Bucket所在地域對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。 $endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 填寫Bucket名稱。 $bucket= "examplebucket"; // 填寫不包含Bucket名稱在內的Object完整路徑。 $object = "exampleobject.txt"; // 設置簽名URL的有效時長為3600秒。 $timeout = 3600; try { $config = array( "provider" => $provider, "endpoint" => $endpoint, ); $ossClient = new OssClient($config); // 生成簽名URL。 $signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "PUT"); } catch (OssException $e) { printf(__FUNCTION__ . ": FAILED\n"); printf($e->getMessage() . "\n"); return; } print(__FUNCTION__ . ": signedUrl: " . $signedUrl . "\n");
Node.js
const OSS = require("ali-oss"); const { default: axios } = require("axios"); const fs = require("fs"); const client = new OSS({ // yourregion填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為oss-cn-hangzhou。 region: "oss-cn-hangzhou", // 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量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", }); // 生成文件的簽名URL。 const url = client.signatureUrl("exampleobject.txt", { method: "PUT", "Content-Type": "application/x-www-form-urlencoded", }); console.log(url);
Python
# -*- coding: utf-8 -*- import oss2 from oss2.credentials import EnvironmentVariableCredentialsProvider # 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider()) # 填寫Bucket所在地域對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。 endpoint = "https://oss-cn-hangzhou.aliyuncs.com" # 填寫Endpoint對應的Region信息,例如cn-hangzhou。注意,v4簽名下,必須填寫該參數 region = "cn-hangzhou" # yourBucketName填寫存儲空間名稱。 bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region) # 填寫Object完整路徑,例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。 object_name = 'exampledir/exampleobject.txt' # 生成上傳文件的簽名URL,有效時間為60秒。 # 生成簽名URL時,OSS默認會對Object完整路徑中的正斜線(/)進行轉義,從而導致生成的簽名URL無法直接使用。 # 設置slash_safe為True,OSS不會對Object完整路徑中的正斜線(/)進行轉義,此時生成的簽名URL可以直接使用。 url = bucket.sign_url('PUT', object_name, 60, slash_safe=True) print('簽名URL的地址為:', url)
Android
// 填寫Bucket名稱,例如examplebucket。 String bucketName = "examplebucket"; // 填寫不包含Bucket名稱在內源Object的完整路徑,例如exampleobject.txt。 String objectKey = "exampleobject.txt"; // 設置content-type。 String contentType = "application/octet-stream"; String url = null; try { // 生成用于上傳文件的簽名URL。 GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, objectKey); // 設置簽名URL的過期時間為30分鐘。 request.setExpiration(30*60); request.setContentType(contentType); request.setMethod(HttpMethod.PUT); url = oss.presignConstrainedObjectURL(request); Log.d("url", url); } catch (ClientException e) { e.printStackTrace(); }
Go
package main import ( "context" "flag" "log" "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(®ion, "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) // 生成PutObject的預簽名URL result, err := client.Presign(context.TODO(), &oss.PutObjectRequest{ Bucket: oss.Ptr(bucketName), Key: oss.Ptr(objectName), //ContentType: oss.Ptr("text/txt"), // 請確保在服務端生成該簽名URL時設置的ContentType與在使用URL時設置的ContentType一致 //Metadata: map[string]string{"key1": "value1", "key2": "value2"}, // 請確保在服務端生成該簽名URL時設置的Metadata與在使用URL時設置的Metadata一致 }, oss.PresignExpires(10*time.Minute), ) if err != nil { log.Fatalf("failed to put object presign %v", err) } log.Printf("request method:%v\n", result.Method) log.Printf("request expiration:%v\n", result.Expiration) log.Printf("request url:%v\n", result.URL) if len(result.SignedHeaders) > 0 { //當返回結果包含簽名頭時,使用簽名URL發送Put請求時,需要設置相應的請求頭 log.Printf("signed headers:\n") for k, v := range result.SignedHeaders { log.Printf("%v: %v\n", k, v) } } }
iOS
// 填寫Bucket名稱。 NSString *bucketName = @"examplebucket"; // 填寫Object名稱。 NSString *objectKey = @"exampleobject.txt"; NSURL *file = [NSURL fileURLWithPath:@"<filePath>"]; NSString *contentType = [OSSUtil detemineMimeTypeForFilePath:file.absoluteString uploadName:objectKey]; __block NSString *urlString; // 生成用于上傳的簽名URL,并指定簽名URL過期時間為30分鐘。 OSSTask *task = [client presignConstrainURLWithBucketName:bucketName withObjectKey:objectKey httpMethod:@"PUT" withExpirationInterval:30 * 60 withParameters:@{} contentType:contentType contentMd5:nil]; [task continueWithBlock:^id _Nullable(OSSTask * _Nonnull task) { if (task.error) { NSLog(@"presign error: %@", task.error); } else { urlString = task.result; NSLog(@"url: %@", urlString); } return nil; }];
使用簽名URL上傳文件。
以下僅列舉常見SDK使用簽名URL簡單上傳的代碼示例。關于其他SDK使用簽名URL簡單上傳的代碼示例,請參見SDK簡介。
Java
import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPut; import org.apache.http.entity.FileEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import java.io.*; import java.net.URL; import java.util.*; public class SignUrlUpload { public static void main(String[] args) throws Throwable { CloseableHttpClient httpClient = null; CloseableHttpResponse response = null; // 將<signedUrl>替換為授權URL。 URL signedUrl = new URL("<signedUrl>"); // 填寫本地文件的完整路徑。如果未指定本地路徑,則默認從示例程序所屬項目對應本地路徑中上傳文件。 String pathName = "C:\\Users\\demo.txt"; try { HttpPut put = new HttpPut(signedUrl.toString()); System.out.println(put); HttpEntity entity = new FileEntity(new File(pathName)); put.setEntity(entity); httpClient = HttpClients.createDefault(); response = httpClient.execute(put); System.out.println("返回上傳狀態碼:"+response.getStatusLine().getStatusCode()); if(response.getStatusLine().getStatusCode() == 200){ System.out.println("使用網絡庫上傳成功"); } System.out.println(response.toString()); } catch (Exception e){ e.printStackTrace(); } finally { response.close(); httpClient.close(); } } }
PHP
<?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\Http\RequestCore; use OSS\Http\ResponseCore; // 填寫步驟1生成的簽名URL。 $signedUrl = 'yourSignedUrl'; $content = "Hello OSS"; $request = new RequestCore($signedUrl); // 使用簽名URL上傳文件。 $request->set_method('PUT'); $request->add_header('Content-Type', ''); $request->add_header('Content-Length', strlen($content)); $request->set_body($content); $request->send_request(); $res = new ResponseCore($request->get_response_header(), $request->get_response_body(), $request->get_response_code()); if ($res->isOK()) { print(__FUNCTION__ . ": OK" . "\n"); } else { print(__FUNCTION__ . ": FAILED" . "\n"); };
Node.js
const OSS = require("ali-oss"); const { default: axios } = require("axios"); const fs = require("fs"); // 填寫步驟1生成的簽名URL。 const url = "yourSignedUrl"; // 指定本地文件的完整路徑。 const file = fs.readFileSync("D:\\examplefile.txt"); // 使用簽名URL上傳文件。 axios({ url, method: "PUT", data: file, }) .then((r) => console.log(r)) .catch((e) => console.log(e));
Python
import requests def upload_file(signed_url, file_path): try: # 打開文件 with open(file_path, 'rb') as file: # 發送PUT請求上傳文件 response = requests.put(signed_url, data=file) print(f"返回上傳狀態碼:{response.status_code}") if response.status_code == 200: print("使用網絡庫上傳成功") print(response.text) except Exception as e: print(f"發生錯誤:{e}") if __name__ == "__main__": # 將<signedUrl>替換為授權URL。 signed_url = "<signedUrl>" # 填寫本地文件的完整路徑。如果未指定本地路徑,則默認從示例程序所屬項目對應本地路徑中上傳文件。 file_path = "C:\\Users\\demo.txt" upload_file(signed_url, file_path)
Browser.js
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <title>Document</title> </head> <body> <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script> <script> // 填寫步驟1生成的簽名URL。 const url = "yourSignatureUrl"; var xhr = new XMLHttpRequest(); xhr.open("PUT", url, true); xhr.onload = function () { // 請求結束后,在此處編寫處理代碼。 }; // xhr.send(null); xhr.send("string"); // xhr.send(new Blob()); // xhr.send(new Int8Array()); // xhr.send({ form: 'data' }); // xhr.send(document); </script> </body> </html>
Android
// 填寫生成的簽名URL。 String url = ""; // 指定本地文件的完整路徑。 String localFile = "/storage/emulated/0/oss/examplefile"; // 設置content-type。 String contentType = "application/octet-stream"; // 通過簽名URL上傳文件。 OkHttpClient client = new OkHttpClient(); Request putRequest = new Request.Builder() .url(url) .put(RequestBody.create(MediaType.parse(contentType), new File(localFile))) .build(); client.newCall(putRequest).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { e.printStackTrace(); } @Override public void onResponse(Call call, Response response) throws IOException { Log.d("response", response.body().string()); } });
Go
package main import ( "fmt" "io" "net/http" "os" ) func uploadFile(signedUrl, filePath string) error { // 打開文件 file, err := os.Open(filePath) if err != nil { return fmt.Errorf("無法打開文件: %w", err) } defer file.Close() // 創建一個新的HTTP客戶端 client := &http.Client{} // 創建一個PUT請求 req, err := http.NewRequest("PUT", signedUrl, file) if err != nil { return fmt.Errorf("創建請求失敗: %w", err) } // 發送請求 resp, err := client.Do(req) if err != nil { return fmt.Errorf("發送請求失敗: %w", err) } defer resp.Body.Close() // 讀取響應 body, err := io.ReadAll(resp.Body) if err != nil { return fmt.Errorf("讀取響應失敗: %w", err) } fmt.Printf("返回上傳狀態碼: %d\n", resp.StatusCode) if resp.StatusCode == 200 { fmt.Println("使用網絡庫上傳成功") } fmt.Println(string(body)) return nil } func main() { // 將<signedUrl>替換為授權URL。 signedUrl := "<signedUrl>" // 填寫本地文件的完整路徑。如果未指定本地路徑,則默認從示例程序所屬項目對應本地路徑中上傳文件。 filePath := "C:\\Users\\demo.txt" err := uploadFile(signedUrl, filePath) if err != nil { fmt.Println("發生錯誤:", err) } }
iOS
// 通過簽名URL上傳文件。 NSURL * url = [NSURL URLWithString:urlString]; NSMutableURLRequest * request = [NSMutableURLRequest requestWithURL:url]; request.HTTPMethod = @"PUT"; request.allHTTPHeaderFields = @{OSSHttpHeaderContentType: contentType}; NSURLSession * session = [NSURLSession sharedSession]; NSURLSessionTask * sessionTask = [session uploadTaskWithRequest:request fromFile:file completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) { if (error) { NSLog(@"upload error: %@", error); return; } else if (((NSHTTPURLResponse*)response).statusCode == 203 || ((NSHTTPURLResponse*)response).statusCode >= 300) { NSString *body = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]; NSLog(@"upload error: %@", body); return; } NSLog(@"upload success"); }]; [sessionTask resume];
相關文檔
當您希望使用簽名URL以分片上傳的方式上傳大文件到OSS時,您需要先初始化分片上傳,然后把每一個分片生成一個對應的上傳簽名URL,并返回給第三方應用。第三方應用可以使用這些簽名URL上傳所有的分片信息,然后合并分片來達到通過簽名URL實現分片上傳的目的。關于生成分片上傳的簽名URL以及使用簽名URL臨時授權分片上傳的代碼示例,請參見使用簽名URL下載。