JavaScript Client API参考文档

初使化Minio Client object.

Minio

  1. varMinio=require('minio')
  2. var minioClient =newMinio.Client({
  3. endPoint:'play.minio.io',
  4. port:9000,
  5. useSSL:true,
  6. accessKey:'Q3AM3UQ867SPQQA43P2F',
  7. secretKey:'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
  8. });

AWS S3

  1. varMinio=require('minio')
  2. var s3Client =newMinio.Client({
  3. endPoint:'s3.amazonaws.com',
  4. accessKey:'YOUR-ACCESSKEYID',
  5. secretKey:'YOUR-SECRETACCESSKEY'
  6. })
操作存储桶操作对象Presigned操作存储桶策略/通知
makeBucketgetObjectpresignedUrlgetBucketNotification
listBucketsgetPartialObjectpresignedGetObjectsetBucketNotification
bucketExistsfGetObjectpresignedPutObjectremoveAllBucketNotification
removeBucketputObjectpresignedPostPolicygetBucketPolicy
listObjectsfPutObjectsetBucketPolicy
listObjectsV2copyObjectlistenBucketNotification
listIncompleteUploadsstatObject
removeObject
removeIncompleteUpload

1. 构造函数

new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey})

|
|——-
|new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey})
|初使化一个新的client对象。

参数

参数类型描述
endPointstringendPoint是一个主机名或者IP地址。
portnumberTCP/IP端口号。可选,默认值是,如果是http,则默认80端口,如果是https,则默认是443端口。
accessKeystringaccessKey类似于用户ID,用于唯一标识你的账户。
secretKeystringsecretKey是你账户的密码。
useSSLbool如果是true,则用的是https而不是http,默认值是true。
regionstring设置该值以覆盖自动发现存储桶region。(可选)

示例

创建连接Minio Server的客户端

  1. varMinio=require('minio')
  2. var minioClient =newMinio.Client({
  3. endPoint:'play.minio.io',
  4. port:9000,
  5. useSSL:true,
  6. accessKey:'Q3AM3UQ867SPQQA43P2F',
  7. secretKey:'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
  8. });

创建连接AWS S3的客户端

  1. varMinio=require('minio')
  2. var s3Client =newMinio.Client({
  3. endPoint:'s3.amazonaws.com',
  4. accessKey:'YOUR-ACCESSKEYID',
  5. secretKey:'YOUR-SECRETACCESSKEY'
  6. })

2. 操作存储桶

makeBucket(bucketName, region[, callback])

创建一个新的存储桶。

参数

参数类型描述
bucketNamestring存储桶名称。
regionstring存储桶被创建的region(地区),默认是us-east-1(美国东一区),下面列举的是其它合法的值:
us-east-1
us-west-1
us-west-2
eu-west-1
eu-central-1
ap-southeast-1
ap-northeast-1
ap-southeast-2
sa-east-1
cn-north-1
callback(err)function回调函数,err做为错误信息参数。如果创建存储桶成功则err为null。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.makeBucket('mybucket','us-east-1',function(err){
  2. if(err)return console.log('Error creating bucket.', err)
  3. console.log('Bucket created successfully in "us-east-1".')
  4. })

listBuckets([callback])

列出所有存储桶。

参数

参数类型描述
callback(err, bucketStream)function回调函数,第一个参数是错误信息。bucketStream是带有存储桶信息的流。如果没有传callback的话,则返回一个Promise对象。

bucketStream格式如下:-

参数类型描述
bucket.namestring存储桶名称
bucket.creationDateDate存储桶创建时间。

示例

  1. minioClient.listBuckets(function(err, buckets){
  2. if(err)return console.log(err)
  3. console.log('buckets :', buckets)
  4. })

bucketExists(bucketName[, callback])

验证存储桶是否存在。

参数

