ossslim

README

ossslim

Slim Aliyun OSS client.

You can create (upload), get (download), delete, list files on OSS.

Command line:

go install -v github.com/caiguanhao/ossslim/oss@latest

Usage:

package main

import (
	"bytes"
	"crypto/rand"
	"fmt"
	"time"

	"github.com/caiguanhao/ossslim"
)

func main() {
	client := ossslim.Client{
		AccessKeyId:     "xxxxxxxxxxxxxxxx",
		AccessKeySecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		Prefix:          "https://abc.oss-cn-hongkong.aliyuncs.com",
		Bucket:          "abc",
	}

	buf := make([]byte, 1024)
	_, err := rand.Read(buf)
	if err != nil {
		panic(err)
	}

	file := time.Now().UTC().Format("tmp/20060102150405")
	req, err := client.Upload(file, bytes.NewReader(buf), nil, "")
	if err != nil {
		panic(err)
	}
	fmt.Println(req.URL())
	// https://abc.oss-cn-hongkong.aliyuncs.com/tmp/20201229130519

	result, err := client.List("tmp/", false)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Files)
	// [{tmp/20201229130519 2020-12-29T13:05:20.000Z "13BB571C15022FC9211A85AF85272B85" 1024}]

	var buffer bytes.Buffer
	req, err = client.Download(file, &buffer)
	if err != nil {
		panic(err)
	}
	fmt.Println(bytes.Equal(buf, buffer.Bytes()))
	// true

	err = client.Delete(file)
	if err != nil {
		panic(err)
	}

	result, err = client.List("tmp/", false)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Files)
	// []

	const MB = 1 << 20
	expiredAfter := 2 * time.Minute
	form := client.PostForm("/foo/bar", 1*MB, expiredAfter)
	fmt.Println(form)
	// map[OSSAccessKeyId:... key:foo/bar policy:... signature:...]
}

Documentation

Index

• type Client
  • func (c *Client) Delete(remotes ...string) error
  • func (c *Client) DeleteWithContext(ctx context.Context, remotes ...string) error
  • func (c *Client) Download(remote string, respBody io.Writer) (*Request, error)
  • func (c *Client) DownloadAsync(remote string, respBody io.Writer) (*Request, error)
  • func (c *Client) DownloadAsyncWithContext(ctx context.Context, remote string, respBody io.Writer) (*Request, error)
  • func (c *Client) DownloadWithContext(ctx context.Context, remote string, respBody io.Writer) (*Request, error)
  • func (c *Client) Exists(remote string) (bool, *Request, error)
  • func (c *Client) ExistsWithContext(ctx context.Context, remote string) (exists bool, req *Request, err error)
  • func (c *Client) ImageInfo(remote string) (*ImageInfo, *Request, error)
  • func (c *Client) ImageInfoWithContext(ctx context.Context, remote string) (info *ImageInfo, req *Request, err error)
  • func (c *Client) List(prefix string, recursive bool) (ListResult, error)
  • func (c *Client) ListWithContext(ctx context.Context, prefix string, recursive bool) (result ListResult, err error)
  • func (c *Client) PostForm(key string, maxSize int64, duration time.Duration, ...) map[string]string
  • func (c *Client) URL(remote string) string
  • func (c *Client) Upload(remote string, reqBody io.Reader, reqBodyMd5 []byte, contentType string) (*Request, error)
  • func (c *Client) UploadWithContext(ctx context.Context, remote string, reqBody io.Reader, reqBodyMd5 []byte, ...) (*Request, error)
• type Directory
• type File
• type ImageInfo
• type ListResult
• type Request
  • func (req *Request) String() string
  • func (req *Request) URL() string

Types

type Client

type Client struct {
	AccessKeyId     string
	AccessKeySecret string
	Prefix          string
	Bucket          string
}

An OSS client must have prefix, bucket, access key ID and access key secret. Prefix should be a string like this: https://<your-bucket>.<region>.aliyuncs.com.

func (*Client) Delete

func (c *Client) Delete(remotes ...string) error

Delete wraps DeleteWithContext using context.Background.

func (*Client) DeleteWithContext

