对象存储公开API目录
API概览
OSS产品提供以下相关API接口
API | 描述 |
---|---|
PutObjectTags | 给某个存储空间下的对象(Object)添加或修改标签。 |
DeleteObjectTags | 删除某个存储空间下的指定对象(Object)下的全部标签。 |
GetObjectTags | 获取某个存储空间下的对象(Object)的标签。 |
PutBucketTags | 给某个存储空间(Bucket)添加或修改标签。 |
DeleteBucketTags | 删除某个存储空间(Bucket)的全部标签。 |
GetBucketTags | 获取某个存储空间(Bucket)的标签。 |
AddNotify | 添加事件通知规则。 |
GetNotify | 获取某个存储空间(Bucket)的标签。 |
DescribeSTS | 获取用户临时上传文件至对象存储签名。 |
- 认证方式.md#认证方式)
- 1.公共请求参数.md#1公共请求参数)
- 2.签名机制.md#2签名机制)
- 步骤一:构造规范化请求字符串.md#步骤一构造规范化请求字符串)
- 步骤二:构造签名字符串.md#步骤二构造签名字符串)
- 3.获取签名代码.md#2获取签名代码)
- 访问地址
访问地址
地区 | 访问地址 |
---|---|
中国大陆 | cdsapi.capitalonline.net |
亚太地区 | cdsapi-asia.capitalonline.net |
欧美地区 | cdsapi-us.capitalonline.net |
实例
PutObjectTags
Action: PutObjectTags
描述: 用于给某个存储空间下的对象(Object)添加或修改标签。
请求方法: PUT
注意事项:
使用PutObjectTags接口时,有如下注意事项:
- 只有ObjectT的拥有者才能为ObjectT设置标签,否则返回403 Forbudden错误,错误码为AccessDenied。
- 最多可设置10对ObjectT标签(Key-Value对),不可设置重复的标签
- PutObjectTTags是覆盖语义,即新添加的标签会完全覆盖已有的标签。
- 只有ObjectT的拥有者才能为ObjectT设置标签,否则返回403 Forbudden错误,错误码为AccessDenied。
参数:
- 请求元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Tagging | 容器 | 是 | 设置Bucket TagSet的容器。 子元素:TagSet 父元素:无 |
TagSet | 容器 | 是 | 包含一系列Bucket Tag的容器。 子元素:Tag 父元素:Tagging |
Tag | 容器 | 是 | 设置Bucket Tag的容器。 子元素:Key、Value 父元素:TagSet |
Key | 字符串 | 是 | 指定Bucket Tag的Key。 ·最大长度为128字节。 ·不能为空。 ·不包括特殊字符+‑=._:/。 子元素:无 父元素:Tag |
Value | 字符串 | 否 | 指定Bucket Tag的Value。 ·最大长度为256字节。 ·可以为空。 ·不包括特殊字符+‑=._:/。 子元素:无 父元素:Tag |
请求示例:
PUT /aa.xlsx?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
<?xml version="1.0" encoding="UTF-8"?>
<Tagging>
<TagSet>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key2</Key>
<Value>value2</Value>
</Tag>
</TagSet>
</Tagging>
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
DeleteObjectTags
Action:DeleteObjectTags
描述:用于删除某个存储空间下的指定对象(Object)下的全部标签。
请求方法:DEL
参数:
- 响应元素:无
请求示例:
DELETE /aa.xlsx?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
GetObjectTags
Action: GetObjectTags
描述: 用于获取某个存储空间下的对象(Object)的标签。
请求方法: GET
参数:
- 响应元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Tagging | 容器 | 是 | 设置Bucket TagSet的容器。 子元素:TagSet 父元素:无 |
TagSet | 容器 | 是 | 包含一系列Bucket Tag的容器。 子元素:Tag 父元素:Tagging |
Tag | 容器 | 是 | 设置Bucket Tag的容器。 子元素:Key、Value 父元素:TagSet |
Key | 字符串 | 是 | 某个Tag的Key。 父元素:Tag |
Value | 字符串 | 否 | 某个Tag的Value。 父元素:Tag |
请求示例:
GET /aa.xlsx?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
<?xml version="1.0" encoding="utf-8"?>
<Tagging>
<TagSet>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key2</Key>
<Value>value2</Value>
</Tag>
</TagSet>
</Tagging>
PutBucketTags
Action: PutBucketTags
描述: 用于给某个存储空间(Bucket)添加或修改标签。
请求方法: PUT
注意事项:
- 使用PutBucketTags接口时,有如下注意事项:
- 只有Bucket的拥有者才能为Bucket设置标签,否则返回403 Forbudden错误,错误码为AccessDenied。
- 最多可设置10对Bucket标签(Key-Value对),不可设置重复的标签
- PutBucketTags是覆盖语义,即新添加的标签会完全覆盖已有的标签。
参数:
- 请求元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Tagging | 容器 | 是 | 设置Bucket TagSet的容器。 子元素:TagSet 父元素:无 |
TagSet | 容器 | 是 | 包含一系列Bucket Tag的容器。 子元素:Tag 父元素:Tagging |
Tag | 容器 | 是 | 设置Bucket Tag的容器。 子元素:Key、Value 父元素:TagSet |
Key | 字符串 | 是 | 指定Bucket Tag的Key。 ·最大长度为128字节。 ·不能为空。 ·不包括特殊字符+‑=._:/。 子元素:无 父元素:Tag |
Value | 字符串 | 否 | 指定Bucket Tag的Value。 ·最大长度为256字节。 ·可以为空。 ·不包括特殊字符+‑=._:/。 子元素:无 父元素:Tag |
请求示例:
PUT /?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
<?xml version="1.0" encoding="UTF-8"?>
<Tagging>
<TagSet>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key2</Key>
<Value>value2</Value>
</Tag>
</TagSet>
</Tagging>
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
DeleteBucketTags
Action: DeleteBucketTags
描述: 用来删除某个存储空间(Bucket)的全部标签。
请求方法: DEL
参数:
- 响应元素:无
请求示例:
DELETE /?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
GetBucketTags
Action: GetBucketTags
描述: 用于获取某个存储空间(Bucket)的标签。
请求方法: GET
参数:
- 响应元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Tagging | 容器 | 是 | 设置Bucket TagSet的容器。 子元素:TagSet 父元素:无 |
TagSet | 容器 | 是 | 包含一系列Bucket Tag的容器。 子元素:Tag 父元素:Tagging |
Tag | 容器 | 是 | 设置Bucket Tag的容器。 子元素:Key、Value 父元素:TagSet |
Key | 字符串 | 是 | 某个Tag的Key。 父元素:Tag |
Value | 字符串 | 否 | 某个Tag的Value。 父元素:Tag |
请求示例:
GET /?tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
<?xml version="1.0" encoding="utf-8"?>
<Tagging>
<TagSet>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key2</Key>
<Value>value2</Value>
</Tag>
</TagSet>
</Tagging>
AddNotify
Action: AddNotify
描述: 用于添加事件通知规则。
请求方法: PUT
注意事项:
- 使用AddNotify接口时,有如下注意事项:
- 只有Bucket的拥有者才能为Object事件设置通知,否则返回403 Forbudden错误,错误码为AccessDenied。
- 最多可设置5个接收终端
参数:
- 请求元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
NotificationConfiguration | 是 | 设置事件根目录。子元素:RuleConfiguration父元素:无 | |
RuleConfiguration | 是 | 子元素:RuleName父元素:NotificationConfiguration | |
RuleName | 根元素 | 事件名称 | |
Event | 根元素 | 事件类型 | |
Filter | 根元素 | ||
S3Key | 根元素 | ||
FilterRule | 根元素 | ||
Name | 否 | 文件名前缀类型 | |
Value | 否 | 文件名 | |
Target | 根元素 | ||
Type | 是 | 终端接收类型:http、kafka | |
Url | 是 | http://开头的协议格式 | |
Topic | 否 | 主题名称 | |
Token | 否 | 信任秘钥Token | |
UserName | 否 | Type 为kafka时kafka的用户名 | |
Password | 否 | Type 为kafka时kafka的密码 | |
Version | 否 | Type 为kafka时的填写的版本 |
请求示例:
PUT /?notification&CustomerId=E88899&UserId=577273 HTTP/1.1 x-forwarded-host: testss.oss-test.cdsgss.com:6001
<?xml version="1.0" encoding="UTF-8" ?>
<NotificationConfiguration>
<RuleConfiguration>
<RuleName>testaaaa</RuleName>
<Event>ObjectCreated:Put</Event>
<Filter>
<S3Key>
<FilterRule>
<Name>prefix</Name>
<Value>aaaa</Value>
</FilterRule>
<FilterRule>
<Name>prefix</Name>
<Value>testaassss</Value>
</FilterRule>
</S3Key>
</Filter>
<Target>
<Type>http</Type>
<Url>http://114.112.81.188:7000/admin/demo/xml</Url>
<Topic></Topic>
<Token>ssss</Token>
<UserName></UserName>
<Password></Password>
<Version></Version>
</Target>
</RuleConfiguration>
</NotificationConfiguration>
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
GetNotify
Action: GetNotify
描述: 用于获取某个存储空间(Bucket)的标签。
请求方法: GET
参数:
- 响应元素:同新增请求元素
请求示例:
GET /?notification&tagging&CustomerId=E88899&UserId=577273 HTTP/1.1
x-forwarded-host: testss.oss-test.cdsgss.com:6001
返回示例:
Date: Tue, 09 Mar 2021 07:43:25 GMT
x-oss-request-id: 1615275804887
Content-Length: 80
Content-Type: application/xml; charset=utf-8
Server: Werkzeug/0.14.1 Python/2.7.12
<?xml version="1.0" encoding="utf-8"?>
<NotificationConfiguration>
<RuleConfiguration>
<Filter>
<S3key>
<FilterRule>
<Name>prefix</Name>
<Value>pka1,luas</Value>
</FilterRule>
</S3key>
</Filter>
<Target>
<UserName></UserName>
<Url>101.89.76.90:9092</Url>
<Topic>wangwei</Topic>
<Token></Token>
<Version></Version>
<Password>admin</Password>
<Type>kafka</Type>
</Target>
<Event>ObjectCreated:Put</Event>
<RuleName>cs</RuleName>
</RuleConfiguration>
....
</NotificationConfiguration>
DescribeSTS
Action: DescribeSTS
描述: 获取用户临时上传文件至对象存储签名。
请求方法: POST
注意事项:
- 该签名只适用于相同容器及其目录的签名,如容器目录发生变化则需要额外获取对应目录的签名
参数:
- 请求元素
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
dir_path | varchar(500) | 是 | 文件上传到容器的目录,根目录:””,其他目录以“/”结尾,示例:“test/a/” |
expires | int | 是 | 选填,签名有效期,默认300秒 |
max_file_count | int | 否 | 选填,单次请求最多允许上传的文件数量,默认50 |
请求示例:
URL:
GET http://cdsapi.capitalonline.net/oss/?Action=DescribeSTS&AccessKeyId=13c8318a18b811eb9e513e1666a08b08&SignatureMethod=HMAC-SHA1&SignatureNonce=552f0058-1465-11ec-8f08-646c80cc670e&SignatureVersion=1.0&Timestamp=2021-09-13T07%3A36%3A39Z&Version=2019-08-08&STSSignature=&Signature=26bOJJBCpQ8ZtvzonM61cAyRzOA%3D
请求headers:
{'Host': 'test-domain.oss-cnbj01.cdsgss.com'}
请求data:
<?xml version="1.0" encoding="utf-8"?>
<SignatureReq>
<dir_path>test/a/</dir_path>
<expires>300</expires>
<max_file_count>50</max_file_count>
</SignatureReq>
请求param:
param = {'STSSignature': ''} #必填,接口调用Query中参数
返回示例:
<?xml version="1.0" encoding="utf-8"?>
<request>
<max_file_size>524288000</max_file_size>
<redirect></redirect>
<max_file_count>50</max_file_count>
<expires>1631518899</expires>
<signature>722676d6ed1200bbad6f232dfb3e42952f592c56</signature>
<upload_url>https://oss-cnbj01.cdsgss.com/v1/AUTH_5e29863a6e8e41fca3e1dd4440273a72/test-domain/test/a/</upload_url>
</request>
使用临时签名上传文件至对象存储curl命令示例:
curl --location --request POST 'https://oss-cnbj01.cdsgss.com/v1/AUTH_5e29863a6e8e41fca3e1dd4440273a72/test-domain/test/a/' \
--form 'signature="722676d6ed1200bbad6f232dfb3e42952f592c56"' \
--form 'expires="1631518899"' \
--form 'max_file_count="50"' \
--form 'max_file_size="524288000"' \
--form 'file=@"/C:/Users/Administrator/AppData/Local/Postman/app-8.12.0/libEGL.dll"'
python调用示例:(需替换自己的ak,sk,bucket名称)
# coding: utf-8
import base64
import hmac
import time
import urllib.parse as parse
import uuid
import json
from hashlib import sha1
import requests
import xmltodict as xmlparse
# 签名地址
openapi_url = 'http://cdsapi.capitalonline.net/oss' # default
# 对象存储节点地址
endpoint = 'oss-cnbj01.cdsgss.com'
# 用户管理对应ak sk值,查询地址 https://account.capitalonline.net/users/securityKey
a_key = '13c8318a18b811eb9e513e1666a08xxx'
s_key = 'dfa80eac1a8c77f375630709fc7e5xxx'
# 容器名称
bucket = 'test-domain'
class PayloadType:
XML = 'xml'
JSON = 'json'
def encode_query_param(query_param):
_query_str = ''
if query_param:
_query_str = parse.urlencode(query_param)
return _query_str
def percent_encode(string):
"""将特殊转义字符替换"""
res = parse.quote(string, '')
res = res.replace('+', '%20')
res = res.replace('*', '%2A')
res = res.replace('%7E', '~')
return res
def signature(action, ak, access_key_secret, method, url, param={}):
"""
参数签名
@params: action: 接口动作
@params: ak: ak值
@params: access_key_secret: ak秘钥
@params: method: 接口调用方法(POST/GET)
@params: param: 接口调用Query中参数(非POST方法Body中参数)
@params: url: 接口调用路径
@return: 请求的url可直接调用
"""
timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
D = {
'Action': action,
'AccessKeyId': ak,
'SignatureMethod': 'HMAC-SHA1',
'SignatureNonce': str(uuid.uuid1()),
'SignatureVersion': "1.0",
"Timestamp": timestamp,
'Version': '2019-08-08',
}
if param:
D.update(param)
sortedD = sorted(D.items(), key=lambda x: x[0])
canstring = ''
for k, v in sortedD:
canstring += '&' + percent_encode(k) + '=' + percent_encode(v)
stringToSign = method + '&%2F&' + percent_encode(canstring[1:])
stringToSign = stringToSign.encode('utf-8')
access_key_secret = access_key_secret.encode('utf-8')
h = hmac.new(access_key_secret, stringToSign, sha1)
signature = base64.encodebytes(h.digest()).strip()
D['Signature'] = signature
url = url + '/?' + parse.urlencode(D)
return url
class OpenAPI(object):
def __init__(self, access_key, secret_key):
self.access_key = access_key
self.secret_key = secret_key
def get_sts_token(self, bucket=None):
'''
查询容器上传临时token
@param bucket: 容器名称
@return:
'''
method = 'POST'
url = openapi_url
headers = {
'Host': f'{bucket}.{endpoint}' #host必填
}
param = {'STSSignature': ''} #必填,接口调用Query中参数
body ={"SignatureReq":
{
'dir_path': "test/a/", #必填,文件上传的路径,根目录:"",其他目录以“/”结尾,示例:“test/a/”
'expires': 300, #选填,临时token有效期
'max_file_count':50 #选填,单次请求最多允许上传的文件数量
}
}
data = xmlparse.unparse(body, pretty=True)
url = signature("DescribeSTS", self.access_key, self.secret_key, method, url, param)
print("请求url:%s" % url)
'''
url 示例:
http://cdsapi.capitalonline.net/oss/?Action=DescribeSTS&AccessKeyId=13c8318a18b811eb9e513e1666a08b08&SignatureMethod=HMAC-SHA1&SignatureNonce=078c3310-1465-11ec-844f-646c80cc670e&SignatureVersion=1.0&Timestamp=2021-09-13T07%3A34%3A29Z&Version=2019-08-08&STSSignature=&Signature=T4xl7QvpmqlH3jlYxseuQPQNv%2FY%3D
'''
print("请求内容data:%s" % data)
'''
data 示例:
<?xml version="1.0" encoding="utf-8"?>
<SignatureReq>
<dir_path></dir_path>
<expires>300</expires>
<max_file_count>3</max_file_count>
</SignatureReq>
'''
print("请求headers:%s" %headers)
'''
headers 示例:
{'Host': 'ddw002.oss-test.cdsgss.com'}
'''
resp = requests.post(url, data=data, headers=headers)
status = resp.status_code
data = resp.text
print('返回结果:%s' %data)
return status, data
if __name__ == '__main__':
api = OpenAPI(a_key, s_key)
api.get_sts_token(bucket)