Updated on 2024-06-18 GMT+08:00

Uploading a Part (SDK for Java)

Function

After a multipart upload is initiated, this API uploads a part to a specified bucket. In the upload request, the multipart upload ID must be included. Except for the part lastly being uploaded whose size ranges from 0 to 5 GB, sizes of the other parts range from 100 KB to 5 GB. Part numbers can be any number from 1 to 10,000.

When uploading a part, you must specify its upload ID and part number. A part number uniquely identifies a part and its position in the object you are uploading. If you upload a new part with the same part number as that of a previous part, the previously uploaded part will be overwritten. Whenever you upload a part, OBS returns the ETag header in the response. For each part upload task, you must record the part number and ETag value. These values are required in subsequent requests for you to complete a multipart upload.

If you have any questions during development, post them on the Issues page of GitHub.

Restrictions

  • To upload a part, 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.
  • After initiating a multipart upload and uploading one or more parts, you must assemble the parts or abort the multipart upload.
  • partNumber in a multipart upload must be unique. When the same partNumber of the same object is concurrently uploaded, last write wins policy is applied. The time of last write is defined as the time when the part metadata is created. To ensure data accuracy, the client must be locked to ensure concurrent uploads of the same part of the same object. Concurrent uploads for different parts of the same object do not need to be locked.

Method

obsClient.uploadPart(UploadPartRequest request)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

request

UploadPartRequest

Yes

Explanation:

Request parameters for uploading a part. For details, see Table 2.

Table 2 UploadPartRequest

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

String

Yes

Explanation:

Bucket name.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

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

partNumber

int

Yes

Explanation:

Part number.

Value range:

The value ranges from 1 to 10000. If a part number is not within the range, OBS returns error code 400 Bad Request.

Default value:

None

uploadId

String

Yes

Explanation:

Multipart upload ID, which can be returned by initiating a multipart upload, for example, 000001648453845DBB78F2340DD460D8.

Restrictions:

The value must contain 32 characters.

Default value:

None

input

java.io.InputStream

No

Explanation:

Data stream of the object to be uploaded.

Restrictions:

You must specify either file or input.

Default value:

None

file

java.io.File

No

Explanation:

File stream of the object to be uploaded.

Restrictions:

You must specify either file or input. If one of the two parameters is left blank, the other must be specified.

Default value:

None

offset

long

No

Explanation:

Start offset of a part in the source file.

Value range:

A non-negative integer not exceeding the size of the object to be uploaded, in bytes.

Default value:

0

partSize

Long

No

Explanation:

Part size.

Restrictions:

  • Except the part last uploaded, each of the other parts must be larger than 100 KB. The size of each part is not verified during its upload, because the system cannot define whether it is the last part. The part size is verified when the parts are assembled.
  • The minimum part size supported by an OBS 3.0 bucket is 100 KB, and that supported by an OBS 2.0 bucket is 5 MB.

Value range:

The value ranges from 100 KB to 5 GB, in bytes.

Default value:

102400

sseCHeader

SseCHeader

No

Explanation:

Server-side encryption header. For details, see Table 3.

Default value:

None

attachMd5

boolean

No

Explanation:

Whether to automatically calculate the MD5 value of the data to be uploaded. To ensure data integrity, set UploadPartRequest.setAttachMd5 to true to make the SDK automatically calculate the MD5 value (valid only when the data source is a local file) of each part and add the MD5 value to the Content-MD5 request header. The OBS server will calculate the MD5 value of the uploaded data and compare it with the MD5 value calculated by the SDK.

Restrictions:

If attachMd5 and contentMd5 are used at the same time, attachMd5 is ignored.

Value range:

true: The MD5 value of the data to be uploaded is automatically calculated.

false: The MD5 value of the data to be uploaded is not automatically calculated.

Default value:

false

contentMd5

String

No

Explanation:

Base64-encoded MD5 value of the part to be uploaded, which uniquely identifies the content of the uploaded part and can be used to identify whether the object content is changed.

Restrictions:

