aliyun

README

Go SDK for Aliyun

This is not a typical SDK as it won't try to provide all APIs.

For the complete APIs see the official https://github.com/aliyun/alibaba-cloud-sdk-go.

Products & APIs

STS

• AssumeRole
• Cache

MTS

• Transcode-Job

Live

• Record create & decribe

Other repo: https://github.com/BPing/aliyun-live-go-sdk

OSS

https://github.com/aliyun/aliyun-oss-go-sdk is good enough.

MNS

• Different Restful APIs and authorization
• Queue & Messages

ACM

• Get/listen config

Usage

The typical usage is:

s := aliyun.NewSigner("id", "secret")
api := YourImplementedAPI{}
var resp APIResponseType

// just use Get for most APIs
err := aliyun.Get(&http.Client{}, s, api, "host", &resp)

// which equals to
f := json.Unmarshal // or xml.Unmarshal if you API use XML
url := "host" + ? + s.Sign(api)
rawResponse, err := http.Get(url) // http level error if any
err = HandleResp(rawResponse, f, &resp) // return a CanonicalizedError if any

License

MIT

Documentation

Overview

Package aliyun contains a library for development around Alibaba Cloud Services.

It aims to provide primitives for making requests to any services, and wrappers/tools around APIs for better user-friendly experience.

The API, Signer & CanonicalizedError are three key primitives that can be used for almost all services.

See sub-packages for API examples.

Index

• Constants
• func FillOSS(v url.Values, o OSS)
• func FormatT(t time.Time) string
• func Get(cl *http.Client, s Signer, a API, host string, resp interface{}) error
• func HandleResp(raw *http.Response, f func([]byte, interface{}) error, resp interface{}) (err error)
• func RandString(n int) string
• func TimeoutClient(d time.Duration) *http.Client
• type API
• type AccessKey
  • func NewAccessKey(id, secret string) *AccessKey
  • func (s *AccessKey) ID() string
  • func (s *AccessKey) Sign(a API) string
• type Base
  • func (Base) Method() string
  • func (Base) Nonce() string
• type CanonicalizedError
  • func (ce *CanonicalizedError) Error() string
• type OSS
• type Signer

Constants

const (
	XMLFormat  = "XML"                  // default by Aliyun official
	JSONFormat = "JSON"                 // force by this package
	TimeFormat = "2006-01-02T15:04:05Z" // official UTC time format
)

Aliyun constants

const (
	ErrCodeForbidden             = "Forbidden"
	ErrCodeInternalError         = "InternalError"
	ErrCodeInvalidParameter      = "InvalidParameter"
	ErrCodeUnknownError          = "UnknownError"
	ErrCodeSignatureNonceUsed    = "SignatureNonceUsed"
	ErrCodeUnsupportedHTTPMethod = "UnsupportedHTTPMethod"
	ErrCodeAPINotFound           = "InvalidApi.NotFound"
	ErrCodeMissingSecurityToken  = "MissingSecurityToken"
	ErrCodeSignatureDoesNotMatch = "SignatureDoesNotMatch"
)

some common error codes for all products more on https://error-center.aliyun.com/status/product/Public

Functions

func FillOSS

func FillOSS(v url.Values, o OSS)

FillOSS helps filling the OSS to the param.

func FormatT

func FormatT(t time.Time) string

FormatT converts a Time to Aliyun format time string, e.g., 2006-01-02T15:04:05Z.

func Get

func Get(cl *http.Client, s Signer, a API, host string, resp interface{}) error

Get makes a HTTP GET request to the host for the provided API, and marshal the response into the value pointed by resp.

func HandleResp

func HandleResp(raw *http.Response, f func([]byte, interface{}) error, resp interface{}) (err error)

HandleResp reads the raw HTTP response and checks if any error returned. Errors other than io/json error should be a CanonicalizedError. The body is unmarshaled to the provided interface resp using the function f. If f is nil, it defaults to json.Unmarshal. It is the caller's responsibility to close the body.

func RandString

func RandString(n int) string

RandString returns a random string with the given length n.

func TimeoutClient

func TimeoutClient(d time.Duration) *http.Client

TimeoutClient returns a http.Client with timeout set. Set timeout longer than the max wait time for long polling requests.

Types

type API

type API interface {
	// Param returns the API specific parameters.
	// These will combine with the common param to get a signature.
	Param() url.Values
	// Version returns the API specific version,
	// usually in the form of a date string.
	Version() string
	// Nonce returns a random string to migate repeat-attack.
	// It gives the freedom for each API to specify it's
	// own randomness.
	Nonce() string
	// Method returns the HTTP method the API used to
	// make the request.
	Method() string
}

An API abstracts the unique parts of an Aliyun API for a single request. The Signer then signs the API to protect against different attacks.

type AccessKey

type AccessKey struct {
	// contains filtered or unexported fields
}

AccessKey is an id-secret pair obtained from Aliyun to access the resources (sign the requests).

func NewAccessKey

func NewAccessKey(id, secret string) *AccessKey

NewAccessKey returns a AccessKey to sign the APIs using the JSON format.

func (*AccessKey) ID

func (s *AccessKey) ID() string

ID returns the access ID.

func (*AccessKey) Sign

func (s *AccessKey) Sign(a API) string

Sign signs the API.

type Base

type Base struct{}

Base implements parts for the API with a 32 bytes string nonce and HTTP GET method.

func (Base) Method

func (Base) Method() string

Method returns GET (the most common method).

func (Base) Nonce

func (Base) Nonce() string

Nonce returns a random 32 bytes string.

type CanonicalizedError

type CanonicalizedError struct {
	XMLName   xml.Name `json:"-" xml:"Error"`
	Code      string   `json:"Code,omitempty" xml:"Code,omitempty"`
	Message   string   `json:"Message,omitempty" xml:"Message,omitempty"`
	RequestID string   `json:"RequestId,omitempty" xml:"RequestId,omitempty"`
	HostID    string   `json:"HostId,omitempty" xml:"HostId,omitempty"`
	Status    int      `json:"status,omitempty"` // from HTTP
}

A CanonicalizedError defines the common request response if any error occurs. It also implements the error interface.

func (*CanonicalizedError) Error

func (ce *CanonicalizedError) Error() string

type OSS

type OSS struct {
	Bucket   string `json:"OssBucket"`
	Endpoint string `json:"OssEndpoint"`
	Object   string `json:"OssObject"`
}

An OSS defines a unique OSS resource. OSS is the fundamental service used by most other services.

type Signer

type Signer interface {
	// Sign signs the API according to the Aliyun specification:
	// https://help.aliyun.com/document_detail/50284.html &
	// https://help.aliyun.com/document_detail/50286.html.
	// It returns the query part of the request including
	// the signature.
	Sign(API) string
}

A Signer signs the APIs.