全部产品
云市场
云游戏

AccessKey调接口接入

更新时间:2020-08-06 15:47:19

PDS 提供的 API,有两套鉴权体系。除了可以使用 AccessToken 访问之外,还可以使用阿里云 AccessKey 签名访问。

1. AK 调用方式举例

使用 AccessKey 签名的方式,可以调用以下 Endpoint 的所有接口, 请看API参考

Endpoint 描述
https://${domainID}.api.alicloudpds.com 资源 API
https://${domainID}.auth.alicloudpds.com 认证授权 API

举例:

  1. POST /v2/drive/list
  2. Host: ${domainID}.api.alicloudpds.com
  3. Authorization: acs ${ACCESS_KEY_ID}:${SIGNATURE}
  4. Content-Type: application/json; charset=UTF-8
  5. {
  6. "owner": "xxxx"
  7. }

2. AK 签名说明

用户可以在HTTP请求中增加 Authorization 的Header来包含签名(Signature)信息,表明这个消息已被授权。

2.1 计算方法

这里参考了 aliyun sdk 的 RoaRequest,确保 aliyun sdk可以调通

  1. Authorization = "acs " + AccessKeyId + ":" + Signature
  2. Signature = base64(hmac-sha1(AccessKeySecret,
  3. VERB + "\n"
  4. + Accept + "\n"
  5. + Content-MD5 + "\n"
  6. + Content-Type + "\n"
  7. + Date + "\n"
  8. + CanonicalizedHeaders
  9. + CanonicalizedResource))
  • AccessKeySecret 表示签名所需的密钥。
  • VERB 表示HTTP 请求的Method,当前只支持 POST 。
  • \n 表示换行符。
  • Apdset 可以不设置,如果设置,当前只支持:application/json
  • Content-MD5 如果body为空,可以不设置。否则必须设置,表示请求内容数据的MD5值,对消息内容(不包括头部)计算MD5值获得128比特位数字,对该数字进行base64编码而得到。该请求头可用于消息合法性的检查(消息内容是否与发送时一致),如 eB5eJF1ptWaXm4bijSPyxw==。详情请参见 RFC2616 Content-MD5
  • Content-Type 可以为空,表示请求内容的类型,如 application/octet-stream
  • Date 必须设置,表示此次操作的时间,且必须为GMT格式,如Sun, 22 Nov 2015 08:16:38 GMT
  • CanonicalizedHeaders 表示以 x-acs- 为前缀的 HTTP Header 的字典序排列。
  • CanonicalizedResource 表示用户想要访问的pds资源。其中,DateCanonicalizedResource不能为空;如果请求中的Date时间和PDS服务器的时间差15分钟以上,OSS服务器将拒绝该服务,并返回HTTP 403错误。

2.2 构建CanonicalizedHeaders的方法

所有以 x-acs- 为前缀的HTTP Header被称为CanonicalizedHeaders。它的构建方法如下:

  1. 将所有以 x-acs- 为前缀的HTTP请求头的名字转换成小写 。如X-ACS-Meta-Name: TaoBao转换成x-oss-meta-name: TaoBao
  2. 如果请求是以STS获得的AccessKeyIdAccessKeySecret发送时,还需要将获得的security-token值以 x-acs-security-token:security-token 的形式加入到签名字符串中。
  3. 将上一步得到的所有HTTP请求头按照名字的字典序进行升序排列。
  4. 删除请求头和内容之间分隔符两端出现的任何空格。如x-oss-meta-name: TaoBao转换成:x-oss-meta-name:TaoBao
  5. 将每一个头和内容用 \n 分隔符分隔拼成最后的CanonicalizedOSSHeaders

说明

  • CanonicalizedHeaders可以为空,无需添加最后的 \n
  • 如果只有一个,则如 x-acs-meta-a\n,注意最后的\n
  • 如果有多个,则如 x-acs-meta-a:a\nx-oss-meta-b:b\nx-oss-meta-c:c\n,注意最后的\n

2.3 构建CanonicalizedResource的方法

用户发送请求中想访问的OSS目标资源被称为CanonicalizedResource。它的构建方法如下:

  1. CanonicalizedResource置成空字符串 “”。
  2. 放入要访问的OSS资源 /BucketName/ObjectName(如果没有ObjectName则CanonicalizedResource/BucketName/,如果同时也没有BucketName则为/)。
  3. 如果请求的资源包括子资源(SubResource) ,那么将所有的子资源按照字典序,从小到大排列并以 & 为分隔符生成子资源字符串。在CanonicalizedResource字符串尾添加 ? 和子资源字符串。此时的CanonicalizedResource如:/BucketName/ObjectName?acl&uploadId=UploadId

2.4 计算签名头规则

  • 签名的字符串必须为 UTF-8 格式。含有中文字符的签名字符串必须先进行 UTF-8 编码,再与 AccessKeySecret 计算最终签名。
  • 签名的方法用RFC 2104中定义的HMAC-SHA1方法,其中Key为 AccessKeySecret
  • AcceptContent-TypeContent-MD5 在请求中不是必须的,但是如果请求需要签名验证,空值的话以换行符 \n 代替。
  • 在所有非HTTP标准定义的header中,只有以 x-acs- 开头的header,需要加入签名字符串;其他非HTTP标准header将被忽略(如下方签名示例中的x-acs-magic是需要加入签名字符串的)。
  • x-acs-开头的header在签名验证前需要符合以下规范:
  • header的名字需要变成小写。
  • header按字典序自小到大排序。
  • 分割header name和value的冒号前后不能有空格。
  • 每个Header之后都有一个换行符\n,如果没有Header,CanonicalizedOSSHeaders就设置为空。

