JavaScript 客戶端 API 參考

初始化 MinIO Client 物件。

MinIO

import * as Minio from 'minio'

const minioClient = new Minio.Client({
  endPoint: 'play.min.io',
  port: 9000,
  useSSL: true,
  accessKey: 'Q3AM3UQ867SPQQA43P2F',
  secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
})

AWS S3

import * as Minio from 'minio'

const s3Client = new Minio.Client({
  endPoint: 's3.amazonaws.com',
  accessKey: 'YOUR-ACCESSKEYID',
  secretKey: 'YOUR-SECRETACCESSKEY',
})

儲存桶操作	物件操作	預先簽署的操作	儲存桶原則和通知操作	自訂設定
`makeBucket`	`getObject`	`presignedUrl`	`getBucketNotification`	`setS3TransferAccelerate`
`listBuckets`	`getPartialObject`	`presignedGetObject`	`setBucketNotification`
`bucketExists`	`fGetObject`	`presignedPutObject`	`removeAllBucketNotification`
`removeBucket`	`putObject`	`presignedPostPolicy`	`getBucketPolicy`
`listObjects`	`fPutObject`		`setBucketPolicy`
`listObjectsV2`	`copyObject`		`listenBucketNotification`
`listIncompleteUploads`	`statObject`
`getBucketVersioning`	`removeObject`
`setBucketVersioning`	`removeObjects`
`getBucketTagging`	`removeIncompleteUpload`
`setBucketTagging`	`putObjectRetention`
`removeBucketTagging`	`getObjectRetention`
`setBucketLifecycle`	`setObjectTagging`
`getBucketLifecycle`	`removeObjectTagging`
`removeBucketLifecycle`	`getObjectTagging`
`setObjectLockConfig`	`getObjectLegalHold`
`getObjectLockConfig`	`setObjectLegalHold`
`getBucketEncryption`	`composeObject`
`setBucketEncryption`	`selectObjectContent`
`removeBucketEncryption`
`setBucketReplication`
`getBucketReplication`
`removeBucketReplication`

1. 建構函式

new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize})


`new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize})`
初始化新的客戶端物件。

參數

參數	類型	描述
`endPoint`	字串	endPoint 是主機名稱或 IP 位址。
`port`	數字	TCP/IP 通訊埠號碼。此輸入為選用。HTTP 的預設值設為 80，HTTPS 的預設值設為 443。
`useSSL`	布林值	如果設定為 true，則使用 https 而非 http。預設值為 true。
`accessKey`	字串	accessKey 就像使用者 ID 一樣，可唯一識別您的帳戶。
`secretKey`	字串	secretKey 是您帳戶的密碼。
`sessionToken`	字串	設定此值以提供 x-amz-security-token (AWS S3 特定)。(選用)
`region`	字串	設定此值以覆寫區域快取。(選用)
`transport`	字串	設定此值以傳入自訂傳輸。(選用)
`partSize`	數字	設定此值以覆寫多部分上傳的預設部分大小 64MB。(選用)
`pathStyle`	布林值	設定此值以覆寫非 AWS 端點的預設存取行為 (路徑)。預設值為 true。(選用)
`transportAgent`	代理	設定此值以提供自訂 HTTP(s) 代理，以處理逾時、TLS 處理和低階插槽設定。(選用)

範例

為 MinIO 建立用戶端

import * as Minio from 'minio'

const minioClient = new Minio.Client({
  endPoint: 'play.min.io',
  port: 9000,
  useSSL: true,
  accessKey: 'Q3AM3UQ867SPQQA43P2F',
  secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
})

為 AWS S3 建立用戶端

import * as Minio from 'minio'

const s3Client = new Minio.Client({
  endPoint: 's3.amazonaws.com',
  accessKey: 'YOUR-ACCESSKEYID',
  secretKey: 'YOUR-SECRETACCESSKEY',
})

使用臨時憑證建立用戶端

import * as Minio from 'minio'

const s3Client = new Minio.Client({
  endPoint: 's3.amazonaws.com',
  accessKey: 'YOUR-TEMP-ACCESSKEYID',
  secretKey: 'YOUR-TEMP-SECRETACCESSKEY',
  sessionToken: 'YOUR-TEMP-SESSIONTOKEN',
})

使用自訂 HTTPS 代理建立用戶端

import * as Minio from 'minio'
import * as fs from 'fs'
import * as https from 'https'

const s3Client = new Minio.Client({
  endPoint: 'play.min.io',
  port: 9000,
  useSSL: true,
  accessKey: 'Q3AM3UQ867SPQQA43P2F',
  secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
  transportAgent: new https.Agent({
    timeout: 10000,
    ca: fs.readFileSync('path/to/ca.cert'),
    cert: fs.readFileSync('path/to/public.cert'),
    key: fs.readFileSync('path/to/secret.key'),
    keepAlive: false,
  }),
})

注意：以下範例可能依賴頂層的 await。

2. 儲存桶操作

async makeBucket(bucketName, [region, makeOpts]): Promise

建立新的儲存桶。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`region`	字串	建立儲存桶的區域。此參數為選用。預設值為 us-east-1。
`makeOpts`	物件	建立儲存桶的選項。例如：`{ObjectLocking:true}` （選用）

範例