参数类型描述
bucketNamestring存储桶名称。
callback(err)function如果存储桶存在的话err就是null,否则err.codeNoSuchBucket。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.bucketExists('mybucket',function(err){
  2. if(err){
  3. if(err.code =='NoSuchBucket')return console.log("bucket does not exist.")
  4. return console.log(err)
  5. }
  6. // if err is null it indicates that the bucket exists.
  7. console.log('Bucket exists.')
  8. })

removeBucket(bucketName[, callback])

删除存储桶。

参数

参数类型描述
bucketNamestring存储桶名称。
callback(err)function如果存储桶删除成功则errnull。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.removeBucket('mybucket',function(err){
  2. if(err)return console.log('unable to remove bucket.')
  3. console.log('Bucket removed successfully.')
  4. })

listObjects(bucketName, prefix, recursive)

列出存储桶中所有对象。

参数

参数类型描述
bucketNamestring存储桶名称。
prefixstring要列出的对象的前缀 (可选,默认值是'')。
recursivebooltrue代表递归查找,false代表类似文件夹查找,以'/'分隔,不查子文件夹。(可选,默认值是false

返回值

参数类型描述
streamStream存储桶中对象信息的流。

对象的格式如下:

参数类型描述
obj.namestring对象名称。
obj.prefixstring对象名称的前缀。
obj.sizenumber对象的大小。
obj.etagstring对象的etag值。
obj.lastModifiedDate最后修改时间。

示例

  1. var stream = minioClient.listObjects('mybucket','',true)
  2. stream.on('data',function(obj){ console.log(obj)})
  3. stream.on('error',function(err){ console.log(err)})

listObjectsV2(bucketName, prefix, recursive)

使用S3 listing objects V2版本API列出所有对象。

参数

参数类型描述
bucketNamestring存储桶名称。
prefixstring要列出的对象的前缀。(可选,默认值是''
recursivebooltrue代表递归查找,false代表类似文件夹查找,以'/'分隔,不查子文件夹。(可选,默认值是false

返回值

参数类型描述
streamStream存储桶中对象信息的流。

对象的格式如下:

参数类型描述
obj.namestring对象名称。
obj.prefixstring对象名称的前缀。
obj.sizenumber对象的大小。
obj.etagstring对象的etag值。
obj.lastModifiedDate最后修改时间。

示例

  1. var stream = minioClient.listObjectsV2('mybucket','',true)
  2. stream.on('data',function(obj){ console.log(obj)})
  3. stream.on('error',function(err){ console.log(err)})

listIncompleteUploads(bucketName, prefix, recursive)

列出存储桶中未完整上传的对象。

参数

参数类型描述
bucketnamestring存储桶名称。
prefixstring未完整上传的对象的前缀。(可选,默认值是'')。
recursivebooltrue代表递归查找,false代表类似文件夹查找,以'/'分隔,不查子文件夹。(可选,默认值是false

返回值

参数类型描述
streamStream对象格式如下:
参数类型描述
part.keystring对象名称。
part.uploadIdstring对象的上传ID。
part.sizeInteger未完整上传的对象的大小。

示例

  1. varStream= minioClient.listIncompleteUploads('mybucket','',true)
  2. Stream.on('data',function(obj){
  3. console.log(obj)
  4. })
  5. Stream.on('end',function(){
  6. console.log('End')
  7. })
  8. Stream.on('error',function(err){
  9. console.log(err)
  10. })

3. 操作对象

getObject(bucketName, objectName[, callback])

下载对象。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
callback(err, stream)function回调函数,第一个参数是错误信息。stream是对象的内容。如果没有传callback的话,则返回一个Promise对象。

示例

  1. var size =0
  2. minioClient.getObject('mybucket','photo.jpg',function(err, dataStream){
  3. if(err){
  4. return console.log(err)
  5. }
  6. dataStream.on('data',function(chunk){
  7. size += chunk.length
  8. })
  9. dataStream.on('end',function(){
  10. console.log('End. Total size = '+ size)
  11. })
  12. dataStream.on('error',function(err){
  13. console.log(err)
  14. })
  15. })

getPartialObject(bucketName, objectName, offset, length[, callback])

下载对象中指定区间的字节数组,并返回流。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
offsetnumberoffset是从第几个字节始
lengthnumberlength是要下载的字节数组长度(可选值,如果为空的话则代表从offset一直到文件的末尾)。
callback(err, stream)function回调函数,第一个参数是错误信息。stream是对象的内容。如果没有传callback的话,则返回一个Promise对象。

示例

  1. var size =0
  2. // reads 30 bytes from the offset 10.
  3. minioClient.getPartialObject('mybucket','photo.jpg',10,30,function(err, dataStream){
  4. if(err){
  5. return console.log(err)
  6. }
  7. dataStream.on('data',function(chunk){
  8. size += chunk.length
  9. })
  10. dataStream.on('end',function(){
  11. console.log('End. Total size = '+ size)
  12. })
  13. dataStream.on('error',function(err){
  14. console.log(err)
  15. })
  16. })

fGetObject(bucketName, objectName, filePath[, callback])

下载并将对象保存成本地文件。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
filePathstring要写入的本地文件路径。
callback(err)function如果报错的话,则会调用回调函数,传入err参数。 如果没有传callback的话,则返回一个Promise对象。

示例

  1. var size =0
  2. minioClient.fGetObject('mybucket','photo.jpg','/tmp/photo.jpg',function(err){
  3. if(err){
  4. return console.log(err)
  5. }
  6. console.log('success')
  7. })

putObject(bucketName, objectName, stream, size, contentType[, callback])

从一个stream/Buffer中上传一个对象。

从stream中上传

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
streamStream可以读的流。
sizenumber对象的大小(可选)。
contentTypestring对象的Content-Type(可选,默认是application/octet-stream)。
callback(err, etag)function如果err不是null则代表有错误,etagstring是上传的对象的etag值。如果没有传callback的话,则返回一个Promise对象。

示例

单个对象的最大大小限制在5TB。putObject在对象大于5MiB时,自动使用multiple parts方式上传。这样的话,当上传失败的时候,客户端只需要上传未成功的部分即可(类似断点上传)。上传的对象使用MD5SUM签名进行完整性验证。

  1. varFs=require('fs')
  2. var file ='/tmp/40mbfile'
  3. var fileStream =Fs.createReadStream(file)
  4. var fileStat =Fs.stat(file,function(err, stats){
  5. if(err){
  6. return console.log(err)
  7. }
  8. minioClient.putObject('mybucket','40mbfile', fileStream, stats.size,function(err, etag){
  9. return console.log(err, etag)// err should be null
  10. })
  11. })
从"Buffer"或者"string"上传

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
string or BufferStream or Buffer字符串可者缓冲区
contentTypestring对象的Content-Type(可选,默认是application/octet-stream)。
callback(err, etag)function如果err不是null则代表有错误,etagstring是上传的对象的etag值。

示例

  1. var buffer ='Hello World'
  2. minioClient.putObject('mybucket','hello-file', buffer,function(err, etag){
  3. return console.log(err, etag)// err should be null
  4. })

fPutObject(bucketName, objectName, filePath, contentType[, callback])

上传文件。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
filePathstring要上传的文件路径。
contentTypestring对象的Content-Type。
callback(err, etag)function如果err不是null则代表有错误,etagstring是上传的对象的etag值。如果没有传callback的话,则返回一个Promise对象。

示例

  1. var file ='/tmp/40mbfile'
  2. minioClient.fPutObject('mybucket','40mbfile', file,'application/octet-stream',function(err, etag){
  3. return console.log(err, etag)// err should be null
  4. })

copyObject(bucketName, objectName, sourceObject, conditions[, callback])

将源对象拷贝到指定存储桶的新对象中。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
sourceObjectstring源对象的名称
conditionsCopyConditions允许拷贝需要满足的条件。
callback(err, {etag, lastModified})function如果err不是null则代表有错误,etagstring是上传的对象的etag值,lastModified Date是新拷贝对象的最后修改时间。如果没有传callback的话,则返回一个Promise对象。

示例

  1. var conds =newMinio.CopyConditions()
  2. conds.setMatchETag('bd891862ea3e22c93ed53a098218791d')
  3. minioClient.copyObject('mybucket','newobject','/mybucket/srcobject', conds,function(e, data){
  4. if(e){
  5. return console.log(e)
  6. }
  7. console.log("Successfully copied the object:")
  8. console.log("etag = "+ data.etag +", lastModified = "+ data.lastModified)
  9. })

statObject(bucketName, objectName[, callback])

获取对象的元数据。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
callback(err, stat)function如果err不是null则代表有错误,stat含有对象的元数据信息,格式如下所示。如果没有传callback的话,则返回一个Promise对象。
参数类型描述
stat.sizenumber对象的大小。
stat.etagstring对象的etag值。
stat.contentTypestring对象的Content-Type。
stat.lastModifiedstringLast 最后修改时间。

示例

  1. minioClient.statObject('mybucket','photo.jpg',function(err, stat){
  2. if(err){
  3. return console.log(err)
  4. }
  5. console.log(stat)
  6. })

removeObject(bucketName, objectName[, callback])

删除一个对象。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
callback(err)function如果err不是null则代表有错误。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.removeObject('mybucket','photo.jpg',function(err){
  2. if(err){
  3. return console.log('Unable to remove object', err)
  4. }
  5. console.log('Removed the object')
  6. })

removeIncompleteUpload(bucketName, objectName[, callback])

删除一个未完整上传的对象。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
callback(err)function如果err不是null则代表有错误。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.removeIncompleteUpload('mybucket','photo.jpg',function(err){
  2. if(err){
  3. return console.log('Unable to remove incomplete object', err)
  4. }
  5. console.log('Incomplete object removed successfully.')
  6. })

4. Presigned操作

Presigned URLs用于对私有对象提供临时的上传/下载功能。

presignedUrl(httpMethod, bucketName, objectName, expiry[, reqParams, cb])

生成一个给指定HTTP方法('httpMethod')请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行下载,即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间,默认值是7天。

参数

参数类型描述
httpMethodstringhttp方法,put、get等。
bucketNamestring存储桶名称。
objectNamestring对象名称。
expirynumber失效时间(以秒为单位),默认是7天,不得大于七天。
reqParamsobject请求参数。
callback(err, presignedUrl)function如果err不是null则代表有错误。presignedUrl就是可临时上传/下载文件的URL。如果没有传callback的话,则返回一个Promise对象。

示例1

  1. // presigned url for 'getObject' method.
  2. // expires in a day.
  3. minioClient.presignedUrl('GET','mybucket','hello.txt',24*60*60,function(err, presignedUrl){
  4. if(err)return console.log(err)
  5. console.log(presignedUrl)
  6. })

示例2

  1. // presigned url for 'listObject' method.
  2. // Lists objects in 'myBucket' with prefix 'data'.
  3. // Lists max 1000 of them.
  4. minioClient.presignedUrl('GET','mybucket','',1000,{'prefix':'data','max-keys':1000},function(err, presignedUrl){
  5. if(err)return console.log(err)
  6. console.log(presignedUrl)
  7. })

presignedGetObject(bucketName, objectName, expiry[, cb])

生成一个给HTTP GET请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行下载,即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间,默认值是7天。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
expirynumber失效时间(以秒为单位),默认是7天,不得大于七天。
callback(err, presignedUrl)function如果err不是null则代表有错误。presignedUrl就是可用于临时下载的URL。 如果没有传callback的话,则返回一个Promise对象。

示例

  1. // expires in a day.
  2. minioClient.presignedGetObject('mybucket','hello.txt',24*60*60,function(err, presignedUrl){
  3. if(err)return console.log(err)
  4. console.log(presignedUrl)
  5. })

presignedPutObject(bucketName, objectName, expiry[, callback])

生成一个给HTTP PUT请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行上传,即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间,默认值是7天。

参数

参数类型描述
bucketNamestring存储桶名称。
objectNamestring对象名称。
expirynumber失效时间(以秒为单位),默认是7天,不得大于七天。
callback(err, presignedUrl)function如果err不是null则代表有错误。presignedUrl用于使用PUT请求进行上传。如果没有传callback的话,则返回一个Promise对象。

示例

  1. // expires in a day.
  2. minioClient.presignedPutObject('mybucket','hello.txt',24*60*60,function(err, presignedUrl){
  3. if(err)return console.log(err)
  4. console.log(presignedUrl)
  5. })

presignedPostPolicy(policy[, callback])

允许给POST请求的presigned URL设置条件策略。比如接收上传的存储桶名称、名称前缀、过期策略。

参数

参数类型描述
policyobject通过minioClient.newPostPolicy()创建的Policy对象。
callback(err, {postURL, formData})function如果err不是null则代表有错误。postURL用于使用post请求上传。formData是POST请求体中的键值对对象。如果没有传callback的话,则返回一个Promise对象。

创建策略:

  1. var policy = minioClient.newPostPolicy()

设置上传策略:

  1. // Policy restricted only for bucket 'mybucket'.
  2. policy.setBucket('mybucket')
  3. // Policy restricted only for hello.txt object.
  4. policy.setKey('hello.txt')

或者

  1. // Policy restricted for incoming objects with keyPrefix.
  2. policy.setKeyStartsWith('keyPrefix')
  3. var expires =newDate
  4. expires.setSeconds(24*60*60*10)
  5. // Policy expires in 10 days.
  6. policy.setExpires(expires)
  7. // Only allow 'text'.
  8. policy.setContentType('text/plain')
  9. // Only allow content size in range 1KB to 1MB.
  10. policy.setContentLengthRange(1024,1024*1024)

使用superagent通过浏览器POST你的数据:

  1. minioClient.presignedPostPolicy(policy,function(err, data){
  2. if(err)return console.log(err)
  3. var req = superagent.post(data.postURL)
  4. _.each(data.formData,function(value, key){
  5. req.field(key, value)
  6. })
  7. // file contents.
  8. req.attach('file','/path/to/hello.txt','hello.txt')
  9. req.end(function(err, res){
  10. if(err){
  11. return console.log(err.toString())
  12. }
  13. console.log('Upload successful.')
  14. })
  15. })

5. 存储桶策略/通知

存储桶可以配置在指定事件类型和相应路径上触发通知。

getBucketNotification(bucketName[, cb])

获取指定存储桶名称的通知配置。

参数

参数类型描述
bucketNamestring存储桶名称。
callback(err, bucketNotificationConfig)function如果err不是null则代表有错误。bucketNotificationConfig是相应存储桶上的通知配置对象。如果没有传callback的话,则返回一个Promise对象。

示例

  1. minioClient.getBucketNotification('mybucket',function(err, bucketNotificationConfig){
  2. if(err)return console.log(err)
  3. console.log(bucketNotificationConfig)
  4. })

setBucketNotification(bucketName, bucketNotificationConfig[, callback])

上传一个用户创建的通知配置,并绑定到指定的存储桶上。

参数

参数类型描述
bucketNamestring存储桶名称。
bucketNotificationConfigBucketNotification包含通知配置的Javascript对象。
callback(err)function如果err不是null则代表有错误。如果没有传callback的话,则返回一个Promise对象。

示例

  1. // Create a new notification object
  2. var bucketNotification =newNotify.BucketNotification();
  3. // Setup a new topic configuration
  4. var arn =Notify.newARN('aws','sns','us-west-2','408065449417','TestTopic')
  5. var topic =newNotify.TopicConfig(arn)
  6. topic.addFilterSuffix('.jpg')
  7. topic.addFilterPrefix('myphotos/')
  8. topic.addEvent(Notify.ObjectReducedRedundancyLostObject)
  9. topic.addEvent(Notify.ObjectCreatedAll)
  10. // Add the topic to the overall notification object
  11. bucketNotification.addTopicConfiguration(topic)
  12. minioClient.setBucketNotification('mybucket', bucketNotification,function(err){
  13. if(err)return console.log(err)
  14. console.log('Success')
  15. })

removeAllBucketNotification(bucketName[, callback])

删除指定存储桶上的通知配置。

参数

参数类型描述
bucketNamestring存储桶名称。
callback(err)function如果err不是null则代表有错误。如果没有传callback的话,则返回一个Promise对象。
  1. minioClient.removeAllBucketNotification('my-bucketname',function(e){
  2. if(e){
  3. return console.log(e)
  4. }
  5. console.log("True")
  6. })

listenBucketNotification(bucketName, prefix, suffix, events)

监听存储桶上的通知,可通过前缀、后缀、事件类型进行过滤。使用本API并不需要预先设置存储桶通知。这是Minio的一个扩展API,服务端基于过来的请求使用唯一ID自动注册或者取消注册。

返回一个EventEmitter对象,它可以广播一个通知事件。

停止监听,调用EventEmitterstop()方法。

参数

参数类型描述
bucketNamestring存储桶名称。
prefixstring用于过滤通知的对象名称前缀。
suffixstring用于过滤通知的对象名称后缀。
eventsArray在指定事件类型上开启通知。

这里是你要的完整示例,拿走不谢。

  1. var listener = minioClient.listenBucketNotification('my-bucketname','photos/','.jpg',['s3:ObjectCreated:*'])
  2. listener.on('notification',function(record){
  3. // For example: 's3:ObjectCreated:Put event occurred (2016-08-23T18:26:07.214Z)'
  4. console.log('%s event occurred (%s)', record.eventName, record.eventTime)
  5. listener.stop()
  6. })

getBucketPolicy(bucketName, objectPrefix[, callback])

获取指定存储桶的访问策略,如果objectPrefix不为空,则会取相应对象前缀上的访问策略。

参数

参数类型描述
bucketNamestring存储桶名称。
objectPrefixstring用于过滤的对象前缀,''代表整个存储桶。
callback(err, policy)function如果err不是null则代表有错误。policy是存储桶策略的字符串表示(minio.Policy.NONEminio.Policy.READONLYminio.Policy.WRITEONLY,或者minio.Policy.READWRITE). 如果没有传callback的话,则返回一个Promise对象。
  1. // Retrieve bucket policy of 'my-bucketname' that applies to all objects that
  2. // start with 'img-'.
  3. minioClient.getBucketPolicy('my-bucketname','img-',function(err, policy){
  4. if(err)throw err
  5. console.log(`Bucket policy: ${policy}`)
  6. })

setBucketPolicy(bucketName, objectPrefix, bucketPolicy[, callback])

设置指定存储桶的策略。如果objectPrefix不为空,则会给符合该前缀的对象(们)设置策略。

参数

参数类型描述
bucketNamestring存储桶名称。
objectPrefixstring要设置访问策略的对象前缀。''代表整个存储桶。
bucketPolicystring存储桶策略。可选值有:minio.Policy.NONEminio.Policy.READONLYminio.Policy.WRITEONLY或者minio.Policy.READWRITE
callback(err)function如果err不是null则代表有错误。如果没有传callback的话,则返回一个Promise对象。
  1. // Set the bucket policy of `my-bucketname` to `readonly` (only allow retrieval),
  2. // but only for objects that start with 'img-'.
  3. minioClient.setBucketPolicy('my-bucketname','img-', minio.Policy.READONLY,function(err){
  4. if(err)throw err
  5. console.log('Set bucket policy to \'readonly\'.')
  6. })

6. 了解更多

原文: https://docs.minio.io/cn/javascript-client-api-reference.html