2.5 细节分析

  • 如果设置了 Accept,则检查是否为 application/json,否则返回400 Bad Request。错误码:InvalidHeader
  • 检查Body Length是否超过 4M,如果超过,返回400 Bad Request。错误码为:InvaliField
  • 若用户请求头中Authorization值的格式不对,返回400 Bad Request。错误码:InvaliField
  • 如果ak为STS开头,则检查是否设置 x-acs-security-token,否则返回403 Forbidden。错误码为:InvalidHeader
  • 如果传入的AccessKeyId不存在或inactive,返回403 Forbidden。错误码:InvalidParameter
  • 如果AccessKeyId是active的,但pds判断用户的请求发生签名错误,则返回403 Forbidden。错误码:SignatureDoesNotMatch;并在返回给用户的response中告诉用户正确的用于验证加密的签名字符串。用户可以根据 PDS 的response来检查自己的签名字符串是否正确。

3. 权限控制

API 服务端通过阿里云RAM(访问控制服务)来校验权限。您可以在 RAM控制台 设置子账号的 AccessKey 的权限策略。

以下是 API 鉴权参考表:

API 鉴权 Action 鉴权 Resource
ListStores(/v2/domain/liststores) pds:ListStores acs:pds:$regionid:$accountid:domain/$domainid/store/*
ListStoreFiles(/v2/storefile/list) pds:ListStoreFiles acs:pds:$regionid:$accountid:domain/$domainid
CreateDrive(/v2/drive/create) pds:CreateDrive acs:pds:$regionid:$accountid:domain/$domainid/drive/*
ListDrives(/v2/drive/list) pds:ListDrives acs:pds:$regionid:$accountid:domain/$domainid/drive/*
GetDrive(/v2/drive/get) pds:GetDrive acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
UpdateDrive(/v2/drive/update) pds:UpdateDrive acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
DeleteDrive(/v2/drive/delete) pds:DeleteDrive acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
ListMyDrives(/v2/drive/list_my_drives) pds:ListMyDrives acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
ListMyShares(/v2/drive/list_my_shares) pds:ListMyShares acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
CreateUser(/v2/user/create) pds:CreateUser acs:pds:$regionid:$accountid:domain/$domainid/user/*
GetUser(/v2/user/get) pds:GetUser acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
ListUsers(/v2/user/list) pds:ListUser acs:pds:$regionid:$accountid:domain/$domainid/user/*
UpdateUser(/v2/user/update) pds:UpdateUser acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
DeleteUser(/v2/user/delete) pds:DeleteUser acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
SearchUser(/v2/user/search) pds:SearchUser acs:pds:$regionid:$accountid:domain/$domainid/user/*
GetUserAccessToken(/v2/user/get_access_token) pds:GetUserAccessToken acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
CreateShare(/v2/share/create) pds:CreateShare acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetShare(/v2/share/get) pds:GetShare acs:pds:$regionid:$accountid:domain/$domainid/share/$shareid
ListShares(/v2/share/list) pds:ListShares acs:pds:$regionid:$accountid:domain/$domainid/share/*
UpdateShare(/v2/share/update) pds:UpdateShare acs:pds:$regionid:$accountid:domain/$domainid/share/$shareid
CreateFile(/v2/file/create) pds:CreateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
CreateFileWithSignature(/v2/file/create_with_signature) pds:CreateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid or acs:pds:$regionid:$accountid:domain/$domainid/share/$shareid
ListFiles(/v2/file/list) pds:ListFiles acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
CompleteFile(/v2/file/complete) pds:CreateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
CompleteFileWithStoreInfo(/v2/file/complete_with_store_info) pds:CreateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetFileSignature(/v2/file/get_signature) pds:GetFileSignature acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetFileUploadUrl(/v2/file/get_upload_url) pds:CreateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetFileDownloadUrl(/v2/file/get_download_url) pds:GetFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
DeleteFile(/v2/file/delete) pds:DeleteFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
CopyFile(/v2/file/copy) pds:CopyFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
MoveFile(/v2/file/move) pds:MoveFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
UpdateFile(/v2/file/update) pds:UpdateFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetFile(/v2/file/get) pds:GetFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
DownloadFile(/v2/file/get) pds:GetFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
BatchDeleteFile(/v2/file/batch_delete) pds:DeleteFile acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
GetAsyncTask(/v2/async_task/get) pds:GetAsyncTask acs:pds:$regionid:$accountid:domain/$domainid/user/$userid
ListImageTags(/v2/image/list_tags) pds:ListImageTags acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
ListImageFaceGroups(/v2/image/list_facegroups) pds:ListImageFaceGroups acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
ListFaceGroupImages(/v2/image/list_facegroup_images) pds:ListFaceGroupImages acs:pds:$regionid:$accountid:domain/$domainid/drive/$driveid
Batch(/v2/batch) pds:Batch acs:pds:$regionid:$accountid:*