If attachMd5 and contentMd5 are used at the same time, attachMd5 is ignored.

Value range:

The value must contain 32 characters.

Default value:

None

progressListener

ProgressListener

No

Explanation:

Upload progress. For details, see Table 7.

progressInterval

long

No

Explanation:

Interval for reporting the upload progress, in bytes. For example, 1024 * 1024L indicates that the upload progress is reported each time 1 MB data is uploaded.

Default value:

100 * 1024L

autoClose

boolean

No

Explanation:

Whether to automatically close data streams after the upload is complete.

Value range:

true: The data flow is automatically closed.

false: The data flow is not automatically closed.

Default value:

true

Table 3 SseCHeader

Parameter

Type

Mandatory (Yes/No)

Description

algorithm

ServerAlgorithm

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 4.

Default value:

None

sseAlgorithm

SSEAlgorithmEnum

No

Explanation:

Encryption algorithm.

Restrictions:

Only AES256 is supported.

Value range:

See Table 5.

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

Table 4 ServerAlgorithm

Constant

Default Value

AES256

AES256

Table 5 SSEAlgorithmEnum

Constant

Default Value

KMS

kms

AES256

AES256

Table 6 StorageClassEnum

Constant

Default Value

Description

STANDARD

STANDARD

Standard storage class

WARM

WARM

Infrequent Access storage class.

COLD

COLD

Archive storage class.

Table 7 ProgressListener

Method

Return Value Type

Mandatory (Yes/No)

Description

progressChanged

void

Yes

Explanation:

Used for obtaining the upload progress. For details, see Table 8.

Default value:

None

Table 8 progressChanged

Parameter

Type

Mandatory (Yes/No)

Description

status

ProgressStatus

Yes

Explanation:

Progress data. For details, see Table 9.

Default value:

None

Table 9 ProgressStatus

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.

Responses

Table 10 UploadPartResult

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

partNumber

int

Explanation:

Part number.

Value range:

[1,10000]

Default value:

None

etag

String

Explanation:

Base64-encoded, 128-bit MD5 value of a part. ETag is the unique identifier of the part contents and is used to determine whether the contents of a part are changed. For example, if the ETag value is A when a part is uploaded and is B when the part is downloaded, this indicates the contents of the part are changed. The ETag reflects changes only to the contents of a part, not its metadata. Parts created by the upload and copy operations have unique ETags after being encrypted using MD5.

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

Code Examples

This example calls obsClient.uploadPart to upload parts to object objectname in 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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.PartEtag;
import com.obs.services.model.UploadPartRequest;
import com.obs.services.model.UploadPartResult;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
public class UploadPart001 {
    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 {
            String uploadId = "upload id from initiateMultipartUpload";
            List<PartEtag> partEtags = new ArrayList<PartEtag>();
            // Upload the first part.
            UploadPartRequest request = new UploadPartRequest("examplebucket", "objectname");
            // Set the upload ID.
            request.setUploadId(uploadId);
            // Set the part number, which ranges from 1 to 10000.
            request.setPartNumber(1);
            // Specify the large file to be uploaded.
            request.setFile(new File("localfile"));
            // Set the part size.
            request.setPartSize(5 * 1024 * 1024L);
            UploadPartResult result = obsClient.uploadPart(request);
            partEtags.add(new PartEtag(result.getEtag(), result.getPartNumber()));
            // Upload the second part.
            request = new UploadPartRequest("examplebucket", "objectname");
            // Set the upload ID.
            request.setUploadId(uploadId);
            // Set the part number.
            request.setPartNumber(2);
            // Specify the large file to be uploaded.
            request.setFile(new File("localfile"));
            // Set the offset for the second part.
            request.setOffset(5 * 1024 * 1024L);
            // Set the part size.
            request.setPartSize(5 * 1024 * 1024L);
            result = obsClient.uploadPart(request);
            partEtags.add(new PartEtag(result.getEtag(), result.getPartNumber()));
            System.out.println("uploadPart successfully");
        } catch (ObsException e) {
            System.out.println("uploadPart 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("uploadPart failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}