await minioClient.makeBucket('mybucket', 'us-east-1')
console.log('Bucket created successfully in "us-east-1".')

範例 1 建立啟用物件鎖定的儲存桶。

minioClient.makeBucket('mybucket', 'us-east-1', { ObjectLocking: true }, function (err) {
  if (err) return console.log('Error creating bucket with object lock.', err)
  console.log('Bucket created successfully in "us-east-1" and enabled object lock')
})

listBuckets()

列出所有儲存桶。

參數

NIL

傳回格式如下的物件陣列：-

參數	類型	描述
`bucket.name`	字串	儲存桶名稱
`bucket.creationDate`	日期	儲存桶建立的日期。

範例

請參閱：list-buckets.mjs

try {
  const buckets = await minioClient.listBuckets()
  console.log('Success', buckets)
} catch (err) {
  console.log(err.message)
}

async bucketExists(bucketName): Promise

檢查儲存桶是否存在。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

const exists = await minioClient.bucketExists('mybucket')
if (exists) {
  return console.log('Bucket exists.')
}

removeBucket(bucketName[, callback])

移除儲存桶。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`callback(err)`	函數	如果儲存桶成功移除，則 `err` 為 `null`。如果沒有傳遞回呼函數，則會傳回 `Promise`。

範例

try {
  await minioClient.removeBucket('mybucket')
  console.log('Bucket removed successfully.')
} catch (err) {
  console.log('unable to remove bucket.')
}

listObjects(bucketName, prefix, recursive [,listOpts])

列出儲存桶中的所有物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`prefix`	字串	應列出的物件前綴（選用，預設為 `''`）。
`recursive`	布林值	`true` 表示遞迴樣式清單，`false` 表示以 '/' 分隔的目錄樣式清單。（選用，預設為 `false`）。
`listOpts`	物件	列出物件的查詢參數，可以包含 `{IncludeVersion: _bool_ }` （選用）

傳回值

參數	類型	描述
`串流`	串流	發出儲存桶中物件的串流。

物件的格式如下

參數	類型	描述
`obj.name`	字串	物件的名稱。
`obj.prefix`	字串	物件前綴的名稱。
`obj.size`	數字	物件的大小。
`obj.etag`	字串	物件的 etag。
`obj.versionId`	字串	物件的 versionId。
`obj.isDeleteMarker`	布林值	如果為刪除標記，則為 true。
`obj.lastModified`	日期	修改時間戳記。

範例

const data = []
const stream = minioClient.listObjects('mybucket', '', true)
stream.on('data', function (obj) {
  data.push(obj)
})
stream.on('end', function () {
  console.log(data)
})
stream.on('error', function (err) {
  console.log(err)
})

範例 1 取得物件版本

const data = []
const stream = minioClient.listObjects('mybucket', '', true, { IncludeVersion: true })
stream.on('data', function (obj) {
  data.push(obj)
})
stream.on('end', function () {
  console.log(data)
})
stream.on('error', function (err) {
  console.log(err)
})

listObjectsV2(bucketName, prefix, recursive, startAfter)

使用 S3 列出物件 V2 API 列出儲存桶中的所有物件

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`prefix`	字串	應列出的物件前綴（選用，預設為 `''`）。
`recursive`	布林值	`true` 表示遞迴樣式清單，`false` 表示以 '/' 分隔的目錄樣式清單。（選用，預設為 `false`）。
`startAfter`	字串	指定在列出儲存桶中的物件時，要從哪個物件名稱開始。（選用，預設為 `''`）。

傳回值

參數	類型	描述
`串流`	串流	發出儲存桶中物件的串流。

物件的格式如下

參數	類型	描述
`obj.name`	字串	物件的名稱。
`obj.prefix`	字串	物件前綴的名稱。
`obj.size`	數字	物件的大小。
`obj.etag`	字串	物件的 etag。
`obj.lastModified`	日期	修改時間戳記。

範例

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

listObjectsV2WithMetadata(bucketName, prefix, recursive, startAfter)

使用 S3 列出物件 V2 API 列出儲存桶中的所有物件及其 metadata

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`prefix`	字串	應列出的物件前綴（選用，預設為 `''`）。
`recursive`	布林值	`true` 表示遞迴樣式清單，`false` 表示以 '/' 分隔的目錄樣式清單。（選用，預設為 `false`）。
`startAfter`	字串	指定在列出儲存桶中的物件時，要從哪個物件名稱開始。（選用，預設為 `''`）。

傳回值

參數	類型	描述
`串流`	串流	發出儲存桶中物件的串流。

物件的格式如下

參數	類型	描述
`obj.name`	字串	物件的名稱。
`obj.prefix`	字串	物件前綴的名稱。
`obj.size`	數字	物件的大小。
`obj.etag`	字串	物件的 etag。
`obj.lastModified`	日期	修改時間戳記。
`obj.metadata`	物件	物件的 metadata。

範例

const stream = minioClient.extensions.listObjectsV2WithMetadata('mybucket', '', true, '')
stream.on('data', function (obj) {
  console.log(obj)
})
stream.on('error', function (err) {
  console.log(err)
})

listIncompleteUploads(bucketName, prefix, recursive)

