CodeUnderstanding

Understanding Aliyun OSS Python SDK (Draft)

Following code sample shows how to upload an object via Aliyun OSS Python SDK. Please check comments for explanation of each code statement.

# oss2 is Aliyun OSS Python SDK's package name
import oss2

# access_key_id/access_key_secret is credential of requests
access_key_id = 'your-access-key-id'
access_key_secret = 'your-access-key-secret'

bucket_name = 'your-bucket-name'
endpoint = 'http://oss-cn-hangzhou.aliyuncs.com'

# oss2.Auth indicates Signature Version 1 is used to sign requests
auth = oss2.Auth(access_key_id, access_key_secret)

# all bucket and object operations are performed by instances of oss2.Bucket 
bucket = oss2.Bucket(auth, endpoint, bucket_name)

# upload an object with key readme.txt from memory
bucket.put_object('readme.txt', 'content of the object')

Call chain of the above put_object request is as follows

oss2.api.Bucket.put_object() 
-> oss2.api._Base._do()                     # prepare oss2.http.Request
   -> oss2.auth.Auth._sign_request()        # Add HTTP Authorization header
   -> oss2.http.Session.do_request()        # send the request

Request and Response [oss2/http.py]

Class Request and Response are abstractions for HTTP requests and responses. Class Request has following important public data members

Member Name	type	Description
method	str	HTTP methods, such as 'PUT', 'GET'
url	str	The URL to be accessed, e.g. http://bucket-name.oss-cn-hangzhou.aliyuncs.com/api.pdf
params	dict	params represents HTTP query string parameters. It maps query parameter names to values.
headers	CaseInsensitiveDict	headers represents HTTP headers. It maps header names to values.

Class Response's data members are

Member Name	type	Description
status	int	HTTP status code, e.g. 200, 403
headers	CaseInsensitiveDict	HTTP response headers

Authorization Classes [oss2/auth.py]

To support various authorization algorithms and schemes, Python SDK delegates authorization to so called auth-classes. Below is a list of such classes:

Class Name	Description
AnonymousAuth	Do not add authorization information to requests.
Auth	Using Signature Version 1, sign requests with AccessKeyId and AccessKeySecret
StsAuth	Using Signature Version 1, sign requests with STS credentials
AuthV2	Using Signature Version 2, sign requests with AccessKeyId and AccessKeySecret

Each auth-class must implements two interfaces:

def _sign_request(self, req, bucket_name, key):
    """
    Set authorization information in HTTP `Authorization` header. 

    'req' , of type Request, is the request to add authorization information. Its headers and query string parameters etc. have already been initialized.
    'bucket_name' is the bucket's name.
    'key' is the object key.
    """
    pass
    
def _sign_url(self, req, bucket_name, key, expires):
    """
    Generate a presigned URL.
    
    'expires' is the number of seconds after which the presigned request will be expired. For example, a value of 60 means the presigned URL will be expired after 60 seconds.
    """
    pass