GET Object

API Description

You can user this API to download an object in a specified bucket.

Method

ObsClient.getObject

Request Parameters

Field	Type	Optional or Mandatory	Description
Bucket	String	Mandatory	Bucket name
Key	String	Mandatory	Object name
VersionId	String	Optional	Object version ID
ProgressCallback	Function	Optional	Callback function for obtaining the download progress NOTE: This callback function contains the following parameters in sequence: number of downloaded bytes, total bytes, and used time (unit: second).
IfMatch	String	Optional	Returns the source object if its ETag is the same as the one specified by this parameter; otherwise, an error code is returned.
IfModifiedSince	String	Optional	Returns the object if it is modified after the time specified by this parameter; otherwise, an error code is returned. This parameter must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.
IfNoneMatch	String	Optional	Returns the source object if its ETag is different from the one specified by this parameter; otherwise, an error code is returned.
IfUnmodifiedSince	String	Optional	Returns the object if it remains unchanged since the time specified by this parameter; otherwise, an error code is returned. This parameter must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.
Range	String	Optional	Download range. The value range is [0, object length-1] and is in the format of bytes=x-y. The maximum length of Range is the length of the object minus 1. If it exceeds this value, the length of the object minus 1 is used.
Origin	String	Optional	Origin of the cross-domain request specified by the pre-request. Generally, it is a domain name.
RequestHeader	String	Optional	HTTP headers in the cross-domain request
ResponseCacheControl	String	Optional	Rewrites the Cache-Control header in the response.
ResponseContentDisposition	String	Optional	Rewrites the Content-Disposition header in the response.
ResponseContentEncoding	String	Optional	Rewrites the Content-Encoding header in the response.
ResponseContentLanguage	String	Optional	Rewrites the Content-Language header in the response.
ResponseContentType	String	Optional	Rewrites the Content-Type header in the response.
ResponseExpires	String	Optional	Rewrites the Expires header in the response
ImageProcess	String	Optional	Image processing parameter
SaveAsFile	String	Optional	The download path with the file name contained
SaveAsStream	Boolean	Optional	Whether the object is returned as a readable stream
SseC	String	Optional	Algorithm used in SSE-C decryption. The value can be: AES256
SseCKey	Buffer	Optional	Key used in SSE-C decryption, which is calculated by using AES256.

SaveAsFile and SaveAsStream cannot be used together.
If the download request includes IfUnmodifiedSince or IfMatch, and IfUnmodifiedSince or IfMatch is not met, 412 Precondition Failed will be returned.
If the download request includes IfModifiedSince or IfNoneMatch, and IfModifiedSince or IfNoneMatch is not met, 304 Not Modified will be returned.

Returned Result (InterfaceResult)

Field	Type	Description
RequestId	String	Request ID returned by the OBS server
DeleteMarker	String	Whether the deleted object is a delete marker
LastModified	String	Time when the last modification was made to the object
ContentLength	String	Object size in bytes
CacheControl	String	Cache-Control header in the response
ContentDisposition	String	Content-Disposition header in the response
ContentEncoding	String	Content-Encoding header in the response
ContentLanguage	String	Content-Language header in the response
ContentType	String	MIME type of the object
Expires	String	Expires header in the response
ETag	String	Object ETag
VersionId	String	Object version ID
WebsiteRedirectLocation	String	Location where the object is redirected to, when the bucket is configured with website hosting
StorageClass	String	Storage class of the object. When the storage class is OBS Standard, the value is null.
Restore	String	Restore status of the object in the OBS Archive storage class
AllowOrigin	String	If Origin in the request meets the CORS rules of the bucket, AllowedOrigin in the CORS rules is returned.
AllowHeader	String	If RequestHeader in the request meets the CORS rules of the bucket, AllowedHeader in the CORS rules is returned.
AllowMethod	String	AllowedMethod in the CORS rules of the bucket
ExposeHeader	String	ExposeHeader in the CORS rules of the bucket
MaxAgeSeconds	String	MaxAgeSeconds in the CORS rules of the bucket
SseKms	String	Algorithm used in SSE-KMS decryption
SseKmsKey	String	Master key used in SSE-KMS decryption
SseC	String	Algorithm used in SSE-C decryption
SseCKeyMd5	String	MD5 value of the key used in SSE-C decryption
Expiration	String	Expiration details
Content	String or stream.Readable	Content of the object. The content is null when SaveAsFile is set. The content is an instance of stream.Readable when SaveAsStream is set to true. The content is an instance of Buffer when neither SaveAsFile nor SaveAsStream is set.
Metadata	Object	Customized metadata of the object

Sample Code

This example downloads part (length range: 0-1,023 bytes) of objectname from examplebucket and prints the progress.

// Use npm to install the client.
var ObsClient = require('esdk-obs-nodejs');

// 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 by referring to https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
const AK = process.env.AccessKeyID
const SK = process.env.SecretAccessKey
// (Optional) If you use a temporary AK/SK pair and a security token to access OBS, obtain them using environment variables.
const security_token= process.env.SecurityToken
// Set server to the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
const server = "https://obs.ap-southeast-1.myhuaweicloud.com"

var obsClient = new ObsClient({
    access_key_id: AK,
    secret_access_key: SK,
    server: server,
});
const Bucket = 'examplebucket'
// Name of the object to be downloaded
const Key = 'objectname'
// Specify the object range to download in the format of bytes=x-y. The range must be from 0 to the total bytes of the object minus 1. If the specified range is beyond the allowed upper limit, the upper limit is used.
const Range = 'bytes=0-1023'
// Specify the download path with the file name contained.
const SaveAsFile = 'D:\\example'
try {
    obsClient.getObject({
        Bucket,
        Key,
        Range,
        SaveAsFile,
        // Progress callback
        ProgressCallback: function (transferredAmount, totalAmount, totalSeconds) {
            // Print the download speed in KB/s.
            console.log(transferredAmount * 1.0 / totalSeconds / 1024);
            // Print the upload percentage.
            console.log(transferredAmount * 100.0 / totalAmount);
        },
        // Specify whether to return the object as a readable stream.
        // SaveAsStream: true
    }, (err, result) => {
        if (err) {
            console.log('GetObject Failed')
            console.error('Error-->' + err);
        } else {
            if (result.CommonMsg.Status < 300) {
                console.log('GetObject Succeeded')
                console.log('RequestId-->' + result.InterfaceResult.RequestId);
                console.log('ETag-->' + result.InterfaceResult.ETag);
                // The following parameters are exclusive to versioned objects.
                console.log('VersionId-->' + result.InterfaceResult.VersionId);
                console.log('ContentLength-->' + result.InterfaceResult.ContentLength);
                // The following parameters are exclusive to versioned objects.
                console.log('DeleteMarker-->' + result.InterfaceResult.DeleteMarker);
                console.log('LastModified-->' + result.InterfaceResult.LastModified);
                // Object storage class. If the storage class is Standard, this parameter is left blank.
                console.log('StorageClass-->' + result.InterfaceResult.StorageClass);
                // console.log('Content-->' + result.InterfaceResult.Content.toString());
                console.log('Metadata-->' + JSON.stringify(result.InterfaceResult.Metadata));
            } else {
                console.log('GetObject Failed')
                console.log('ErrorCode-->' + result.CommonMsg.Code);
                console.log('ErrorMessage-->' + result.CommonMsg.Message);
            }
        }
    });
} catch (error) {
    console.log('GetObject Failed')
    console.error('Error-->' + error);
}

Parent topic: Object-Related APIs

Previous topic: Append Object

Next topic: PUT Object - Copy