列出儲存桶中部分上傳的物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`prefix`	字串	部分上傳的物件名稱前綴。（選用，預設為 `''`）
`recursive`	布林值	`true` 表示遞迴樣式清單，`false` 表示以 '/' 分隔的目錄樣式清單。（選用，預設為 `false`）。

傳回值

參數	類型	描述
`串流`	串流	發出格式如下的物件

參數	類型	描述
`part.key`	字串	物件的名稱。
`part.uploadId`	字串	物件的上傳 ID。
`part.size`	整數	部分上傳的物件的大小。

範例

const 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)
})

getBucketVersioning(bucketName)

取得儲存桶的版本控制狀態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

const versionInfo = await minioClient.getBucketVersioning('bucketname')
console.log('Success ', versionInfo)

setBucketVersioning(bucketName, versioningConfig)

設定儲存桶的版本控制狀態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`versioningConfig`	物件	版本控制設定，例如：`{Status:"Enabled"}`

範例

const versioningConfig = { Status: 'Enabled' }
await minioClient.setBucketVersioning('bucketname', versioningConfig)

setBucketReplication(bucketName, replicationConfig)

設定儲存桶的複寫設定

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`replicationConfig`	物件	複寫設定，以 JSON 物件表示

範例

const arnFromMcCli = 'arn:minio:replication::b22d653b-e4fb-4c5d-8140-7694c8e72ed4:dest-bucket'
const replicationConfig = {
  role: arnFromMcCli,
  rules: [
    {
      ID: 'cisea130mbms6splbmg0',
      Status: 'Enabled',
      Priority: 1,
      DeleteMarkerReplication: { Status: 'Enabled' },
      DeleteReplication: { Status: 'Enabled' },
      Destination: {
        Bucket: 'arn:aws:s3:::dest-bucket',
        StorageClass: 'REDUCED_REDUNDANCY',
      },
      SourceSelectionCriteria: { ReplicaModifications: { Status: 'Enabled' } },
      Filter: {
        //Possible values.
        // Prefix: '/',
        // Tag: [{ 'Key': 'key1', 'Value': 'value1' }, { 'Key': 'key2', 'Value': 'value2' }],//if only this,  =>    'DeleteMarkerReplication': { 'Status': 'Disabled' },
        And: {
          Prefix: '/',
          Tag: [
            { Key: 'key1', Value: 'value1' },
            { Key: 'key2', Value: 'value2' },
          ],
        },
      },
      ExistingObjectReplication: { Status: 'Enabled' },
    },
  ],
}

await s3Client.setBucketReplication('source-bucket', replicationConfig)

getBucketReplication(bucketName)

取得儲存桶的複寫設定

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

const replicatinConfig = await minioClient.getBucketReplication('source-bucket')
console.log(replicatinConfig)

removeBucketReplication(bucketName)

移除儲存桶的複寫設定

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

await minioClient.removeBucketReplication('source-bucket')

setBucketTagging(bucketName, tags)

設定儲存桶的標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`tags`	物件	標籤對應組態，例如：`{<tag-key-1>:<tag-value-1>}`

範例

await minioClient.setBucketTagging('bucketname', tags)

removeBucketTagging(bucketName, callback)

移除儲存桶的標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

await minioClient.removeBucketTagging('bucketname')

getBucketTagging(bucketName)

取得儲存桶的標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

const tagList = await minioClient.getBucketTagging('bucketname')
console.log(tagList)

setBucketLifecycle(bucketName, lifecycleConfig)

設定儲存桶的生命週期組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`lifecycleConfig`	物件	有效的生命週期組態或（`null` 或 `''`），以移除原則組態

範例

const lifecycleConfig = {
  Rule: [
    {
      ID: 'Transition and Expiration Rule',
      Status: 'Enabled',
      Filter: {
        Prefix: '',
      },
      Expiration: {
        Days: '3650',
      },
    },
  ],
}

await minioClient.setBucketLifecycle('bucketname', lifecycleConfig)

getBucketLifecycle(bucketName)

取得儲存桶的生命週期組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

await minioClient.getBucketLifecycle('bucketname')

removeBucketLifecycle(bucketName)

移除儲存桶的生命週期組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例

await minioClient.removeBucketLifecycle('bucketname')

setObjectLockConfig(bucketName, lockConfig [, callback])

設定儲存桶的物件鎖定組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`lockConfig`	物件	鎖定組態可以是 `{}` 以重設，或包含以下所有鍵/值對的物件：`{mode: ["COMPLIANCE"/'GOVERNANCE'], unit: ["Days"/"Years"], validity: <a-valid-number-for-unit>}`

範例 1

await minioClient.setObjectLockConfig('my-bucketname', { mode: 'COMPLIANCE', unit: 'Days', validity: 10 })

範例 2 重設/移除儲存桶的物件鎖定組態。

await s3Client.setObjectLockConfig('my-bucketname', {})

getObjectLockConfig(bucketName [, callback])

取得儲存桶的鎖定組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例取得儲存桶的物件鎖定組態

await minioClient.getObjectLockConfig('my-bucketname')

setBucketEncryption(bucketName [,encryptionConfig])

設定儲存桶的加密組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`encryptionConfig`	物件	加密組態可以省略或為 `{}`，或為有效的支援加密組態。預設為：`{Rule:[{ApplyServerSideEncryptionByDefault:{SSEAlgorithm:"AES256"}}]}`。

