By default, the access control list (ACL) of an Object Storage Service (OSS) object in a bucket is private. Only the object owner has the permissions to upload an object to the bucket. You can use OSS SDK for Python to generate a presigned URL and share the presigned URL with a user to allow the user to upload an object. When you generate a presigned URL, you can specify the validity period of the presigned URL to limit the period of time during which the user can upload an object. During the validity period of the presigned URL, the user can use the URL to upload an object to the bucket multiple times. If you upload an object multiple times, the uploaded object may be overwritten. After the validity period of the presigned URL ends, the user cannot use the presigned URL to upload an object. In this case, you must generate a new presigned URL.
Usage notes
The sample code in this topic uses the region ID
cn-hangzhou
of the China (Hangzhou) region. By default, a public endpoint is used to access resources in a bucket. If you want to access resources in the bucket by using other Alibaba Cloud services in the same region in which the bucket is located, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.You do not need specific permissions to generate a presigned URL. However, to allow others to use the presigned URL for uploading an object, you must have the
oss:PutObject
permission. For more information, see Authorize a RAM user to access multiple directories in a bucket.In this topic, presigned URLs that include V4 signatures and have a validity period of up to seven days are used. For more information, see (Recommended) Include a V4 signature in a URL.
Process
The following figure shows how to use a presigned URL that allows HTTP PUT requests to upload an object to OSS.
Method
You can call a specific operation to generate a presigned URL and use the presigned URL to grant temporary access permissions on objects in a bucket. You can use the signed URL multiple times before the URL expires.
Syntax:
presign(request: PutObjectRequest, **kwargs) → PresignResult
Request parameters
Parameter | Type | Description |
request | PutObjectRequest | The API operation used to generate a presigned URL. For more information, see Client.presign. |
expires | datetime.timedelta | The validity period of the presigned URL. This is an optional parameter. For example, if you want to set the validity period to 30 minutes, set expires to 30 * time.Minute. If you do not specify this parameter, the presigned URL uses the default value, which is 15 minutes. |
expiration | datetime.datetime | The absolute expiration time of the presigned URL. This is an optional parameter. |
If you use the V4 signature algorithm, the validity period can be up to seven days. If you specify both Expiration and Expires, Expiration takes precedence.
Response parameters
Type | Description |
PresignResult | The returned results, including the presigned URL, HTTP method, expiration time, and request headers specified in the request. For more information, see PresignResult. |
Response parameters of PresignResult
Parameter | Type | Description |
method | str | The HTTP method, which corresponds to the API operation. For example, the HTTP method of the PutObject operation is PUT. |
url | str | The presigned URL. |
expiration | datetime | The expiration time of the presigned URL. |
signed_headers | MutableMapping | The signed headers specified in the request. For example, if Content-Type is specified, information about Content-Type is returned. |
For the more information about the presign method, visit presign.
Sample code
Generate a presigned URL that allows HTTP PUT requests.
ImportantIf you specify request headers when you generate a presigned URL that allows HTTP PUT requests, make sure that the request headers are included in the PUT request initiated by using the presigned URL. This prevents request failures and signature errors.
import argparse import requests import alibabacloud_oss_v2 as oss from datetime import datetime, timedelta # Create a command line parameter parser and describe the purpose of the script. The example describes how to generate a presigned URL that allows HTTP PUT requests. parser = argparse.ArgumentParser(description="presign put object sample") # Specify the command line parameters, including the required region, bucket name, endpoint, and object name. parser.add_argument('--region', help='The region in which the bucket is located.', required=True) parser.add_argument('--bucket', help='The name of the bucket.', required=True) parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS') parser.add_argument('--key', help='The name of the object.', required=True) def main(): # Parse the command line parameters to obtain the values specified by the user. args = parser.parse_args() # Obtain access credentials from environment variables for authentication. credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider() # Use the default configurations of the SDK to create a configuration object and specify the credential provider. cfg = oss.config.load_default() cfg.credentials_provider = credentials_provider # Specify the region attribute of the configuration object based on the command line parameters specified by the user. cfg.region = args.region # If a custom endpoint is provided, modify the endpoint parameter in the configuration object. if args.endpoint is not None: cfg.endpoint = args.endpoint # Use the preceding configurations to initialize the OSSClient instance and allow the instance to interact with OSS. client = oss.Client(cfg) # Send the request to initiate a PUT request and generate a presigned URL for the specified object. pre_result = client.presign(oss.PutObjectRequest( bucket=args.bucket, # The name of the bucket. key=args.key, # The name of the object. ),expires=timedelta(seconds=3600)) # Specify the validity period of the request. In this example, the validity period is set to 3,600 seconds. # Display the method, expiration time, and presigned URL specified in the request to check the validity of the presigned 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}' ) # Display the signed headers in the request, which are included in the HTTP header when the request is sent. for key, value in pre_result.signed_headers.items(): print(f'signed headers key: {key}, signed headers value: {value}') # Call the main function to start the processing logic when the script is directly run. if __name__ == "__main__": main() # Specify the entry points in the functions of the script. The control program flow starts here.
Use the presigned URL that allows HTTP PUT requests to upload an object.
curl
curl -X PUT -T /path/to/local/file "https://exampleobject.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T083238Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************%2F20241112%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=ed5a******************************************************"
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; // Replace <signedUrl> with the presigned URL. URL signedUrl = new URL("<signedUrl>"); // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. 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("Status code:"+response.getStatusLine().getStatusCode()); if(response.getStatusLine().getStatusCode() == 200){ System.out.println("The object is uploaded by using the library."); } System.out.println(response.toString()); } catch (Exception e){ e.printStackTrace(); } finally { response.close(); httpClient.close(); } } }
Go
package main import ( "fmt" "io" "net/http" "os" ) func uploadFile(signedUrl, filePath string) error { // Open the local file. file, err := os.Open(filePath) if err != nil { return fmt.Errorf("Unable to open the local file: %w", err) } defer file.Close() // Create an HTTP client. client := &http.Client{} // Create a PUT request. req, err := http.NewRequest("PUT", signedUrl, file) if err != nil { return fmt.Errorf("Failed to create the request: %w", err) } // Send the request. resp, err := client.Do(req) if err != nil { return fmt.Errorf("Failed to send the request:: %w", err) } defer resp.Body.Close() // Read the response. body, err := io.ReadAll(resp.Body) if err != nil { return fmt.Errorf("Failed to read the request: %w", err) } fmt.Printf("Status code: %d\n", resp.StatusCode) if resp.StatusCode == 200 { fmt.Println("The object is uploaded by using the library.") } fmt.Println(string(body)) return nil } func main() { // Replace <signedUrl> with the presigned URL. signedUrl := "<signedUrl>" // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. filePath := "C:\\Users\\demo.txt" err := uploadFile(signedUrl, filePath) if err != nil { fmt.Println("An error occurred: ", err) } }
python
import requests def upload_file(signed_url, file_path): try: # Open the local file that you want to upload. with open(file_path, 'rb') as file: # Send a PUT request to upload the local file. response = requests.put(signed_url, data=file) print(f"Status code: {response.status_code}") if response.status_code == 200: print("The object is uploaded by using the library.") print(response.text) except Exception as e: print(f"An error occurred: {e}") if __name__ == "__main__": # Replace <signedUrl> with the generated signed URL. signed_url = "<signedUrl>" # Specify the full path of the local file. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. file_path = "C:\\Users\\demo.txt" upload_file(signed_url, file_path)
Node.js
const fs = require('fs'); const axios = require('axios'); async function uploadFile(signedUrl, filePath) { try { // Create a read stream. const fileStream = fs.createReadStream(filePath); // Send a PUT request to upload the local file. const response = await axios.put(signedUrl, fileStream, { headers: { 'Content-Type': 'application/octet-stream' // Specify the Content-Type parameter. } }); console.log(`Status code: ${response.status}`); if (response.status === 200) { console.log("The object is uploaded by using the library."); } console.log(response.data); } catch (error) { console.error(`An error occurred: ${error.message}`); } } // Specify the main function. (async () => { // Replace <signedUrl> with the presigned URL. const signedUrl = '<signedUrl>'; // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. const filePath = 'C:\\Users\\demo.txt'; await uploadFile(signedUrl, filePath); })();
browser.js
ImportantWhen uploading an object using Browser.js and a presigned URL, a 403 SignatureNotMatch error that indicates signature inconsistency may occur. This is typically caused by the browser's automatic inclusion of the Content-Type request header, which that was not specified when the presigned URL was generated. To prevent this error, ensure that the Content-Type header is specified when generating a presigned URL.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>File Upload Example</title> </head> <body> <h1>File Upload Example</h1> <! -- Select File --> <input type="file" id="fileInput" /> <button id="uploadButton">Upload File</button> <script> // Replace <signedUrl> with the presigned URL that was generated in Step 1. const signedUrl = "<signedUrl>"; document.getElementById('uploadButton').addEventListener('click', async () => { const fileInput = document.getElementById('fileInput'); const file = fileInput.files[0]; if (!file) { alert('Please select a file to upload.'); return; } try { await upload(file, signedUrl); alert('File uploaded successfully!'); } catch (error) { console.error('Error during upload:', error); alert('Upload failed: ' + error.message); } }); /** * Upload a file to OSS. * @param {File} file - The file to be uploaded. * @param {string} presignedUrl - The presigned URL. */ const upload = async (file, presignedUrl) => { const response = await fetch(presignedUrl, { method: 'PUT', body: file, // Upload the entire file. }); if (!response.ok) { throw new Error(`Upload failed, status: ${response.status}`); } console.log('File uploaded successfully'); }; </script> </body> </html>
C#
using System.Net.Http.Headers; // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. var filePath = "C:\\Users\\demo.txt"; // Replace <signedUrl> with the presigned URL. var presignedUrl = "<signedUrl>"; // Create an HTTP client and a local file stream. using var httpClient = new HttpClient(); using var fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read); using var content = new StreamContent(fileStream); // Create a PUT request. var request = new HttpRequestMessage(HttpMethod.Put, presignedUrl); request.Content = content; // Send a request. var response = await httpClient.SendAsync(request); // Process the response. if (response.IsSuccessStatusCode) { Console.WriteLine($"Uploaded! Status Code: {response.StatusCode}"); Console.WriteLine("Response Header:"); foreach (var header in response.Headers) { Console.WriteLine($"{header.Key}: {string.Join(", ", header.Value)}"); } } else { string responseContent = await response.Content.ReadAsStringAsync(); Console.WriteLine($"Upload Failed! Status Code: {response.StatusCode}"); Console.WriteLine("Response content: " + responseContent); }
C++
#include <iostream> #include <fstream> #include <curl/curl.h> void uploadFile(const std::string& signedUrl, const std::string& filePath) { CURL *curl; CURLcode res; curl_global_init(CURL_GLOBAL_DEFAULT); curl = curl_easy_init(); if (curl) { // Specify the presigned URL. curl_easy_setopt(curl, CURLOPT_URL, signedUrl.c_str()); // Set the request method to PUT. curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); // Open the local file. FILE *file = fopen(filePath.c_str(), "rb"); if (!file) { std::cerr << "Unable to open the file: " << filePath << std::endl; return; } // Query the size of the local file. fseek(file, 0, SEEK_END); long fileSize = ftell(file); fseek(file, 0, SEEK_SET); // Specify the size of the local file. curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fileSize); // Specify the input file handle. curl_easy_setopt(curl, CURLOPT_READDATA, file); // Execute the request. res = curl_easy_perform(curl); if (res != CURLE_OK) { std::cerr << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl; } else { long httpCode = 0; curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &httpCode); std::cout << "Status code: " << httpCode << std::endl; if (httpCode == 200) { std::cout << "The object is uploaded by using the network library." << std::endl; } } // Close the local file. fclose(file); // Clear the cURL handle. curl_easy_cleanup(curl); } curl_global_cleanup(); } int main() { // Replace <signedUrl> with the presigned URL. std::string signedUrl = "<signedUrl>"; // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. std::string filePath = "C:\\Users\\demo.txt"; uploadFile(signedUrl, filePath); return 0; }
Android
package com.example.signurlupload; import android.os.AsyncTask; import android.util.Log; import java.io.DataOutputStream; import java.io.FileInputStream; import java.io.IOException; import java.net.HttpURLConnection; import java.net.URL; public class SignUrlUploadActivity { private static final String TAG = "SignUrlUploadActivity"; public void uploadFile(String signedUrl, String filePath) { new UploadTask().execute(signedUrl, filePath); } private class UploadTask extends AsyncTask<String, Void, String> { @Override protected String doInBackground(String... params) { String signedUrl = params[0]; String filePath = params[1]; HttpURLConnection connection = null; DataOutputStream dos = null; FileInputStream fis = null; try { URL url = new URL(signedUrl); connection = (HttpURLConnection) url.openConnection(); connection.setRequestMethod("PUT"); connection.setDoOutput(true); connection.setRequestProperty("Content-Type", "application/octet-stream"); fis = new FileInputStream(filePath); dos = new DataOutputStream(connection.getOutputStream()); byte[] buffer = new byte[1024]; int length; while ((length = fis.read(buffer)) != -1) { dos.write(buffer, 0, length); } dos.flush(); dos.close(); fis.close(); int responseCode = connection.getResponseCode(); Log.d(TAG, "Status code: " + responseCode); if (responseCode == 200) { Log.d(TAG, "The object is uploaded by using the library."); } return "Object uploaded. Status code: " + responseCode; } catch (IOException e) { e.printStackTrace(); return "Upload failed: " + e.getMessage(); } finally { if (connection != null) { connection.disconnect(); } } } @Override protected void onPostExecute(String result) { Log.d(TAG, result); } } public static void main(String[] args) { SignUrlUploadActivity activity = new SignUrlUploadActivity(); // Replace <signedUrl> with the presigned URL. String signedUrl = "<signedUrl>"; // Specify the full path of the local file that you want to upload. If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. String filePath = "C:\\Users\\demo.txt"; activity.uploadFile(signedUrl, filePath); } }
Common scenarios
Use a presigned URL that contains specific request headers and user metadata to upload an object
Use a presigned URL to upload an object by using multipart upload
Use a presigned URL to upload an object and set upload callback parameters
FAQ
When I use a signed URL to upload a local file, is the file uploaded if the signed URL expires during the upload?
If I do not specify request headers and user metadata when I generate a URL, do I need to specify request headers and user metadata when I use the URL to upload a local file?
References
For the complete sample code that is used to upload an object by using a presigned URL, visit presigner_put_object.py.
For the complete sample code for using presigned URLs to upload an object by using multipart upload, see presigner_complete_multipart_upload.py.