Obtaining User-defined Metadata (SDK for Java)

Function

Object metadata is a set of key-value pairs that describe the object and is used for object management.

This API returns the user-defined object metadata after the object is successfully downloaded.

Restrictions

To obtain object metadata, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.

Method

obsClient.getObject(GetObjectRequest request)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
request	GetObjectRequest	Yes	Explanation: Request parameters for downloading an object. For details, see Table 2.

**Table 2** GetObjectRequest
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.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None
versionId	String	No	Explanation: Object version ID. Value range: The value must contain 32 characters. Default value: None
rangeStart	Long	No	Explanation: Start position for object download. Value range: A non-negative integer. Default value: None
rangeEnd	Long	No	Explanation: End position for object download. Restrictions: The upper limit of the value is the object length minus 1, in bytes. Default value: None
ifMatchTag	String	No	Explanation: Preset ETag. If the ETag of the object to be downloaded is the same as the preset ETag, the object is returned. Otherwise, an error is returned. Value range: The value must contain 32 characters. Default value: None
ifNoneMatchTag	String	No	Explanation: Preset ETag. If the ETag of the object to be downloaded is different from the preset ETag, the object is returned. Otherwise, an error is returned. Value range: The value must contain 32 characters. Default value: None
IfModifiedSince	Date	No	Explanation: The object is returned if it has been modified since the specified time; otherwise, an error is returned. Default value: None
IfUnmodifiedSince	Date	No	Explanation: The object is returned if it has not been modified since the specified time; otherwise, an error is returned. Default value: None
sseCHeader	SseCHeader	No	Explanation: Server-side decryption header. For details, see Table 7.
replaceMetadata	ObjectRepleaceMetadata	No	Explanation: Additional information about the object. For details, see Table 3.
progressListener	ProgressListener	No	Explanation: Data transmission listener for obtaining the progress. For details, see Table 4.
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

**Table 3** ObjectRepleaceMetadata
Parameter	Type	Mandatory (Yes/No)	Description
contentType	String	No	Explanation: MIME type of the object file. 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: 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: Expires header in the response. It specifies the cache expiration time of the web page when the object is downloaded. 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
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
contentEncoding	String	No	Explanation: Content-Encoding header in the response. It specifies which encoding is applied to the object in a download. Default value: None

**Table 4** ProgressListener
Method	Return Value Type	Mandatory (Yes/No)	Description
progressChanged	void	Yes	Explanation: Used for obtaining the progress. For details, see Table 5. Default value: None

**Table 5** progressChanged
Parameter	Type	Mandatory (Yes/No)	Description
status	ProgressStatus	Yes	Explanation: Progress data. For details, see Table 6. Default value: None

**Table 6** 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.

**Table 7** 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 Advanced Encryption Standard (AES) is used to encrypt the object in SSE-C. For details, see Table 9. Default value: None
sseAlgorithm	SSEAlgorithmEnum	No	Explanation: Encryption algorithm. Restrictions: Only AES256 is supported. Value range: See Table 8. 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 8** SSEAlgorithmEnum
Constant	Default Value
KMS	kms
AES256	AES256

**Table 9** ServerAlgorithm
Constant	Default Value
AES256	AES256

**Table 10** Owner
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

**Table 11** StorageClassEnum
Constant	Default Value	Description
STANDARD	STANDARD	Standard storage class
WARM	WARM	Infrequent Access storage class.
COLD	COLD	Archive storage class.

**Table 12** ObjectMetadata
Parameter	Type	Mandatory (Yes/No)	Description
contentLength	Long	No	Explanation: Object size. 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 file. 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: The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object. Value range: Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864. Example: n58IG6hfM7vqI4K0vnWpog== Default value: None
storageClass	StorageClassEnum	No	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 11. 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: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS only supports redirection for objects in the root directory of a bucket. 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: An object can have multiple pieces of metadata. The size of the metadata cannot exceed 8 KB in total. When you call ObsClient.getObject to download an object, its user-defined metadata will also be downloaded. Default value: None

Responses

**Table 13** ObsObject
Parameter	Type	Description
bucketName	String	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	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.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None
owner	Owner	Explanation: Owner of the object. For details, see Table 10.
metadata	ObjectMetadata	Explanation: Object metadata. For details, see Table 12.
objectContent	InputStream	Explanation: Object data stream. Default value: None

Code Examples

This example downloads object objectname from bucket examplebucket and returns the user-defined object metadata.

    
     
       
       
         import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.GetObjectRequest;
import com.obs.services.model.ObjectMetadata;
import com.obs.services.model.ObsObject;
import com.obs.services.model.PutObjectRequest;
public class GetObject006 {
    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. EU-Dublin is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu"; 
        // 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 {
            // Obtain the user-defined metadata.
            // Upload the object and customize the metadata.
            PutObjectRequest request = new PutObjectRequest("examplebucket", "objectname");
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.addUserMetadata("property", "property-value");
            request.setMetadata(metadata);
            obsClient.putObject(request);
            // Download the object to obtain the object's user-defined metadata.
            GetObjectRequest request1 = new GetObjectRequest("examplebucket", "objectname");
            ObsObject obsObject = obsClient.getObject(request1);
            System.out.println("getObject successfully");
            // Get the object metadata.
            System.out.println(obsObject.getMetadata().getContentType());
            // Obtain the user-defined metadata named property.
            System.out.println(obsObject.getMetadata().getUserMetadata("property"));
            // Obtain all user-defined metadata.
            System.out.println("allUserMetadata:" + metadata.getAllMetadata());
            obsObject.getObjectContent().close();
        } catch (ObsException e) {
            System.out.println("getObject 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("getObject failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}

        

      

    
   