範例設定儲存桶的加密組態

await s3Client.setBucketEncryption('my-bucketname')

範例 1 設定儲存桶的加密組態，使用演算法

await s3Client.setBucketEncryption('my-bucketname', {
  Rule: [{ ApplyServerSideEncryptionByDefault: { SSEAlgorithm: 'AES256' } }],
})

getBucketEncryption(bucketName)

取得儲存桶的加密組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例取得儲存桶的加密組態

await s3Client.getBucketEncryption('my-bucketname')

removeBucketEncryption(bucketName)

移除儲存桶的加密組態

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。

範例移除儲存桶的加密組態

await s3Client.removeBucketEncryption('my-bucketname')

3. 物件操作

getObject(bucketName, objectName, getOpts)

以串流方式下載物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`getOpts`	物件	取得物件的選項。預設為 `{}`。（選用）

傳回值

參數	類型	描述
`串流`	`stream.Readable`	發出物件內容的串流。

範例

let size = 0
const dataStream = await minioClient.getObject('mybucket', 'photo.jpg')
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)
})

範例

取得特定物件版本。

let size = 0
const dataStream = await minioClient.getObject('mybucket', 'photo.jpg', { versionId: 'my-versionId' })
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)
})

範例

取得伺服器端加密物件。

let size = 0
const dataStream = await minioClient.getObject('mybucket', 'photo.jpg', {
  SSECustomerAlgorithm: 'AES256',
  SSECustomerKey: 'YOUR_KEY',
  SSECustomerKeyMD5: 'YOUR_MD5',
})
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, getOpts[, callback])

以串流方式下載物件的指定範圍位元組。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`offset`	數字	串流將從哪個 `offset` 開始。
`length`	數字	將在串流中讀取的物件 `length` （選用，如果未指定，則會從 offset 讀取檔案的其餘部分）。
`getOpts`	物件	取得物件的選項。預設為 `{}`。（選用）
`callback(err, stream)`	函數	如果發生錯誤，則會使用 `err` 呼叫回呼函數。`stream` 是物件內容串流。如果沒有傳遞回呼函數，則會傳回 `Promise`。

傳回值

參數	類型	描述
`串流`	串流	發出物件內容的串流。

範例

let size = 0
// reads 30 bytes from the offset 10.
const dataStream = await minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30)
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)
})

範例取得物件的特定版本

const versionedObjSize = 0
// reads 30 bytes from the offset 10.
const dataStream = await minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, { versionId: 'my-versionId' })
dataStream.on('data', function (chunk) {
  versionedObjSize += chunk.length
})
dataStream.on('end', function () {
  console.log('End. Total size = ' + versionedObjSize)
})
dataStream.on('error', function (err) {
  console.log(err)
})

範例取得伺服器端加密物件。

const versionedObjSize = 0
// reads 30 bytes from the offset 10.
const dataStream = await minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, {
  SSECustomerAlgorithm: 'AES256',
  SSECustomerKey: 'YOUR_KEY',
  SSECustomerKeyMD5: 'YOUR_MD5',
})
dataStream.on('data', function (chunk) {
  versionedObjSize += chunk.length
})
dataStream.on('end', function () {
  console.log('End. Total size = ' + versionedObjSize)
})
dataStream.on('error', function (err) {
  console.log(err)
})

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

下載物件並將其儲存為本機檔案系統中的檔案。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`filePath`	字串	本機檔案系統上將寫入物件資料的路徑。
`getOpts`	物件	取得物件的選項。預設為 `{}`。（選用）
`callback(err)`	函數	如果發生錯誤，則會使用 `err` 呼叫回呼函數。如果沒有傳遞回呼函數，則會傳回 `Promise`。

傳回值

值	類型	描述
`err`	物件	發生任何失敗時的錯誤
`file`	file	指定 `filePath` 的串流輸出檔案

範例

minioClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function (err) {
  if (err) {
    return console.log(err)
  }
  console.log('success')
})

範例將特定物件版本串流到檔案中。

minioClient.fGetObject(bucketName, objNameValue, './download/MyImage.jpg', { versionId: 'my-versionId' }, function (e) {
  if (e) {
    return console.log(e)
  }
  console.log('success')
})

範例將伺服器端加密物件串流到檔案中。

minioClient.fGetObject(
  bucketName,
  objNameValue,
  './download/MyImage.jpg',
  {
    SSECustomerAlgorithm: 'AES256',
    SSECustomerKey: 'YOUR_KEY',
    SSECustomerKeyMD5: 'YOUR_MD5',
  },
  function (e) {
    if (e) {
      return console.log(e)
    }
    console.log('success')
  },
)

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

從串流/Buffer 上傳物件。

從串流

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`串流`	串流	可讀取的串流。
`size`	數字	物件的大小（選用）。
`metaData`	Javascript 物件	物件的 metaData（選用）。
`callback(err, objInfo)`	函數	非 null 的 `err` 表示發生錯誤，如果成功，`objInfo` 包含物件的 `etag` 字串和 `versionId` 字串。如果沒有傳遞回呼函數，則會傳回 `Promise`。

傳回值

值	類型	描述
`err`	物件	發生任何失敗時的錯誤
`objInfo.etag`	字串	物件的 `etag`
`objInfo.versionId`	字串	物件的 `versionId`（選用）

