快速开始

Qiniu S3 API 完全兼容 AWS S3 API，客户端在创建连接时只需做如下配置:

• 指定访问域名 (endpoint) 为 Qiniu S3 API 对应域名，如 https://api-s3.qiniu.com

• 指定访问空间区域 (bucket region) 为 Qiniu S3 API 对应区域，如 cn-east-1

• 指定访问密钥 (access key id && secret access key) 为七牛云存储密钥

• 指定访问方式为 URL 路径 (path-style) 方式

• 分块传输每块大小必须为 4M 的整数倍，即 4M * N (N >= 1)

示例代码

注意: 本示例使用 Golang 编写，其他语言请参考 AWS SDK 中更多示例。

初始化 (Setup SDK)

package main

import (
    "strings"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

const (
    s3host      = "https://api-s3.qiniu.com"
    s3region    = "cn-east-1"
    s3pathstyle = true
)

var (
    s3client *s3.S3
)

func main() {
    s3provider := credentials.StaticProvider{
        Value: credentials.Value{
            AccessKeyId: "<your-qiniu-access-key-id>",
            SecretAccessKey: "<your-qiniu-access-key-secret>",
        },
    }
    s3credential := credentials.NewCredentials(&s3provider)

    s3session := session.New()
    s3session.Config.WithEndpoint(s3host)
    s3session.Config.WithRegion(s3region)
    s3session.Config.WithCredentials(s3credential)
    s3session.Config.WithS3ForcePathStyle(s3pathstyle)
    s3session.Config.WithMaxRetries(1)

    s3client = s3.New(s3session, nil)

    // your logic codes
}

创建空间 (Create Bucket)

// normal bucket in cn-east-1 region
func CreateBucket(s3client *s3.S3, bucketName, region string) (err error) {
    input := s3.CreateBucketInput{
        Bucket: aws.String("your-bucket-name"),
        CreateBucketConfiguration: &s3.CreateBucketConfiguration{
            LocationConstraint: aws.String("cn-east-1"),
        },
    }

    _, err = s3client.CreateBucket(&input)
    return
}

// line storage bucket in cn-north-1 region
func CreateLineBucket(s3client *s3.S3, buketName string) (err error) {
    input := s3.CreateBucketInput{
        Bucket: aws.String("your-line-bucket-name"),
        CreateBucketConfiguration: &s3.CreateBucketConfiguration{
            LocationConstraint: aws.String("cn-north-1"),
        },
    }

    request, _ := s3client.CreateBucketRequest(&input)
    request.HTTPRequest.Header.Add("X-Amz-Storage-Class", "line") // since s3 sdk does not support assign storage class within input, we use a custom header instead.

    err = s3client.Send()
    return
}

上传对象 (Upload Object)

// upload a file
func CreateObjectWithFile(s3client *s3.S3, bucketName, objectName, filename string) error {
    fd, err := os.Open(filename)
    if err != nil {
        return err
    }

    input := s3.PutObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectName),
        Body:   fd,
    }

    _, err := s3client.PutObject(&input)
    return err
}

获取对象 (Download Object)

func GetObject(s3client *s3.S3, bucketName, objectName string) (io.ReadCloser, error) {
    input := s3.GetObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectName),
    }

    return s3client.GetObject(&input)
}

删除对象 (Delete Object)

func DeleteObject(s3client *s3.S3, bucketName, objectName string) (err error) {
    input := s3.DeleteObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectName),
    }

    _, err = s3client.DeleteObject(&input)
    return
}

删除空间 (Delete Bucket)

func DeleteBucket(s3client *s3.S3, bucketName string) (err error) {
    input := s3.DeleteBucketInput{
        Bucket: aws.String(bucketName),
    }

    _, err = s3client.DeleteBucket(&input)
    return
}