API Docs for: 0.7.0
Show:

File: lib/api.js

/**
 * OSS API
 * @module API
 * @requires
 * @namespace API
 */

var data2xml = require('data2xml');
var xml2js = require('xml2js');
var settings = require('./settings');
var util = require('./util');

/**
 * API manipulation class
 * @class OSS
 * @constructor
 */
function OSS(){

var _this = this;

/**
 * GET OSS ListBucket Service
 * @method getService
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object
 */
_this.getService = function(callback){
	util.authWithHeader('GET',{},{},function(response){
		callback(response);
	});
};

/**
 * Add Or Modify bucket
 * @method putBucket
 * @param {string} bucket bucket name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.putBucket = function(bucket,callback){
	util.authWithHeader('PUT',{},{},function(response){
		callback(response);
	},bucket);
};

/**
 * Add Or Modify bucket with o-oss-acl header
 * @method putBucket
 * @param {string} bucket bucket name
 * @param {string} acl access control.Can be following three value:
 *   <ul>
 *     <li>private</li>
 *     <li>public-read</li>
 *     <li>public-read-write</li>
 *   </ul>
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.putBucketACL = function(bucket,acl,callback){
	if (settings.ACLS.indexOf(acl) === -1) {
		throw 'Given acl not supported!Read about OSS API';
	}
	util.authWithHeader('PUT',{
		'x-oss-acl': acl,
	},{},function(response){
		callback(response);
	},bucket);
};

/**
 * Get bucket information,list objects in bucket
 * @method getBucket
 * @param {string} bucket bucket name
 * @param {Object} queryObj Query parameters,can be three of the following
 * 	 <ul>
 * 	   <li>prefix</li>
 * 	   <li>marker</li>
 * 	   <li>delimiter</li>
 * 	   <li>max-keys</li>
 * 	 </ul>
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.getBucket = function(bucket,queryObj,callback){
	util.authWithHeader('GET',{},queryObj,function(response){
		callback(response);
	},bucket);
};

/**
 * Get bucket's ACL info
 * @method getBucketACL
 * @param {string} bucket Bucket name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.getBucketACL = function(bucket,callback){
	util.authWithHeader('GET',{},{'acl':''},function(response){
		callback(response);
	},bucket);
};

/**
 * Delete bucket
 * @method deleteBucket
 * @param {string} bucket Bucket name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.deleteBucket = function(bucket,callback){
	util.authWithHeader('DELETE',{},{},function(response){
		callback(response);
	},bucket);
};

/**
 * Add Or Update an object
 * @method putObject
 * @param {Object} headers http headers,you should take care of Content-Length,
 *   and also support Cache-Control、Expires、Content-Encoding、Content-Disposition
 * @param {string} bucket bucket name
 * @param {string} object object name
 * @param {string} data object content
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.putObject = function(headers,bucket,object,data,callback){
	util.authWithHeader('PUT',headers,{},function(response){
		callback(response);
	},bucket,object,data);
};

/**
 * Get object data
 * @method getObject
 * @param {Object} headers http headers,you should take care of Content-Length,
 *   and also support Cache-Control、Expires、Content-Encoding、Content-Disposition
 * @param {Object} queryObj Extra query string in object format<br>
 * <h7>请求 Header:</h7><br>
 * Range 指定文件传输的范围。如,设定 bytes=0-9,表示传送第 0 到第 9 这 10 个字符。<br>
 * If-Modified-Since 如果指定的时间早于实际修改时间,则正常传送文件,并返回 200 OK;
 * 否则返回 304 not modified<br>
 * If-Unmodified-Since 如果传入参数中的时间等于或者晚于文件实际修改时间,则正常传输文件,
 * 并返回 200 OK;否则返回 412 precondition failed 错误
 * If-Match 如果传入期望的 ETag 和 object 的 ETag 匹配,则正常传输文件,并返回 200 OK;
 * 否则返回 412 precondition failed 错误<br>
 * If-None-Match 如果传入的 ETag 值和 Object 的 ETag 不匹配,则正常传输文件,并返回 200 OK;
 * 否则返回 304 Not Modified<br>
 * <h7>请求参数: </h7><br>
 *   OSS支持用户在发送GET请求时,可以自定义OSS返回请求中的一些Header,这些 Header 包括:<br>
 * response-content-type 设置 OSS 返回请求的 content-type 头<br>
 * response-content-language 设置 OSS 返回请求的 content-language 头<br>
 * response-expires 设置 OSS 返回请求的 expires 头<br>
 * response-cache-control 设置 OSS 返回请求的 cache-control 头<br>
 * response-content-disposition 设置OSS返回请求的content-disposition头<br>
 * response-content-encoding 设置 OSS 返回请求的 content-encoding 头<br>
 * @param {string} bucket bucket name
 * @param {string} object object name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.getObject = function(headers,queryObj,bucket,object,callback){
	util.authWithHeader('GET',headers,queryObj,function(response){
		callback(response);
	},bucket,object);
};

/**
 * Copy object
 * @method copyObject
 * @param {Object} headers http header
 * 请求 Header: <br>
 * x-oss-copy-source复制源地址(必须有可读权限)<br>
 * x-oss-copy-source-if-match如果源Object的ETAG值和用户提供的ETAG相等,则执行拷贝操作;
 * 否则返回412HTTP错误码(预处理失败)。<br>
 * x-oss-copy-source-if-nonematch如果源Object自从用户指定的时间以后就没有被修改过,
 * 则执行拷贝操作;否则返回412HTTP36错误码(预处理失败)。<br>
 * x-oss-copy-source-if-unmodified-since如果传入参数中的时间等于或者晚于文件实际修改时间,
 * 则正常传输文件,并返回200OK;否则返回412preconditionfailed错误<br>
 * x-oss-copy-source-if-modified-since如果源Object自从用户指定的时间以后被修改过,
 * 则执行拷贝操作;否则返回412HTTP错误码(预处理失败)。<br>
 * x-oss-metadata-directive有效值为COPY和REPLACE。如果该值设为COPY,
 * 则新的Object的meta都从源Object复制过来;如果设为REPLACE,则忽视所有源Object的meta值,
 * 而采用用户这次请求中指定的meta值;其他值则返回400HTTP错误码。
 * @param {string} source x-oss-copy-source value
 * @param {string} bucket bucket name
 * @param {string} object object name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.copyObject = function(headers,source,bucket,object,callback){
	headers['x-oss-copy-source'] = source;
	util.authWithHeader('PUT',headers,{},function(response){
		callback(response);
	},bucket,object);
};

/**
 * Get object meta info
 * @method headObject
 * @param {string} bucket bucket name
 * @param {string} object object name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.headObject = function(bucket,object,callback){
	util.authWithHeader('HEAD',{},{},function(response){
		callback(response);
	},bucket,object);
};

/**
 * Delete object
 * @method deleteObject
 * @param {string} bucket bucket name
 * @param {string} object object name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.deleteObject = function(bucket,object,callback){
	util.authWithHeader('DELETE',{},{},function(response){
		callback(response);
	},bucket,object);
};

/**
 * Delete mutiple object at one time
 * @method deleteMultipleObject
 * @param {string} bucket bucket name
 * @param {Array} object List of object names need to be deleted
 * @param {bool} isQuite verbose or quite mode in response
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.deleteMultipleObject = function(bucket,objects,isQuite,callback){
	//create xml content
	objectKeyPairs = objects.map(function(object){
		return {'Key': object};
	});
	var data = data2xml('Delete',{
		'Quite': isQuite, 'Object': objectKeyPairs
	});
	util.debugOutput('API.deleteMultipleObject','data',data);

	var headers = {
		'Content-Length': data.length,
		'Content-MD5': util.cryptoMD5(data),
	};
	util.authWithHeader('POST',headers,{'delete':''},function(response){
		callback(response);
	},bucket,'',data);
};

/**
 * Create new object group
 * @method postObjectGroup
 * @param {string} bucket bucket name
 * @param {string} group group name
 * @param {Array} parts Supply object info,With the following format
 *   {'PartNumber': 1,'PartName': 'stuff','ETag': 686897696a7c876b7e}<br>
 *   Because of this,you have to first fetch ETag of each object 
 *   you want to join in group
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.postObjectGroup = function(bucket,group,parts,callback){
	parts.sort(function(first,second){
		return first.PartNumber - second.PartNumber
	});
	var xml = data2xml('CreateFileGroup',{'Part':parts});
	console.log(xml);
	util.authWithHeader(
		'POST',{'Content-Length':xml.length},
		{'group':''},function(response){callback(response);},
		bucket,group,xml);
};

/**
 * Get object group Content
 * @method getObjectGroup
 * @param {string} bucket bucket name
 * @param {string} group group name
 * @param {Object} headers Can add 'Range' in here.And it's optional
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.getObjectGroup = function(bucket,group,headers,callback){
	util.authWithHeader('GET',headers,{},function(response){
		callback(response);
	},bucket,group);
};

/**
 * Get object object's info in group
 * @method getObjectGroupIndex
 * @param {string} bucket bucket name
 * @param {string} group group name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.getObjectGroupIndex = function(bucket,group,callback){
	util.authWithHeader('GET',{'x-oss-file-group':''},{},function(response){
		callback(response);
	},bucket,group);
};

/**
 * Get group info
 * @method headObjectGroup
 * @param {string} bucket bucket name
 * @param {string} group group name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.headObjectGroup = function(bucket,group,callback){
	util.authWithHeader('HEAD',{},{},function(response){
		callback(response);
	},bucket,group);
};

/**
 * Delete object group
 * @method deleteObjectGroup
 * @param {string} bucket bucket name
 * @param {string} group group name
 * @param {Function} callback Called when OSS response,
 *   supplied with http.Response object.
 */
_this.deleteObjectGroup = function(bucket,group,callback){
	util.authWithHeader('DELETE',{},{},function(response){
		callback(response);
	},bucket,group);
};

/**
 * @namespace API.OSS
 * @class MultipartUpload
 */
_this.MultipartUpload = (function(){
	/**
	 * @constructor
	 */
	var constructor = function(){
		var _this = this;
		/**
		 * @private
		 * @property {string} _uploadId Multipart upload ID
		 */
		_this._uploadId = undefined;
		/**
		 * @private
		 * @property {string} _bucket Multipart upload bucket name
		 */
		_this._bucket = undefined;
		/**
		 * @private
		 * @property {string} _object Multipart upload object name
		 */
		_this._object = undefined;
		/**
		 * @private
		 * @property {number} _partNumber Multipart upload object name
		 */
		_this._partNumber = undefined;
		/**
		 * @private
		 * @property {Array} _parts store every uploaded part number & returned ETag
		 */
		_this._parts = [];

		/**
		 * Init multipart upload process
		 * @method init
		 * @param {string} bucket bucket name
		 * @param {string} object object name
		 * @param {Function} callback Called when OSS response,
		 *   supplied with http.Response object.
		 */
		_this.init = function(bucket,object,callback){
			util.authWithHeader('POST',{},{'uploads':''},function(response){
				response.setEncoding('utf8');
				response.on('data',function(chunk){
					var parser = new xml2js.Parser();
					parser.parseString(chunk,function(err,xml){
						//init multipart upload parameters
						_this._uploadId = xml.InitiateMultipartUploadResult.UploadId[0];
						_this._bucket = xml.InitiateMultipartUploadResult.Bucket[0];
						_this._object = xml.InitiateMultipartUploadResult.Key[0];
						_this._partNumber = 1;
						callback(response);
					});
				});
			},bucket,object);
		};

		/**
		 * Upload part data
		 * @method uploadPart
		 * @param {string} data content being uploaded
		 * @param {Function} callback Called when OSS response,
		 *   supplied with http.Response object.
		 */
		_this.upload = function(data,callback){
			util.authWithHeader('PUT',{
				'Content-Length': data.length,
			},{
				'partNumber': _this._partNumber,
				'uploaded':_this._uploadId,
			},function(response){
				_this._parts.push({
					'PartNumber': _this._partNumber,
					'ETag': response.headers.etag,
				});
				_this._partNumber++;
				callback(response);
			},_this._bucket,_this._object,data);
		};

		/**
		 * FIXME : 出现invalid part错误
		 * complete upload process
		 * @method complete
		 * @param {Function} callback Called when OSS response,
		 *   supplied with http.Response object.
		 */
		_this.complete = function(callback){
			var xml = data2xml('CompleteMultipartUpload',{'Part':_this._parts});
			console.log(_this._uploadId);
			console.log(_this._parts);
			console.log(xml);
			util.authWithHeader(
				'POST',
				{'Content-Length':xml.length},
				{'uploadId':_this._uploadId},
				function(response){ xml;debugger;callback(response); },
				_this._bucket,_this._object,xml);
		};

		/**
		 * Delete multipartupload object
		 * @method abort
		 * @param {Function} callback Called when OSS response,
		 *   supplied with http.Response object.
		 */
		_this.abort = function(callback){
			util.authWithHeader(
				'DELETE',
				{},
				{'uploadId':_this._uploadId},
				function(response){callback(response);},
				_this._bucket,_this._object);
		};
	};//End of MultipartUpload constructor
	
	/**
	 * List a number of multipart upload in bucket
	 * @method listMultiUploads
	 * @static
	 * @param {string} bucket bucket name
	 * @param {Object} queryObj Extra query string in object format
	 *   List Multipart Uploads 请求支持 5 中请求参数: prefix,marker,
	 *   delimiter,upload-id-marker 和 max-keys。通过这些参数的组合,可以设定查
	 *   询 Multipart Uploads 事件的规则,获得期望的查询结果。
	 * @param {Function} callback Called when OSS response,
	 *   supplied with http.Response object.
	 */
	constructor.listMultipartUploads = function(bucket,queryObj,callback){
		queryObj.uploads = '';
		util.authWithHeader('GET',{},queryObj,function(response){
			callback(response);
		},bucket);
	};

	/**
	 * List a multipart process all parts
	 * @method listParts
	 * @static
	 * @param {string} bucket bucket name
	 * @param {string} object object name
	 * @param {string} uploadId multipartupload ID
	 * @param {Object} queryObj Extra query string in object format
	 *   List Parts 支持 max-parts 和 part-number-marker 两种请求参数。
	 * @param {Function} callback Called when OSS response,
	 *   supplied with http.Response object.
	 */
	constructor.listParts = function(bucket,object,uploadId,queryObj,callback){
		queryObj.uploadId = uploadId;
		util.authWithHeader('GET',{},queryObj,function(response){
			callback(response);
		},bucket,object);
	};
	return constructor;

})();//End of MultipartUpload class

};//End of OSS class

exports.OSS = OSS;