Uploading an Object - File-Based (SDK for Java)
Function
This API uploads local files to OBS over the Internet. The file to be uploaded can be of any type.
If you have any questions during development, post them on the Issues page of GitHub.
Restrictions
- To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
- The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
- The object size in a single upload ranges from 0 to 5 GB.
- To upload files larger than 5 GB, multipart uploads should be used.
Method
obsClient.putObject(PutObjectRequest request)
Request Parameters
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
request |
Yes |
Explanation: Request parameters for uploading an object. For details, see Table 2. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
bucketName |
String |
Yes |
Explanation: Bucket name. Restrictions:
Default value: None |
objectKey |
String |
Yes |
Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None |
metadata |
No |
Explanation: Object metadata. For details, see Table 19. Default value: None |
|
acl |
No |
Explanation: ACL that can be pre-defined when an object is created. Refer to Table 12 to choose the option you need. For details about ACLs, see ACLs. Value range:
Default value: None |
|
sseKmsHeader |
No |
Explanation: Server-side encryption header. For details, see Table 14. Default value: None |
|
sseCHeader |
No |
Explanation: Server-side encryption header. For details, see Table 13. Default value: None |
|
input |
java.io.InputStream |
No |
Explanation: Data stream of the object to be uploaded. Default value: None |
file |
java.io.File |
No |
Explanation: File stream of the object to be uploaded. Default value: None |
extensionPermissionMap |
Map<ExtensionObjectPermissionEnum, Set<String>> |
No |
Explanation: A permission map for granting bucket ACL permissions to one or more accounts. ExtensionObjectPermissionEnum specifies the permissions to grant, and Set<String> describes the list of account IDs (indicated by domain_id) the granted permissions apply to. Value range:
Default value: None |
expires |
int |
No |
Explanation: Expiration time of the object. The calculation starts from the time when the object was last modified. Once the object expires, it is automatically deleted. Restrictions: This parameter can be configured when uploading an object or using the x-obs-expires header in a metadata API call. Value range: An integer greater than 0, in days Default value: None |
progressListener |
No |
Explanation: Upload progress. For details, see Table 3. |
|
encodeHeaders |
boolean |
No |
Explanation: Whether to enable OBS to automatically encode request headers. Due to HTTP coding restrictions, only ASCII characters can be sent. If your request headers contain full-width characters, the SDK will URL encode these characters before sending the request. When you use a browser to access the object metadata, the browser automatically decodes the data. Value range: true: Encoding with SDK is enabled. false: Encoding with SDK is disabled. Default value: true |
Method |
Return Value Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
void |
Yes |
Explanation: Used for obtaining the upload progress. For details, see Table 4. Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
status |
Yes |
Explanation: Progress data. For details, see Table 5. Default value: None |
Method |
Return Value Type |
Description |
---|---|---|
getAverageSpeed() |
double |
Average transmission rate. |
getInstantaneousSpeed() |
double |
Instantaneous transmission rate. |
getTransferPercentage() |
int |
Transmission progress, in percentage. |
getNewlyTransferredBytes() |
long |
Number of the newly transmitted bytes. |
getTransferredBytes() |
long |
Number of bytes that have been transmitted. |
getTotalBytes() |
long |
Number of the bytes to be transmitted. |
Constant |
Description |
---|---|
GRANT_READ |
Grants a specific tenant the permissions to read the object and object metadata. |
GRANT_READ_ACP |
Grants a specific tenant the permissions to obtain the object ACL. |
GRANT_WRITE_ACP |
Grants a specific tenant the permissions to write the object ACL. |
GRANT_FULL_CONTROL |
Grants a specific tenant the permissions to read the content, metadata, and ACL of the object and write the object ACL. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
encryption |
Yes |
Explanation: SSE-KMS used for encrypting objects. Explanation: SSE-KMS is used for encrypting objects on the server side. Value range: kms. For details, see Table 9. Default value: None |
|
sseAlgorithm |
No |
Explanation: Encryption algorithm. Restrictions: Only KMS is supported. Value range: See Table 10. Default value: None |
|
kmsKeyId |
String |
No |
Explanation: ID of the KMS master key when SSE-KMS is used. Value range: Valid value formats are as follows:
In the preceding formats:
Default value:
|
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
algorithm |
Yes |
Explanation: SSE-C is used for encrypting objects on the server side. Value range: AES256, indicating AES is used to encrypt the object in SSE-C. For details, see Table 11. Default value: None |
|
sseAlgorithm |
No |
Explanation: Encryption algorithm. Restrictions: Only AES256 is supported. Value range: See Table 10. Default value: None |
|
sseCKey |
byte[] |
Yes |
Explanation: Key used for encrypting the object when SSE-C is used, in byte[] format. Default value: None |
sseCKeyBase64 |
String |
No |
Explanation: Base64-encoded key used for encrypting the object when SSE-C is used. Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Type |
---|---|---|---|
owner |
No |
Explanation: Bucket owner information. For details, see Table 13. |
|
delivered |
boolean |
No |
Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false |
grants |
Set<GrantAndPermission> |
No |
Explanation: Grantee information. For details, see Table 14. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
id |
String |
Yes |
Explanation: Account (domain) ID of the bucket owner. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None |
displayName |
String |
No |
Explanation: Account name of the owner. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
grantee |
Yes |
Explanation: Grantees (users or user groups). For details, see Table 16. |
|
permission |
Yes |
Explanation: Permissions to grant. Value range: See Table 15. Default value: None |
|
delivered |
boolean |
No |
Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false |
Constant |
Default Value |
Description |
---|---|---|
PERMISSION_READ |
READ |
Read permission. A grantee with this permission for a bucket can obtain the list of objects, multipart uploads, bucket metadata, and object versions in the bucket. A grantee with this permission for an object can obtain the object content and metadata. |
PERMISSION_WRITE |
WRITE |
Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object or part in the bucket. This permission is not available for objects. |
PERMISSION_READ_ACP |
READ_ACP |
Permission to read an ACL. A grantee with this permission can obtain the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default. |
PERMISSION_WRITE_ACP |
WRITE_ACP |
Permission to modify an ACL. A grantee with this permission can update the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default. This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object. |
PERMISSION_FULL_CONTROL |
FULL_CONTROL |
Full control access, including read and write permissions for a bucket and its ACL, or for an object and its ACL. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket. A grantee with this permission for an object has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the object. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
Yes |
Explanation: Grantee (user) information. For details, see Table 17. |
||
Yes |
Explanation: Grantee (user group) information. Value range: See Table 18. Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
grantId |
String |
Yes if Type is set to GranteeUser |
Explanation: Account (domain) ID of the grantee. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None |
displayName |
String |
No |
Parameter description: Account name of the grantee. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None |
Constant |
Description |
---|---|
ALL_USERS |
All users. |
AUTHENTICATED_USERS |
Authorized users. This constant is deprecated. |
LOG_DELIVERY |
Log delivery group. This constant is deprecated. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
contentLength |
Long |
No |
Explanation: Size of the object. Restrictions:
Default value: If this parameter is not specified, the SDK automatically calculates the size of the object. |
contentType |
String |
No |
Explanation: MIME type of the object to be uploaded. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data. Value range: See What Is Content-Type (MIME)? (Java SDK) Default value: If this parameter is not specified, the SDK determines the file type based on the suffix of the object name and assigns a value to the parameter. For example, if the suffix of the object name is .xml, the object is an application/xml file. If the suffix is .html, the object is a text/html file. |
contentEncoding |
String |
No |
Explanation: Content-Encoding header in the response. It specifies which encoding is applied to the object. Default value: None |
contentDisposition |
String |
No |
Explanation: Provides a default file name for the requested object. When the object with the default file name is being downloaded or accessed, the content is displayed as part of a web page in the browser or as an attachment in a download dialog box. Default value: None |
cacheControl |
String |
No |
Explanation: Cache-Control header in the response. It specifies the cache behavior of the web page when an object is downloaded. Default value: None |
contentLanguage |
String |
No |
Explanation: Language or language combination for visitors to customize and use. For details, see the definition of ContentLanguage in the HTTP protocol. Default value: None |
expires |
String |
No |
Explanation: The time a cached web page object expires. Restrictions: The time must be in the GMT format. Default value: None |
contentMd5 |
String |
No |
Explanation: Base64-encoded MD5 value of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned. Restrictions:
Value range: Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864. Example: n58IG6hfM7vqI4K0vnWpog== Default value: None |
storageClass |
No |
Explanation: Object storage class that can be specified at object creation. If this parameter is not specified, the object inherits the storage class of the bucket where it is to be uploaded by default. Value range: See Table 20. Default value: None |
|
webSiteRedirectLocation |
String |
No |
Explanation: If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL. This parameter specifies the address the request for the object is redirected to. The request is redirected to an object anotherPage.html in the same bucket: WebsiteRedirectLocation:/anotherPage.html The request is redirected to an external URL http://www.example.com/: WebsiteRedirectLocation:http://www.example.com/ Restrictions:
Default value: None |
nextPosition |
long |
No |
Explanation: Start position for the next append upload. Value range: 0 to the object length, in bytes. Default value: None |
appendable |
boolean |
No |
Explanation: Whether the object is appendable. Value range: true: The object is appendable. false: The object is not appendable. Default value: None |
userMetadata |
Map<String, Object> |
No |
Explanation: User-defined metadata of the object. To define it, you can add a header starting with x-obs-meta- in the request. In Map, the String key indicates the name of the user-defined metadata that starts with x-obs-meta-, and the Object value indicates the value of the user-defined metadata. To obtain the user-defined metadata of an object, use ObsClient.getObjectMetadata. For details, see Obtaining Object Metadata (SDK for Java). Restrictions:
Default value: None |
Constant |
Default Value |
Description |
---|---|---|
STANDARD |
STANDARD |
Standard storage class |
WARM |
WARM |
Infrequent Access storage class. |
COLD |
COLD |
Archive storage class. |
Constant |
Description |
---|---|
AccessControlList.REST_CANNED_PRIVATE |
Private read/write. A bucket or object can only be accessed by its owner. |
AccessControlList.REST_CANNED_PUBLIC_READ |
Public read. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, bucket metadata, and object versions in the bucket. If this permission is granted on an object, anyone can read the content and metadata of the object. |
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE |
Public read/write. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, upload parts, assemble parts, copy parts, and cancel multipart upload tasks. If this permission is granted on an object, anyone can read the content and metadata of the object. |
AccessControlList.REST_CANNED_PUBLIC_READ_DELIVERED |
Public read on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects. |
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE_DELIVERED |
Public read/write on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects. |
Responses
Parameter |
Type |
Description |
---|---|---|
statusCode |
int |
Explanation: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None |
responseHeaders |
Map<String, Object> |
Explanation: Response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header. Default value: None |
storageClass |
Explanation: Storage class of an object that can be specified at object creation. If this header is not set, the default storage class of the bucket is used as the storage class of the object. Value range: See Table 20. Default value: None |
|
versionId |
String |
Explanation: Object version ID. If versioning is enabled for the bucket, the object version ID will be returned. Value range: The value must contain 32 characters. Default value: None |
etag |
String |
Explanation: ETag of an object, which is a Base64-encoded 128-bit MD5 digest. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, the object content is changed. The ETag reflects changes only to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object. Value range: The value must contain 32 characters. Default value: None |
objectKey |
String |
Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None |
bucketName |
String |
Explanation: Bucket name. Restrictions:
Default value: None |
Code Examples
This example uploads local files to bucket examplebucket.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
import com.obs.services.ObsClient; import com.obs.services.exception.ObsException; import com.obs.services.model.PutObjectRequest; import java.io.File; public class PutObject004 { public static void main(String[] args) { // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage. // Obtain an AK/SK pair on the management console. String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage. // Obtain an AK/SK pair and a security token using environment variables or import them in other ways. // String securityToken = System.getenv("SECURITY_TOKEN"); // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation. String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com"; // Obtain an endpoint using environment variables or import it in other ways. //String endPoint = System.getenv("ENDPOINT"); // Create an ObsClient instance. // Use the permanent AK/SK pair to initialize the client. ObsClient obsClient = new ObsClient(ak, sk,endPoint); // Use the temporary AK/SK pair and security token to initialize the client. // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint); try { // Upload files. // localfile indicates the path of the local file to be uploaded, in which the file name must be specified. PutObjectRequest request = new PutObjectRequest(); request.setBucketName("examplebucket"); request.setObjectKey("objectkey"); request.setFile(new File("localfile")); obsClient.putObject(request); System.out.println("putObject successfully"); } catch (ObsException e) { System.out.println("putObject failed"); // Request failed. Print the HTTP status code. System.out.println("HTTP Code:" + e.getResponseCode()); // Request failed. Print the server-side error code. System.out.println("Error Code:" + e.getErrorCode()); // Request failed. Print the error details. System.out.println("Error Message:" + e.getErrorMessage()); // Request failed. Print the request ID. System.out.println("Request ID:" + e.getErrorRequestId()); System.out.println("Host ID:" + e.getErrorHostId()); e.printStackTrace(); } catch (Exception e) { System.out.println("putObject failed"); // Print other error information. e.printStackTrace(); } } } |
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot