Help Center/ Object Storage Service/ User Guide/ Object Management/ Uploading an Object/ Form-based Upload (POST)
Updated on 2026-08-21 GMT+08:00
View PDF
Share

Form-based Upload (POST)

Form-based upload (POST) lets you upload files smaller than 5 GB from a browser to an OBS bucket using an HTML form with a POST request. It is generally applicable to web applications and supports a wide range of scenarios:

  • User interaction and content generation: avatar and cover updates, rich-media publishing, social feed posting, user feedback, and work-order submission
  • Service records and data exchange: batch data import, certificate or material submission, and online assignment submission
  • Cloud storage integration: direct upload of client files to OBS

Form-based upload sends files straight from the browser to OBS. The upload bypasses your server, which can significantly reduce server load and effectively improve upload efficiency and stability.

OBS allows you to upload objects to buckets in a specified region, but Huawei Cloud does not inspect the content you upload. If your object uploads involve cross-border transfer, ensure that your use complies with relevant laws and regulations.

How It Works

OBS supports object uploads submitted through browser-based forms. The required signature information is included in the form fields. For a POST form-based upload, you define a security policy that specifies the allowed content and conditions of the upload. The client generates a signature using the SK and the security policy and then uploads the object directly to OBS. OBS verifies both the signature and the security policy and returns the upload result. This method does not support multipart uploads and is therefore unsuitable for large files or resumable upload. For details about signatures and security policies for form-based uploads, see Signing Form-based Upload Requests.

Figure 1 How form-based upload works
  1. The user defines a required security policy on the client. The client then generates a signature using the SK and the security policy.
  2. The client uses the signature and the security policy to upload the file to OBS through a form.
  3. OBS verifies the signature and the security policy and returns either a success or an error response.

Prerequisites

  • You have the write permissions to a bucket.
  • If you want to classify files, you can create folders and upload files to different folders. For details, see Creating Folders.

Limits

Size and number of objects

Object naming

  • For object naming rules, see Object Overview. Each object name in a bucket must be unique.
  • Object names containing special characters must be URL encoded. For example, #obj must be encoded as %23obj.

Important Notes

  • Prevent overwriting objects with the same name:
    • Versioning is not enabled for a bucket:
      • If you upload a new file with the same name as the one in the bucket, the new file will automatically overwrite the previous one and the ACL information of the previous file will not be retained.
      • If you upload a new folder with the same name as the one in the bucket, the two folders will be merged, and files in the new folder will overwrite those with the same name in the previous folder.
    • Versioning is enabled for a bucket: If you upload a new file with the same name as the one you previously uploaded to the bucket, a new file version will be added to the bucket. For details, see Versioning.

    You can configure a bucket policy to prevent objects with the same name from being overwritten. For details, see Bucket Policy Parameters and Creating a Custom Bucket Policy.

  • Authorize uploads:
    • To prevent unauthorized users from uploading files to a bucket, configure access control permissions so that only authorized users can upload files. For details, see POST Upload Authorization.

OBS manages partitions based on the UTF-8 encoding range of object names and implements horizontal expansion and dynamic load balancing accordingly. If you use sequential prefixes (sorted by timestamp or in alphabetical order) for object naming, object access requests may be concentrated in a specific partition, resulting in access hotspots. This limits the request rate in the hot partition and increases access latency.

Random prefixes are recommended for naming objects, so requests can be evenly distributed across partitions, achieving horizontal expansion.

Ways to Upload Objects

You can use APIs or SDKs to upload objects through a form.

Using APIs

Uploading an Object

Using SDKs

Java

Python

C: not supported

Go: not supported

BrowserJS

.NET: not supported

Android

iOS: not supported

PHP

Node.js

Logging and Monitoring

You can configure EG notifications for OBS:DWR:ObjectCreated:POST to automatically trigger follow-up operations. For more information, see Event Notifications.

Helpful Links

Parent Topic: Uploading an Object