範例

單一物件的最大大小限制為 5TB。putObject 會以多個部分透明地上傳大於 64MiB 的物件。上傳的資料會使用 MD5SUM 簽章仔細驗證。

import * as Fs from 'fs'
const file = '/tmp/40mbfile'
const fileStream = Fs.createReadStream(file)
const fileStat = Fs.stat(file, function (err, stats) {
  if (err) {
    return console.log(err)
  }
  minioClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function (err, objInfo) {
    if (err) {
      return console.log(err) // err should be null
    }
    console.log('Success', objInfo)
  })
})

從「Buffer」或「字串」

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`字串或 Buffer`	串流或 Buffer	可讀取的串流。
`metaData`	Javascript 物件	物件的 metaData（選用）。
`callback(err, etag)`	函數	非 null 的 `err` 表示發生錯誤，`etag` 字串是上傳物件的 etag。

範例

const 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, metaData[, callback])

從檔案上傳內容到 objectName。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`filePath`	字串	要上傳的檔案路徑。
`metaData`	Javascript 物件	物件的中繼資料。
`callback(err, objInfo)` 函式: 非 null 的 `err` 表示錯誤， `objInfo` 物件是關於已上傳物件的資訊，包含 `versionId` 字串和 `etag` 字串。

傳回值

值	類型	描述
`err`	物件	發生任何失敗時的錯誤
`objInfo.etag`	字串	物件的 `etag`
`objInfo.versionId`	字串	物件的 `versionId`（選用）

範例

單一物件的最大大小限制為 5TB。fPutObject 會以多個部分透明地上傳大於 64MiB 的物件。上傳的資料會使用 MD5SUM 簽名仔細驗證。

const file = '/tmp/40mbfile'
const metaData = {
  'Content-Type': 'text/html',
  'Content-Language': 123,
  'X-Amz-Meta-Testing': 1234,
  example: 5678,
}
minioClient.fPutObject('mybucket', '40mbfile', file, metaData, function (err, objInfo) {
  if (err) {
    return console.log(err)
  }
  console.log('Success', objInfo.etag, objInfo.versionId)
})

copyObject(targetBucketName, targetObjectName, sourceBucketNameAndObjectName [,conditions])

將來源物件複製到指定儲存桶中的新物件。

參數

參數	類型	描述
`targetBucketName`	字串	儲存桶的名稱。
`targetObjectName`	字串	物件的名稱。
`sourceBucketNameAndObjectName`	字串	要複製的檔案路徑。
`conditions`	CopyConditions	允許物件複製前必須滿足的條件。

範例

const conds = new Minio.CopyConditions()
conds.setMatchETag('bd891862ea3e22c93ed53a098218791d')
await minioClient.copyObject('mybucket', 'newobject', '/mybucket/srcobject', conds)

statObject(bucketName, objectName, statOpts[, callback])

取得物件的中繼資料。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`statOpts`	物件	物件的版本，格式為 `{versionId:"my-versionId"}`。預設值為 `{}`。（選用）
`callback(err, stat)`	函數	如果發生錯誤，`err` 不為 `null`，`stat` 包含下面列出的物件資訊。如果未傳遞回呼函式，則會回傳 `Promise`。

傳回值

參數	類型	描述
`stat.size`	數字	物件的大小。
`stat.etag`	字串	物件的 etag。
`stat.versionId`	字串	物件的版本。
`stat.metaData`	Javascript 物件	物件的 metadata。
`stat.lastModified`	日期	上次修改時間戳記。

範例

const stat = await minioClient.statObject('mybucket', 'photo.jpg')
console.log(stat)

物件版本的 stat 範例

const stat = await minioClient.statObject('mybucket', 'photo.jpg', { versionId: 'my-versionId' })
console.log(stat)

removeObject(bucketName, objectName [, removeOpts])

移除物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`removeOpts`	物件	物件的版本，格式為 `{versionId:"my-versionId", governanceBypass: true or false }`。預設值為 `{}`。（選用）

範例 1

;(async function () {
  await minioClient.removeObject('mybucket', 'photo.jpg')
  console.log('Removed the object')
})()

範例 2 刪除特定版本的物件

;(async function () {
  try {
    await minioClient.removeObject('mybucket', 'photo.jpg', { versionId: 'my-versionId' })
    console.log('Removed the object')
  } catch (err) {
    console.log('Unable to remove object', err)
  }
})()

範例 3 使用 governanceBypass 移除選項，移除以保留模式 GOVERNANCE 鎖定的物件版本

;(async function () {
  await s3Client.removeObject('my-bucketname', 'my-objectname', { versionId: 'my-versionId', governanceBypass: true })
  console.log('Success')
})()

removeObjects(bucketName, objectsList)