func (c *Client) DeleteWithContext(ctx context.Context, remotes ...string) error

Delete creates and executes a delete request for multiple remote keys (paths) at the same time.

func (*Client) Download

func (c *Client) Download(remote string, respBody io.Writer) (*Request, error)

Download wraps DownloadWithContext using context.Background.

func (*Client) DownloadAsync

func (c *Client) DownloadAsync(remote string, respBody io.Writer) (*Request, error)

DownloadAsync wraps DownloadAsyncWithContext using context.Background.

func (*Client) DownloadAsyncWithContext

func (c *Client) DownloadAsyncWithContext(ctx context.Context, remote string, respBody io.Writer) (*Request, error)

DownloadAsync is like Download but won't wait till download is complete.

func (*Client) DownloadWithContext

func (c *Client) DownloadWithContext(ctx context.Context, remote string, respBody io.Writer) (*Request, error)

Download creates and executes a download request from remote path to respBody (io.Writer), returns the request and error. You can use bytes.Buffer to download the file to memory. If you want to have more than one destination, use io.MultiWriter.

func (*Client) Exists

func (c *Client) Exists(remote string) (bool, *Request, error)

func (*Client) ExistsWithContext

func (c *Client) ExistsWithContext(ctx context.Context, remote string) (exists bool, req *Request, err error)

func (*Client) ImageInfo

func (c *Client) ImageInfo(remote string) (*ImageInfo, *Request, error)

func (*Client) ImageInfoWithContext

func (c *Client) ImageInfoWithContext(ctx context.Context, remote string) (info *ImageInfo, req *Request, err error)

func (*Client) List

func (c *Client) List(prefix string, recursive bool) (ListResult, error)

List wraps ListWithContext using context.Background.

func (*Client) ListWithContext

func (c *Client) ListWithContext(ctx context.Context, prefix string, recursive bool) (result ListResult, err error)

List creates and executes a list request for remote files and directories under prefix, recursively if recursive is set to true.

func (*Client) PostForm

func (c *Client) PostForm(key string, maxSize int64, duration time.Duration, extraConditions ...interface{}) map[string]string

PostForm generates field names and values ("token") for multipart form. This is generally used when frontend user asks backend server for a token to upload a file to OSS. The "key" is the path to remote file. If "maxSize" is greater than 0, file larger than the "maxSize" bytes limit will not be uploaded. The token will be expired after "duration" time, default is 10 minutes. You can provide "extraConditions" like below to add limits to the uploaded file:

client.PostForm(key, 0, 0,
	[]string{"starts-with", "$content-type", "application/"},
	map[string]string{"x-oss-object-acl": "public-read"},
)

For more info, visit https://help.aliyun.com/document_detail/31988.html#title-5go-s2f-dnw

func (*Client) URL

func (c *Client) URL(remote string) string

URL generates URL without query string for remote file.

func (*Client) Upload

func (c *Client) Upload(remote string, reqBody io.Reader, reqBodyMd5 []byte, contentType string) (*Request, error)

Upload wraps UploadWithContext using context.Background.

func (*Client) UploadWithContext

func (c *Client) UploadWithContext(ctx context.Context, remote string, reqBody io.Reader, reqBodyMd5 []byte, contentType string) (*Request, error)

Upload creates and executes a upload request for reqBody (io.Reader) to remote path, returns the request and error. reqBodyMd5 can be nil, OSS will run MD5 check if it is provided. If contentType is empty, "application/octet-stream" will be used. If the body is bytes, use bytes.NewReader. If it is a string, use strings.NewReader.

type Directory

type Directory struct {
	Name string `xml:"Prefix"`
}

type File

type File struct {
	Name         string `xml:"Key"`
	LastModified string
	ETag         string
	Size         int64
}

type ImageInfo

type ImageInfo struct {
	Size   int64
	Format string
	Width  int
	Height int
}

type ListResult

type ListResult struct {
	Prefix string
	Files  []File
	Dirs   []Directory
}

type Request

type Request struct {
	Response              *http.Response
	ResponseContentLength *int64
	// contains filtered or unexported fields
}

func (*Request) String

func (req *Request) String() string

func (*Request) URL

func (req *Request) URL() string