From 01fa7bec58cb50d03960560dea4c0520127f25fc Mon Sep 17 00:00:00 2001 From: dingjs <47954233@qq.com> Date: Tue, 19 Dec 2017 08:52:22 +0800 Subject: [PATCH] translate minio-js docs to Chinese. (#650) --- README_zh_CN.md | 197 +++++++ docs/zh_CN/API.md | 1003 ++++++++++++++++++++++++++++++++++++ docs/zh_CN/CONTRIBUTING.md | 23 + 3 files changed, 1223 insertions(+) create mode 100644 README_zh_CN.md create mode 100644 docs/zh_CN/API.md create mode 100644 docs/zh_CN/CONTRIBUTING.md diff --git a/README_zh_CN.md b/README_zh_CN.md new file mode 100644 index 00000000..3b39f7fb --- /dev/null +++ b/README_zh_CN.md @@ -0,0 +1,197 @@ +# 适用于Amazon S3兼容云存储的Minio JavaScript Library [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) + +[![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/) + +Minio JavaScript Client SDK提供简单的API来访问任何Amazon S3兼容的对象存储服务。 + +本快速入门指南将向您展示如何安装客户端SDK并执行示例JavaScript程序。有关API和示例的完整列表，请参阅[JavaScript客户端API参考](https://docs.minio.io/docs/javascript-client-api-reference)文档。 + +本文假设你已经安装了[nodejs](http://nodejs.org/) 。 + +## 使用NPM下载 + +```sh +npm install --save minio +``` + +## 下载并安装源码 + +```sh +git clone https://github.com/minio/minio-js +cd minio-js +npm install +npm install -g +``` + +## 初使化Minio Client + +你需要设置5个属性来链接Minio对象存储服务。 + +| 参数 | 描述 | +| :------- | :------------ | +| endPoint |对象存储服务的URL | +|port| TCP/IP端口号。可选值，如果是使用HTTP的话，默认值是`80`；如果使用HTTPS的话，默认值是`443`。| +| accessKey | Access key是唯一标识你的账户的用户ID。 | +| secretKey | Secret key是你账户的密码。 | +|secure |true代表使用HTTPS | + + +```js +var Minio = require('minio') + +var minioClient = new Minio.Client({ + endPoint: 'play.minio.io', + port: 9000, + secure: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); +``` + +## 示例-文件上传 + +本示例连接到一个对象存储服务，创建一个存储桶并上传一个文件到存储桶中。 + +我们在本示例中使用运行在 [https://play.minio.io:9000](https://play.minio.io:9000) 上的Minio服务，你可以用这个服务来开发和测试。示例中的访问凭据是公开的。 + +#### file-uploader.js + +```js +var Minio = require('minio') + +// Instantiate the minio client with the endpoint +// and access keys as shown below. +var minioClient = new Minio.Client({ + endPoint: 'play.minio.io', + port: 9000, + secure: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); + +// File that needs to be uploaded. +var file = '/tmp/photos-europe.tar' + +// Make a bucket called europetrip. +minioClient.makeBucket('europetrip', 'us-east-1', function(err) { + if (err) return console.log(err) + + console.log('Bucket created successfully in "us-east-1".') + + // Using fPutObject API upload your file to the bucket europetrip. + minioClient.fPutObject('europetrip', 'photos-europe.tar', file, 'application/octet-stream', function(err, etag) { + if (err) return console.log(err) + console.log('File uploaded successfully.') + }); +}); +``` + +#### 运行file-uploader + +```sh +node file-uploader.js +Bucket created successfully in "us-east-1". + +mc ls play/europetrip/ +[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar +``` + +## API文档 + +完整的API文档在这里。 +* [完整API文档](https://docs.minio.io/docs/javascript-client-api-reference) + +### API文档 : 操作存储桶 + +* [`makeBucket`](https://docs.minio.io/docs/javascript-client-api-reference#makeBucket) +* [`listBuckets`](https://docs.minio.io/docs/javascript-client-api-reference#listBuckets) +* [`bucketExists`](https://docs.minio.io/docs/javascript-client-api-reference#bucketExists) +* [`removeBucket`](https://docs.minio.io/docs/javascript-client-api-reference#removeBucket) +* [`listObjects`](https://docs.minio.io/docs/javascript-client-api-reference#listObjects) +* [`listObjectsV2`](https://docs.minio.io/docs/javascript-client-api-reference#listObjectsV2) +* [`listIncompleteUploads`](https://docs.minio.io/docs/javascript-client-api-reference#listIncompleteUploads) + +### API文档 : 操作文件对象 + +* [`fPutObject`](https://docs.minio.io/docs/javascript-client-api-reference#fPutObject) +* [`fGetObject`](https://docs.minio.io/docs/javascript-client-api-reference#fGetObject) + +### API文档 : 操作对象 + +* [`getObject`](https://docs.minio.io/docs/javascript-client-api-reference#getObject) +* [`putObject`](https://docs.minio.io/docs/javascript-client-api-reference#putObject) +* [`copyObject`](https://docs.minio.io/docs/javascript-client-api-reference#copyObject) +* [`statObject`](https://docs.minio.io/docs/javascript-client-api-reference#statObject) +* [`removeObject`](https://docs.minio.io/docs/javascript-client-api-reference#removeObject) +* [`removeIncompleteUpload`](https://docs.minio.io/docs/javascript-client-api-reference#removeIncompleteUpload) + +### API文档 : Presigned操作 + +* [`presignedGetObject`](https://docs.minio.io/docs/javascript-client-api-reference#presignedGetObject) +* [`presignedPutObject`](https://docs.minio.io/docs/javascript-client-api-reference#presignedPutObject) +* [`presignedPostPolicy`](https://docs.minio.io/docs/javascript-client-api-reference#presignedPostPolicy) + +### API文档 : 存储桶通知 + +* [`getBucketNotification`](https://docs.minio.io/docs/javascript-client-api-reference#getBucketNotification) +* [`setBucketNotification`](https://docs.minio.io/docs/javascript-client-api-reference#setBucketNotification) +* [`removeAllBucketNotification`](https://docs.minio.io/docs/javascript-client-api-reference#removeAllBucketNotification) +* [`listenBucketNotification`](https://docs.minio.io/docs/javascript-client-api-reference#listenBucketNotification) (Minio Extension) + +### API文档 : 存储桶策略 + +* [`getBucketPolicy`](https://docs.minio.io/docs/javascript-client-api-reference#getBucketPolicy) +* [`setBucketPolicy`](https://docs.minio.io/docs/javascript-client-api-reference#setBucketPolicy) + + +## 完整示例 + +#### 完整示例 : 操作存储桶 + +* [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js) +* [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js) +* [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js) +* [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js) +* [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js) +* [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js) +* [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js) + +#### 完整示例 : 操作文件对象 +* [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js) +* [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js) + +#### 完整示例 : 操作对象 +* [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js) +* [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js) +* [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js) +* [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js) +* [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js) +* [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js) +* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js) + +#### 完整示例 : Presigned操作 +* [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js) +* [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js) +* [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js) + +####完整示例 : 存储桶通知 +* [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js) +* [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js) +* [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js) +* [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (Minio Extension) + +#### 完整示例 : 存储桶策略 +* [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js) +* [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js) + +## 了解更多 +* [完整文档](https://docs.minio.io) +* [Minio JavaScript Client SDK API文档](https://docs.minio.io/docs/javascript-client-api-reference) +* [创建属于你的购物APP-完整示例](https://docs.minio.io/docs/javascript-shopping-app) + +## 贡献 + +[贡献者指南](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md) + +[![Build Status](https://travis-ci.org/minio/minio-js.svg)](https://travis-ci.org/minio/minio-js) +[![Build status](https://ci.appveyor.com/api/projects/status/1d05e6nvxcelmrak?svg=true)](https://ci.appveyor.com/project/harshavardhana/minio-js) diff --git a/docs/zh_CN/API.md b/docs/zh_CN/API.md new file mode 100644 index 00000000..d8dc3f2d --- /dev/null +++ b/docs/zh_CN/API.md @@ -0,0 +1,1003 @@ +# JavaScript Client API参考文档 [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) + +## 初使化Minio Client object. + +## Minio + +```js +var Minio = require('minio') + +var minioClient = new Minio.Client({ + endPoint: 'play.minio.io', + port: 9000, + secure: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); +``` + +## AWS S3 + +```js +var Minio = require('minio') + +var s3Client = new Minio.Client({ + endPoint: 's3.amazonaws.com', + accessKey: 'YOUR-ACCESSKEYID', + secretKey: 'YOUR-SECRETACCESSKEY' +}) +``` +| 操作存储桶 | 操作对象 | Presigned操作 | 存储桶策略/通知 | +| ------------- |-------------| -----| ----- | +| [`makeBucket`](#makeBucket) | [`getObject`](#getObject) | [`presignedUrl`](#presignedUrl) | [`getBucketNotification`](#getBucketNotification) | +| [`listBuckets`](#listBuckets) | [`getPartialObject`](#getPartialObject) | [`presignedGetObject`](#presignedGetObject) | [`setBucketNotification`](#setBucketNotification) | +| [`bucketExists`](#bucketExists) | [`fGetObject`](#fGetObject) | [`presignedPutObject`](#presignedPutObject) | [`removeAllBucketNotification`](#removeAllBucketNotification) | +| [`removeBucket`](#removeBucket) | [`putObject`](#putObject) | [`presignedPostPolicy`](#presignedPostPolicy) | [`getBucketPolicy`](#getBucketPolicy) | | +| [`listObjects`](#listObjects) | [`fPutObject`](#fPutObject) | | [`setBucketPolicy`](#setBucketPolicy) +| [`listObjectsV2`](#listObjectsV2) | [`copyObject`](#copyObject) | | [`listenBucketNotification`](#listenBucketNotification)| +| [`listIncompleteUploads`](#listIncompleteUploads) | [`statObject`](#statObject) | +| | [`removeObject`](#removeObject) | +| | [`removeIncompleteUpload`](#removeIncompleteUpload) | + + + +## 1. 构造函数 + + +### new Minio.Client ({endPoint, port, secure, accessKey, secretKey}) + +| | +| ---- | +|``new Minio.Client ({endPoint, port, secure, accessKey, secretKey})``| +|初使化一个新的client对象。| + +__参数__ + +| 参数| 类型 | 描述 | +|---|---|---| +| `endPoint` | _string_ | endPoint是一个主机名或者IP地址。 | +| `port` | _number_ | TCP/IP端口号。可选，默认值是，如果是http,则默认80端口，如果是https,则默认是443端口。 | +| `accessKey` | _string_ |accessKey类似于用户ID，用于唯一标识你的账户。 | +|`secretKey` | _string_ | secretKey是你账户的密码。| +|`secure` | _bool_ |如果是true，则用的是https而不是http,默认值是true。 | +|`region` | _string_ |设置该值以覆盖自动发现存储桶region。（可选）| + + +__示例__ + +## 创建连接Minio Server的客户端 + +```js +var Minio = require('minio') + +var minioClient = new Minio.Client({ + endPoint: 'play.minio.io', + port: 9000, + secure: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); +``` + +## 创建连接AWS S3的客户端 + + +```js +var Minio = require('minio') + +var s3Client = new Minio.Client({ + endPoint: 's3.amazonaws.com', + accessKey: 'YOUR-ACCESSKEYID', + secretKey: 'YOUR-SECRETACCESSKEY' +}) +``` + + +## 2. 操作存储桶 + + +### makeBucket(bucketName, region[, callback]) + +创建一个新的存储桶。 + +__参数__ + +| 参数| 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称。 | +| `region` | _string_ | 存储桶被创建的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`对象。 | + + +__示例__ + + +```js +minioClient.makeBucket('mybucket', 'us-east-1', function(err) { + if (err) return console.log('Error creating bucket.', err) + console.log('Bucket created successfully in "us-east-1".') +}) +``` + + +### listBuckets([callback]) + +列出所有存储桶。 + + +__参数__ + + +| 参数| 类型 | 描述 | +|---|---|---| +|`callback(err, bucketStream) ` | _function_ | 回调函数，第一个参数是错误信息。`bucketStream`是带有存储桶信息的流。如果没有传callback的话，则返回一个`Promise`对象。| + +bucketStream格式如下:- + +| 参数| 类型 | 描述 | +|---|---|---| +|`bucket.name` | _string_ |存储桶名称 | +|`bucket.creationDate`| _Date_ |存储桶创建时间。 | + + + +__示例__ + + +```js +minioClient.listBuckets(function(err, buckets) { + if (err) return console.log(err) + console.log('buckets :', buckets) +}) +``` + + +#### bucketExists(bucketName[, callback]) + +验证存储桶是否存在。 + + +__参数__ + + +| 参数| 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `callback(err)` | _function_ | 如果存储桶存在的话`err`就是null，否则`err.code`是`NoSuchBucket`。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + + +```js +minioClient.bucketExists('mybucket', function(err) { + if (err) { + if (err.code == 'NoSuchBucket') return console.log("bucket does not exist.") + return console.log(err) + } + // if err is null it indicates that the bucket exists. + console.log('Bucket exists.') +}) +``` + + +### removeBucket(bucketName[, callback]) + +删除存储桶。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `callback(err)` | _function_ | 如果存储桶删除成功则`err`为`null`。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + + +```js +minioClient.removeBucket('mybucket', function(err) { + if (err) return console.log('unable to remove bucket.') + console.log('Bucket removed successfully.') +}) +``` + + +### listObjects(bucketName, prefix, recursive) + +列出存储桶中所有对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `bucketName` | _string_ | 存储桶名称。 | +| `prefix` | _string_ | 要列出的对象的前缀 (可选，默认值是`''`)。 | +| `recursive` | _bool_ | `true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。（可选，默认值是`false`） | + + +__返回值__ + + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `stream` | _Stream_ | 存储桶中对象信息的流。 | + +对象的格式如下： + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `obj.key` | _string_ | 对象名称。 | +| `obj.size` | _number_ | 对象的大小。 | +| `obj.etag` | _string_ |对象的etag值。 | +| `obj.lastModified` | _Date_ | 最后修改时间。 | + +__示例__ + + +```js +var stream = minioClient.listObjects('mybucket','', true) +stream.on('data', function(obj) { console.log(obj) } ) +stream.on('error', function(err) { console.log(err) } ) +``` + + +### listObjectsV2(bucketName, prefix, recursive) + +使用S3 listing objects V2版本API列出所有对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `bucketName` | _string_ | 存储桶名称。 | +| `prefix` | _string_ | 要列出的对象的前缀。（可选，默认值是`''`） | +| `recursive` | _bool_ | `true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。（可选，默认值是`false`） | + + +__返回值__ + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `stream` | _Stream_ | 存储桶中对象信息的流。 | + +对象的格式如下： + +| 参数 | 类型 | 描述 | +| ---- | ---- | ---- | +| `obj.key` | _string_ | 对象名称。 | +| `obj.size` | _number_ | 对象的大小。 | +| `obj.etag` | _string_ |对象的etag值。 | +| `obj.lastModified` | _Date_ | 最后修改时间。 | + + +__示例__ + + +```js +var stream = minioClient.listObjectsV2('mybucket','', true) +stream.on('data', function(obj) { console.log(obj) } ) +stream.on('error', function(err) { console.log(err) } ) +``` + + + +### listIncompleteUploads(bucketName, prefix, recursive) + +列出存储桶中未完整上传的对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +| ---| ---|---| +| `bucketname` | _string_ | 存储桶名称。 | +| `prefix` | _string_ | 未完整上传的对象的前缀。（可选，默认值是`''`）。 | +| `recursive` | _bool_ | `true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。（可选，默认值是`false`） | + + +__返回值__ + + +| 参数 | 类型 | 描述 | +| ---| ---|---| +| `stream` | _Stream_ | 对象格式如下：| + +| 参数 | 类型 | 描述 | +| ---| ---|---| +| `part.key` | _string_ | 对象名称。| +| `part.uploadId` | _string_ | 对象的上传ID。| +| `part.size` | _Integer_ | 未完整上传的对象的大小。| + +__示例__ + + +```js +var Stream = minioClient.listIncompleteUploads('mybucket', '', true) +Stream.on('data', function(obj) { + console.log(obj) +}) +Stream.on('end', function() { + console.log('End') +}) +Stream.on('error', function(err) { + console.log(err) +}) +``` + +## 3. 操作对象 + + +### getObject(bucketName, objectName[, callback]) + +下载对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称。 | +|`objectName` | _string_ | 对象名称。 | +|`callback(err, stream)` | _function_ | 回调函数，第一个参数是错误信息。`stream`是对象的内容。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + + +```js +var size = 0 +minioClient.getObject('mybucket', 'photo.jpg', function(err, dataStream) { + if (err) { + return console.log(err) + } + dataStream.on('data', function(chunk) { + size += chunk.length + }) + dataStream.on('end', function() { + console.log('End. Total size = ' + size) + }) + dataStream.on('error', function(err) { + console.log(err) + }) +}) +``` + +### getPartialObject(bucketName, objectName, offset, length[, callback]) + +下载对象中指定区间的字节数组，并返回流。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `objectName` | _string_ | 对象名称。 | +| `offset` | _number_ | `offset`是从第几个字节始 | +| `length` | _number_ | `length`是要下载的字节数组长度（可选值，如果为空的话则代表从offset一直到文件的末尾）。 | +|`callback(err, stream)` | _function_ | 回调函数，第一个参数是错误信息。`stream`是对象的内容。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + + +```js +var size = 0 +// reads 30 bytes from the offset 10. +minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, function(err, dataStream) { + if (err) { + return console.log(err) + } + dataStream.on('data', function(chunk) { + size += chunk.length + }) + dataStream.on('end', function() { + console.log('End. Total size = ' + size) + }) + dataStream.on('error', function(err) { + console.log(err) + }) +}) +``` + + +### fGetObject(bucketName, objectName, filePath[, callback]) + +下载并将对象保存成本地文件。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `objectName` |_string_ | 对象名称。 | +| `filePath` | _string_ | 要写入的本地文件路径。 | +| `callback(err)` | _function_ | 如果报错的话，则会调用回调函数，传入`err`参数。 如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +var size = 0 +minioClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function(err) { + if (err) { + return console.log(err) + } + console.log('success') +}) +``` + +### putObject(bucketName, objectName, stream, size, contentType[, callback]) + +从一个stream/Buffer中上传一个对象。 + +##### 从stream中上传 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` |_string_ | 存储桶名称。 | +| `objectName` |_string_ | 对象名称。 | +| `stream` | _Stream_ |可以读的流。 | +|`size` | _number_ | 对象的大小（可选）。 | +|`contentType` | _string_ | 对象的Content-Type（可选，默认是`application/octet-stream`）。| +| `callback(err, etag)` | _function_ | 如果`err`不是null则代表有错误，`etag` _string_是上传的对象的etag值。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + +单个对象的最大大小限制在5TB。putObject在对象大于5MiB时，自动使用multiple parts方式上传。这样的话，当上传失败的时候，客户端只需要上传未成功的部分即可（类似断点上传）。上传的对象使用MD5SUM签名进行完整性验证。 + +```js +var Fs = require('fs') +var file = '/tmp/40mbfile' +var fileStream = Fs.createReadStream(file) +var fileStat = Fs.stat(file, function(err, stats) { + if (err) { + return console.log(err) + } + minioClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function(err, etag) { + return console.log(err, etag) // err should be null + }) +}) +``` + +##### 从"Buffer"或者"string"上传 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` |_string_ | 存储桶名称。 | +| `objectName` |_string_ | 对象名称。 | +|`string or Buffer` | _Stream_ or _Buffer_ |字符串可者缓冲区 | +| `contentType` | _string_ | 对象的Content-Type（可选，默认是`application/octet-stream`）。 | +| `callback(err, etag)` | _function_ |如果`err`不是null则代表有错误，`etag` _string_是上传的对象的etag值。 | + + +__示例__ + + +```js +var buffer = 'Hello World' +minioClient.putObject('mybucket', 'hello-file', buffer, function(err, etag) { + return console.log(err, etag) // err should be null +}) +``` + +### fPutObject(bucketName, objectName, filePath, contentType[, callback]) + +上传文件。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +|`objectName` |_string_ | 对象名称。 | +| `filePath` | _string_ | 要上传的文件路径。 | +| `contentType` | _string_ | 对象的Content-Type。 | +| `callback(err, etag)` | _function_ | 如果`err`不是null则代表有错误，`etag` _string_是上传的对象的etag值。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + + +```js +var file = '/tmp/40mbfile' +minioClient.fPutObject('mybucket', '40mbfile', file, 'application/octet-stream', function(err, etag) { + return console.log(err, etag) // err should be null +}) +``` + + +### copyObject(bucketName, objectName, sourceObject, conditions[, callback]) + +将源对象拷贝到指定存储桶的新对象中。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +|`objectName` |_string_ | 对象名称。 | +| `sourceObject` | _string_ | 源对象的名称 | +| `conditions` | _CopyConditions_ | 允许拷贝需要满足的条件。 | +| `callback(err, {etag, lastModified})` | _function_ | 如果`err`不是null则代表有错误，`etag` _string_是上传的对象的etag值，lastModified _Date_是新拷贝对象的最后修改时间。如果没有传callback的话，则返回一个`Promise`对象。 | + +__示例__ + +```js +var conds = new Minio.CopyConditions() +conds.setMatchETag('bd891862ea3e22c93ed53a098218791d') +minioClient.copyObject('mybucket', 'newobject', '/mybucket/srcobject', conds, function(e, data) { + if (e) { + return console.log(e) + } + console.log("Successfully copied the object:") + console.log("etag = " + data.etag + ", lastModified = " + data.lastModified) +}) +``` + + + +### statObject(bucketName, objectName[, callback]) + +获取对象的元数据。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `objectName` | _string_ | 对象名称。 | +| `callback(err, stat)` | _function_ |如果`err`不是null则代表有错误，`stat`含有对象的元数据信息，格式如下所示。如果没有传callback的话，则返回一个`Promise`对象。 | + + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `stat.size` | _number_ | 对象的大小。 | +| `stat.etag` | _string_ | 对象的etag值。 | +| `stat.contentType` | _string_ | 对象的Content-Type。| +| `stat.lastModified` | _string_ | Last 最后修改时间。| + + +__示例__ + + +```js +minioClient.statObject('mybucket', 'photo.jpg', function(err, stat) { + if (err) { + return console.log(err) + } + console.log(stat) +}) +``` + + +### removeObject(bucketName, objectName[, callback]) + +删除一个对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称。 | +| objectName | _string_ | 对象名称。 | +| `callback(err)` | _function_ | 如果`err`不是null则代表有错误。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +minioClient.removeObject('mybucket', 'photo.jpg', function(err) { + if (err) { + return console.log('Unable to remove object', err) + } + console.log('Removed the object') +}) +``` + + +### removeIncompleteUpload(bucketName, objectName[, callback]) + +删除一个未完整上传的对象。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` |_string_ | 存储桶名称。 | +| `objectName` | _string_ | 对象名称。 | +| `callback(err)` | _function_ |如果`err`不是null则代表有错误。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +minioClient.removeIncompleteUpload('mybucket', 'photo.jpg', function(err) { + if (err) { + return console.log('Unable to remove incomplete object', err) + } + console.log('Incomplete object removed successfully.') +}) +``` + +## 4. Presigned操作 + +Presigned URLs用于对私有对象提供临时的上传/下载功能。 + + +### presignedUrl(httpMethod, bucketName, objectName, expiry[, reqParams, cb]) + +生成一个给指定HTTP方法（'httpMethod'）请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行下载，即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间，默认值是7天。 + + +__参数__ + + + +|参数 | 类型 | 描述 | +|---|---|---| +|`httpMethod` | _string_ | http方法，put、get等。 | +|`bucketName` | _string_ | 存储桶名称。 | +|`objectName` | _string_ | 对象名称。 | +|`expiry` | _number_ | 失效时间（以秒为单位），默认是7天，不得大于七天。 | +|`reqParams` | _object_ | 请求参数。 | +|`callback(err, presignedUrl)` | _function_ | 如果`err`不是null则代表有错误。`presignedUrl`就是可临时上传/下载文件的URL。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例1__ + + +```js +// presigned url for 'getObject' method. +// expires in a day. +minioClient.presignedUrl('GET', 'mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` + + +__示例2__ + + +```js +// presigned url for 'listObject' method. +// Lists objects in 'myBucket' with prefix 'data'. +// Lists max 1000 of them. +minioClient.presignedUrl('GET', 'mybucket', '', 1000, {'prefix': 'data', 'max-keys': 1000}, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` + + +### presignedGetObject(bucketName, objectName, expiry[, cb]) + +生成一个给HTTP GET请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行下载，即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间，默认值是7天。 + + +__参数__ + + + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称。 | +|`objectName` | _string_ | 对象名称。 | +|`expiry` | _number_ | 失效时间（以秒为单位），默认是7天，不得大于七天。 | +|`callback(err, presignedUrl)` | _function_ | 如果`err`不是null则代表有错误。`presignedUrl`就是可用于临时下载的URL。 如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +// expires in a day. +minioClient.presignedGetObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` + + +### presignedPutObject(bucketName, objectName, expiry[, callback]) + +生成一个给HTTP PUT请求用的presigned URL。浏览器/移动端的客户端可以用这个URL进行上传，即使其所在的存储桶是私有的。这个presigned URL可以设置一个失效时间，默认值是7天。 + + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称。 | +|`objectName` | _string_ | 对象名称。 | +|`expiry` | _number_ | 失效时间（以秒为单位），默认是7天，不得大于七天。 | +|`callback(err, presignedUrl)` | _function_ | 如果`err`不是null则代表有错误。`presignedUrl`用于使用PUT请求进行上传。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +// expires in a day. +minioClient.presignedPutObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` + + +### presignedPostPolicy(policy[, callback]) + +允许给POST请求的presigned URL设置条件策略。比如接收上传的存储桶名称、名称前缀、过期策略。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `policy` | _object_ | 通过minioClient.newPostPolicy()创建的Policy对象。 | +| `callback(err, postURL, formData)` | _function_ |如果`err`不是null则代表有错误。`postURL`用于使用post请求上传。`formData`是POST请求体中的键值对对象。如果没有传callback的话，则返回一个`Promise`对象。 | + + +创建策略： + + +```js +var policy = minioClient.newPostPolicy() +``` + +设置上传策略： + +```js +// Policy restricted only for bucket 'mybucket'. +policy.setBucket('mybucket') + +// Policy restricted only for hello.txt object. +policy.setKey('hello.txt') +``` +或者 + +```js +// Policy restricted for incoming objects with keyPrefix. +policy.setKeyStartsWith('keyPrefix') + +var expires = new Date +expires.setSeconds(24 * 60 * 60 * 10) +// Policy expires in 10 days. +policy.setExpires(expires) + +// Only allow 'text'. +policy.setContentType('text/plain') + +// Only allow content size in range 1KB to 1MB. +policy.setContentLengthRange(1024, 1024*1024) +``` + +使用`superagent`通过浏览器POST你的数据： + + +```js +minioClient.presignedPostPolicy(policy, function(err, postURL, formData) { + if (err) return console.log(err) + + var req = superagent.post(postURL) + _.each(formData, function(value, key) { + req.field(key, value) + }) + + // file contents. + req.attach('file', '/path/to/hello.txt', 'hello.txt') + + req.end(function(err, res) { + if (err) { + return console.log(err.toString()) + } + console.log('Upload successful.') + }) +}) +``` + +## 5. 存储桶策略/通知 + +存储桶可以配置在指定事件类型和相应路径上触发通知。 + + +### getBucketNotification(bucketName[, cb]) + +获取指定存储桶名称的通知配置。 + +__参数__ + + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `callback(err, bucketNotificationConfig)` | _function_ | 如果`err`不是null则代表有错误。`bucketNotificationConfig`是相应存储桶上的通知配置对象。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + + +```js +minioClient.getBucketNotification('mybucket', function(err, bucketNotificationConfig) { + if (err) return console.log(err) + console.log(bucketNotificationConfig) +}) +``` + + +### setBucketNotification(bucketName, bucketNotificationConfig[, callback]) + +上传一个用户创建的通知配置，并绑定到指定的存储桶上。 + + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `bucketNotificationConfig` | _BucketNotification_ | 包含通知配置的Javascript对象。 | +| `callback(err)` | _function_ | 如果`err`不是null则代表有错误。如果没有传callback的话，则返回一个`Promise`对象。 | + + +__示例__ + +```js +// Create a new notification object +var bucketNotification = new Notify.BucketNotification(); + +// Setup a new topic configuration +var arn = Notify.newARN('aws', 'sns', 'us-west-2', '408065449417', 'TestTopic') +var topic = new Notify.TopicConfig(arn) +topic.addFilterSuffix('.jpg') +topic.addFilterPrefix('myphotos/') +topic.addEvent(Notify.ObjectReducedRedundancyLostObject) +topic.addEvent(Notify.ObjectCreatedAll) + +// Add the topic to the overall notification object +bucketNotification.addTopicConfiguration(topic) + +minioClient.setBucketNotification('mybucket', bucketNotification, function(err) { + if (err) return console.log(err) + console.log('Success') +}) +``` + + +### removeAllBucketNotification(bucketName[, callback]) + +删除指定存储桶上的通知配置。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `callback(err)` | _function_ | 如果`err`不是null则代表有错误。如果没有传callback的话，则返回一个`Promise`对象。 | + + +```js +minioClient.removeAllBucketNotification('my-bucketname', function(e) { + if (e) { + return console.log(e) + } + console.log("True") +}) +``` + + +### listenBucketNotification(bucketName, prefix, suffix, events) + +监听存储桶上的通知，可通过前缀、后缀、事件类型进行过滤。使用本API并不需要预先设置存储桶通知。这是Minio的一个扩展API，服务端基于过来的请求使用唯一ID自动注册或者取消注册。 + +返回一个`EventEmitter`对象，它可以广播一个`通知`事件。 + +停止监听，调用`EventEmitter`的`stop()`方法。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `prefix` | _string_ | 用于过滤通知的对象名称前缀。 | +| `suffix` | _string_ | 用于过滤通知的对象名称后缀。 | +| `events` | _Array_ | 在指定事件类型上开启通知。 | + +这里是你要的[完整示例](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js)，拿走不谢。 + +```js +var listener = minioClient.listenBucketNotification('my-bucketname', 'photos/', '.jpg', ['s3:ObjectCreated:*']) +listener.on('notification', function(record) { + // For example: 's3:ObjectCreated:Put event occurred (2016-08-23T18:26:07.214Z)' + console.log('%s event occurred (%s)', record.eventName, record.eventTime) + listener.stop() +}) +``` + + +### getBucketPolicy(bucketName, objectPrefix[, callback]) + +获取指定存储桶的访问策略，如果`objectPrefix`不为空，则会取相应对象前缀上的访问策略。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `objectPrefix` | _string_ | 用于过滤的对象前缀，`''`代表整个存储桶。 | +| `callback(err, policy)` | _function_ | 如果`err`不是null则代表有错误。`policy`是存储桶策略的字符串表示(`minio.Policy.NONE`，`minio.Policy.READONLY`，`minio.Policy.WRITEONLY`，或者`minio.Policy.READWRITE`). 如果没有传callback的话，则返回一个`Promise`对象。 | + + +```js +// Retrieve bucket policy of 'my-bucketname' that applies to all objects that +// start with 'img-'. +minioClient.getBucketPolicy('my-bucketname', 'img-', function(err, policy) { + if (err) throw err + + console.log(`Bucket policy: ${policy}`) +}) +``` + + +### setBucketPolicy(bucketName, objectPrefix, bucketPolicy[, callback]) + +设置指定存储桶的策略。如果`objectPrefix`不为空，则会给符合该前缀的对象（们）设置策略。 + +__参数__ + + +| 参数 | 类型 | 描述 | +|---|---|---| +| `bucketName` | _string_ | 存储桶名称。 | +| `objectPrefix` | _string_ | 要设置访问策略的对象前缀。`''`代表整个存储桶。 | +| `bucketPolicy` | _string_ | 存储桶策略。可选值有：`minio.Policy.NONE`，`minio.Policy.READONLY`，`minio.Policy.WRITEONLY`或者`minio.Policy.READWRITE`。 | +| `callback(err)` | _function_ | 如果`err`不是null则代表有错误。如果没有传callback的话，则返回一个`Promise`对象。 | + + +```js +// Set the bucket policy of `my-bucketname` to `readonly` (only allow retrieval), +// but only for objects that start with 'img-'. +minioClient.setBucketPolicy('my-bucketname', 'img-', minio.Policy.READONLY, function(err) { + if (err) throw err + + console.log('Set bucket policy to \'readonly\'.') +}) +``` + + +## 6. 了解更多 + + +- [创建属于你的购物APP示例](https://docs.minio.io/docs/javascript-shopping-app) diff --git a/docs/zh_CN/CONTRIBUTING.md b/docs/zh_CN/CONTRIBUTING.md new file mode 100644 index 00000000..7e890548 --- /dev/null +++ b/docs/zh_CN/CONTRIBUTING.md @@ -0,0 +1,23 @@ +### 设置你的minio-js Github仓库 +Fork [minio-js upstream](https://github.com/minio/minio-js/fork) 源码仓库到你的个人仓库。 + +Minio Javascript使用[gulp](http://gulpjs.com/)来管理它的依赖。 + +```bash +$ git clone https://github.com/$USER_ID/minio-js +$ cd minio-js +$ npm install +$ gulp +... +``` + +### 开发者指南 + +``minio-js`` 欢迎各位有识之士贡献自己的力量。为了让大家配合起来更默契，我们做出如下约定： + +* fork项目并修改，我们鼓励大家进行pull request。 + - Fork项目 + - 创建你的特性分支 (git checkout -b my-new-feature) + - Commit你的修改(git commit -am 'Add some feature') + - Push到远程分支(git push origin my-new-feature) + - 创建一个Pull Request