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. This parameter is not supported for streams. 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 stream is automatically closed. false: The data stream 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.

    
     
       
       
         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 of the second part. This parameter takes effect only when a file is uploaded. This parameter is not supported for streams.
            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();
        }
    }
}

        

      

    
   