对象存储公开API目录

API概览

OSS产品提供以下相关API接口

API	描述
PutObjectTags	给某个存储空间下的对象（Object）添加或修改标签。
DeleteObjectTags	删除某个存储空间下的指定对象（Object）下的全部标签。
GetObjectTags	获取某个存储空间下的对象（Object）的标签。
PutBucketTags	给某个存储空间（Bucket）添加或修改标签。
DeleteBucketTags	删除某个存储空间（Bucket）的全部标签。
GetBucketTags	获取某个存储空间（Bucket）的标签。
AddNotify	添加事件通知规则。
GetNotify	获取某个存储空间（Bucket）的标签。
DescribeSTS	获取用户临时上传文件至对象存储签名。

• 认证方式
  • 1.公共请求参数
  • 2.签名机制
    • 步骤一：构造规范化请求字符串
    • 步骤二：构造签名字符串
  • 3.获取签名代码
• 访问地址

访问地址

地区	访问地址
中国大陆	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是覆盖语义，即新添加的标签会完全覆盖已有的标签。

参数：

• 请求元素

名称	类型	是否必需	描述
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)