移除 objectsList 中的所有物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectsList`	物件	要移除的儲存桶中物件的清單。可以是以下任一格式：1. 物件名稱清單，以字串陣列表示，這些字串是物件金鑰：`['objectname1','objectname2']` 2. 物件名稱和 VersionId 清單，以物件表示：[{name:”my-obj-name”,versionId:”my-versionId”}]

範例

const objectsList = []

// List all object paths in bucket my-bucketname.
const objectsStream = s3Client.listObjects('my-bucketname', 'my-prefixname', true)

objectsStream.on('data', function (obj) {
  objectsList.push(obj.name)
})

objectsStream.on('error', function (e) {
  console.log(e)
})

objectsStream.on('end', async () => {
  await s3Client.removeObjects(bucket, objectsList)
})

範例 1

支援版本控制

const objectsList = []
const bucket = 'my-bucket'
const prefix = 'my-prefix'
const recursive = false

const objectsStream = s3Client.listObjects(bucket, prefix, recursive, { IncludeVersion: true })
objectsStream.on('data', function (obj) {
  objectsList.push(obj)
})
objectsStream.on('error', function (e) {
  return console.log(e)
})
objectsStream.on('end', async () => {
  await s3Client.removeObjects(bucket, objectsList)
})

removeIncompleteUpload(bucketName, objectName)

移除部分上傳的物件。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。

範例

await minioClient.removeIncompleteUpload('mybucket', 'photo.jpg')

async putObjectRetention(bucketName, objectName [, retentionOpts])

對物件套用保留。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`retentionOpts`	物件	保留的選項，例如： `{ governanceBypass:true/false ,mode:COMPLIANCE/GOVERNANCE, retainUntilDate: _date_ , versionId:"my-versionId" }`。預設值為 `{}`（選用）

範例對物件套用物件保留

const bucketName = 'my-bucket'
const objectName = 'my-object'

const expirationDate = new Date()
expirationDate.setDate(expirationDate.getDate() + 1)
expirationDate.setUTCHours(0, 0, 0, 0) //Should be start of the day.(midnight)
const versionId = 'e67b4b08-144d-4fc4-ba15-43c3f7f9ba74'

await minioClient.putObjectRetention(bucketName, objectName, {
  Mode: 'GOVERNANCE',
  retainUntilDate: retainUntilDate.toISOString(),
  versionId: versionId,
})

getObjectRetention(bucketName, objectName [, getOpts])

取得物件的保留設定

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`getOpts`	物件	保留的選項，例如：`{ versionId:"my-versionId" }`。預設值為 `{}`（選用）

範例 1

const retentionInfo = await minioClient.getObjectRetention('bucketname', 'objectname')
console.log(retentionInfo)

範例 2

const retInfoForVersionId = await minioClient.getObjectRetention('bucketname', 'objectname', {
  versionId: 'my-versionId',
})
console.log(retInfoForVersionId)

setObjectTagging(bucketName, objectName, tags[, putOpts])

在物件上放置標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`tags`	物件	標籤對應組態，例如：`{<tag-key-1>:<tag-value-1>}`
`putOpts`	物件	預設值為 {}。例如 `{versionId:"my-version-id"}`。（選用）

範例

await minioClient.setObjectTagging('bucketname', 'object-name', tags)

範例 1 在物件的版本上放置標籤。

await minioClient.setObjectTagging('bucketname', 'object-name', tags, { versionId: 'my-version-id' })

removeObjectTagging(bucketName, objectName[, removeOpts])

移除物件上的標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`removeOpts`	物件	預設值為 {}。例如 `{versionId:"my-version-id"}`。（選用）

範例

await minioClient.removeObjectTagging('bucketname', 'object-name')

範例 1 移除物件版本上的標籤。

await minioClient.removeObjectTagging('bucketname', 'object-name', { versionId: 'my-object-version-id' })

getObjectTagging(bucketName, objectName[, getOpts])

取得物件的標籤

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`getOpts`	物件	預設值為 {}。例如 `{versionId:"my-version-id"}`。（選用）

範例

console.log(await minioClient.getObjectTagging('bucketname', 'object-name'))

範例 1 取得物件版本上的標籤。

console.log(await minioClient.getObjectTagging('bucketname', 'object-name', { versionId: 'my-object-version-id' }))

getObjectLegalHold(bucketName, objectName, getOpts)

取得物件上的法律保留。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`getOpts`	物件	法律保留設定選項。例如 `{versionId:'my-version-uuid'}`。預設值為 `{}`。

範例 1

取得物件的法律保留。

const legalholdStatus = await minioClient.getObjectLegalHold('bucketName', 'objectName')

範例 2

取得具有 versionId 的物件的法律保留。

const legalholdStatus = await minioClient.getObjectLegalHold('bucketName', 'objectName', {
  versionId: 'my-obj-version-uuid',
})

setObjectLegalHold(bucketName, objectName, [,setOpts])

設定物件上的法律保留。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`setOpts`	物件	要設定的法律保留設定選項。例如 `{versionId:'my-version-uuid', status:'ON or OFF'}`。如果未傳遞，則預設值為 `{status:'ON'}`。

範例 1

設定物件的法律保留。

const legalholdStatus = await minioClient.setObjectLegalHold('bucketName', 'objectName', { Status: 'ON' })

範例 2

設定具有 versionId 的物件的法律保留。

const legalholdStatus = await minioClient.setObjectLegalHold('bucketName', 'objectName', {
  Status: 'ON',
  versionId: 'my-obj-version-uuid',
})

composeObject(destObjConfig, sourceObjectList)

從部分組成物件

參數

參數	類型	描述
`destObjConfig`	物件	類型為 CopyDestinationOptions 的目的地物件設定
`sourceObjectList`	object[]	要組成物件的物件 (部分) 來源陣列。每個部分設定的類型應為 CopySourceOptions

範例 1

從其部分組成物件。

import * as minio from 'minio'

const sourceList = [
  new minio.CopySourceOptions({
    Bucket: 'source-bucket',
    Object: 'parta',
  }),
  new minio.CopySourceOptions({
    Bucket: 'source-bucket',
    Object: 'partb',
  }),
  new minio.CopySourceOptions({
    Bucket: 'source-bucket',
    Object: 'partc',
  }),
  new minio.CopySourceOptions({
    Bucket: 'source-bucket',
    Object: 'partd',
  }),
]

const destOption = new minio.CopyDestinationOptions({
  Bucket: 'dest-bucket',
  Object: '100MB.zip',
})

//using Promise style.
await minioClient.composeObject(destOption, sourceList)

selectObjectContent(bucketName, objectName, selectOpts)

選取物件的內容 (S3 Select)。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`selectOpts`	物件

範例 1 選取所有值

const selectOpts = {
  expression: 'SELECT * FROM s3object s where s."Name" = \'Jane\'',
  expressionType: 'SQL',
  inputSerialization: {
    CSV: { FileHeaderInfo: 'Use', RecordDelimiter: '\n', FieldDelimiter: ',' },
    CompressionType: 'NONE',
  },
  outputSerialization: { CSV: { RecordDelimiter: '\n', FieldDelimiter: ',' } },
  requestProgress: { Enabled: true },
}

const res = await minioClient.selectObjectContent('bucketName', 'objectName', selectOpts)
console.log(res)

4. 預先簽署的操作

會產生預先簽署的 URL，以暫時下載/上傳私有物件。

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

針對提供的 HTTP 方法 ‘httpMethod’ 產生預先簽署的 URL。瀏覽器/行動用戶端可以指向此 URL，直接下載物件，即使儲存桶是私有的也一樣。此預先簽署的 URL 可以有相關聯的到期時間（以秒為單位），在此時間之後，URL 將不再有效。預設值為 7 天。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`expiry`	數字	到期時間（以秒為單位）。預設值為 7 天。（選用）
`reqParams`	物件	要求參數。（選用）例如 {versionId:”10fa9946-3f64-4137-a58f-888065c0732e”}
`requestDate`	日期	日期物件，將在此日期發出 URL。預設值為現在。（選用）

範例 1

// presigned url for 'getObject' method.
// expires in a day.
const presignedUrl = await minioClient.presignedUrl('GET', 'mybucket', 'hello.txt', 24 * 60 * 60)
console.log(presignedUrl)

範例 2

// presigned url for 'listObject' method.
// Lists objects in 'myBucket' with prefix 'data'.
// Lists max 1000 of them.
await minioClient.presignedUrl('GET', 'mybucket', '', 1000, { prefix: 'data', 'max-keys': 1000 })

範例 3

// Get Object with versionid
await minioClient.presignedUrl('GET', 'mybucket', '', 1000, { versionId: '10fa9946-3f64-4137-a58f-888065c0732e' })

presignedGetObject(bucketName, objectName[, expiry, respHeaders, requestDate])

針對 HTTP GET 操作產生預先簽署的 URL。瀏覽器/行動用戶端可以指向此 URL，直接下載物件，即使儲存桶是私有的也一樣。此預先簽署的 URL 可以有相關聯的到期時間（以秒為單位），在此時間之後，URL 將不再有效。預設值為 7 天。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`expiry`	數字	到期時間（以秒為單位）。預設值為 7 天。（選用）
`respHeaders`	物件	要覆寫的回應標頭（選用）
`requestDate`	日期	日期物件，將在此日期發出 URL。預設值為現在。（選用）

範例

// expires in a day.
const presignedUrl = await minioClient.presignedGetObject('mybucket', 'hello.txt', 24 * 60 * 60)
console.log(presignedUrl)

presignedPutObject(bucketName, objectName [,expiry])

針對 HTTP PUT 操作產生預先簽署的 URL。瀏覽器/行動用戶端可以指向此 URL，直接將物件上傳到儲存桶，即使它是私有的也一樣。此預先簽署的 URL 可以有相關聯的到期時間（以秒為單位），在此時間之後，URL 將不再有效。預設值為 7 天。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`objectName`	字串	物件的名稱。
`expiry`	數字	到期時間（以秒為單位）。預設值為 7 天。

範例

// expires in a day.
const presignedUrl = await minioClient.presignedPutObject('mybucket', 'hello.txt', 24 * 60 * 60)
console.log(presignedUrl)

presignedPostPolicy(policy)

允許為 POST 操作的預先簽署 URL 設定原則條件。可以設定諸如接收物件上傳的儲存桶名稱、金鑰名稱前置詞、到期原則等原則。

參數

參數	類型	描述
`policy`	物件	由 minioClient.newPostPolicy() 建立的原則物件

建立原則

const policy = minioClient.newPostPolicy()

套用上傳原則限制

// Policy restricted only for bucket 'mybucket'.
policy.setBucket('mybucket')

// Policy restricted only for hello.txt object.
policy.setKey('hello.txt')

或

// Policy restricted for incoming objects with keyPrefix.
policy.setKeyStartsWith('keyPrefix')

const expires = new Date()
expires.setSeconds(24 * 60 * 60 * 10)
// Policy expires in 10 days.
policy.setExpires(expires)

// Only allow 'text'.
policy.setContentType('text/plain')

// Set content disposition response header.
policy.setContentDisposition('attachment; filename=text.txt')

// Only allow content size in range 1KB to 1MB.
policy.setContentLengthRange(1024, 1024 * 1024)

// Set key-value user defined metadata
policy.setUserMetaData({
  key: 'value',
})

使用 superagent 從瀏覽器 POST 您的內容

const { postURL, formData } = await minioClient.presignedPostPolicy(policy)
const 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])

擷取儲存在 S3 提供者中且屬於指定儲存桶名稱的通知設定。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`callback(err, bucketNotificationConfig)`	函數	回呼函式會在發生錯誤時使用非 `null` 的 err 值呼叫。 `bucketNotificationConfig` 將會是包含與 bucketName 相關聯的所有通知設定的物件。如果沒有傳遞回呼函式，則會傳回 `Promise`。

範例

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

setBucketNotification(bucketName, bucketNotificationConfig[, callback])

上傳使用者建立的通知設定，並將其與指定的儲存桶名稱建立關聯。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`bucketNotificationConfig`	BucketNotification	包含通知設定的 Javascript 物件。
`callback(err)`	函數	回呼函式會在發生錯誤時使用非 `null` 的 err 值呼叫。如果沒有傳遞回呼函式，則會傳回 `Promise`。

範例

// Create a new notification object
const bucketNotification = new Minio.NotificationConfig()

// Setup a new Queue configuration
const arn = Minio.buildARN('aws', 'sqs', 'us-west-2', '1', 'webhook')
const queue = new Minio.QueueConfig(arn)
queue.addFilterSuffix('.jpg')
queue.addFilterPrefix('myphotos/')
queue.addEvent(Minio.ObjectReducedRedundancyLostObject)
queue.addEvent(Minio.ObjectCreatedAll)

// Add the queue to the overall notification object
bucketNotification.add(queue)

minioClient.setBucketNotification('mybucket', bucketNotification, function (err) {
  if (err) return console.log(err)
  console.log('Success')
})

removeAllBucketNotification(bucketName[, callback])

移除與指定儲存桶相關聯的儲存桶通知設定。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱
`callback(err)`	函數	回呼函式會在發生錯誤時使用非 `null` 的 err 值呼叫。如果沒有傳遞回呼函式，則會傳回 `Promise`。

minioClient.removeAllBucketNotification('my-bucketname', function (e) {
  if (e) {
    return console.log(e)
  }
  console.log('True')
})

listenBucketNotification(bucketName, prefix, suffix, events)

監聽儲存桶上的通知。此外，可以為前綴、後綴和事件提供篩選器。使用此 API 不需要事先設定儲存桶通知。這是一個 MinIO 擴充 API，伺服器會根據傳入的請求自動註冊和取消註冊唯一識別符。

傳回一個 EventEmitter，它會發出一個攜帶記錄的 notification 事件。

要停止監聽，請在傳回的 EventEmitter 上呼叫 .stop()。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱
`prefix`	字串	用於篩選通知的物件鍵前綴。
`suffix`	字串	用於篩選通知的物件鍵後綴。
`events`	陣列	針對特定事件類型啟用通知。

請參閱此處以取得完整範例。

const 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()
})

async getBucketPolicy(bucketName: string): Promise

取得與指定儲存桶相關聯的儲存桶政策。如果 objectPrefix 不為空，儲存桶政策也會根據物件權限進行篩選。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱

// Retrieve bucket policy of 'my-bucketname'
const policy = await minioClient.getBucketPolicy('my-bucketname')

console.log(`Bucket policy file: ${policy}`)

async setBucketPolicy(bucketName, bucketPolicy): Promise

在指定的儲存桶上設定儲存桶政策。 bucketPolicy 的詳細資訊請參閱此處。

參數

參數	類型	描述
`bucketName`	字串	儲存桶的名稱。
`bucketPolicy`	字串	儲存桶政策。

// Set the bucket policy of `my-bucketname`
await minioClient.setBucketPolicy('my-bucketname', JSON.stringify(policy))

6. 自訂設定

setS3TransferAccelerate(endpoint)

為後續的所有 API 請求設定 AWS S3 傳輸加速端點。注意：此 API 僅適用於 AWS S3，對於 S3 相容的物件儲存服務則不執行任何操作。

參數

參數	類型	描述
`endpoint`	字串	設定為新的 S3 傳輸加速端點。

7. HTTP 請求選項

setRequestOptions(options)

設定 HTTP/HTTPS 請求選項。支援的選項包括 agent (http.Agent())、 family (解析 host 或 hostname 時使用的 IP 位址系列) 和 tls 相關選項（'agent'、'ca'、'cert'、'ciphers'、'clientCertEngine'、'crl'、'dhparam'、'ecdhCurve'、'honorCipherOrder'、'key'、'passphrase'、'pfx'、'rejectUnauthorized'、'secureOptions'、'secureProtocol'、'servername'、'sessionIdContext'），詳情請參閱此處

// Do not reject self signed certificates.
minioClient.setRequestOptions({ rejectUnauthorized: false })

7. 進一步探索

建立您自己的購物應用程式範例