├── CHANGELOG.md ├── DOCS.md ├── IMPL.md ├── README.md ├── SDK-Docs.md ├── SDK-Tests.md ├── android └── README.md ├── c └── README.md ├── csharp └── README.md ├── golang └── README.md ├── ios └── README.md ├── java └── README.md ├── nodejs └── README.md ├── php └── README.md ├── python └── README.md └── ruby └── README.md /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## CHANGE LOG 2 | 3 | ### v6.0.4 4 | 5 | 2013-07-05 issue [#33](https://github.com/qiniu/sdkspec/pull/33) 6 | 7 | - 补充 ListPrefix 的标准用法 8 | - 增加 单元测试环境(test-env.sh) 规范 9 | - 增加 服务端上传（rsutil）模块规范 10 | 11 | 12 | ### v6.0.3 13 | 14 | 2013-07-02 issue [#32](https://github.com/qiniu/sdkspec/pull/32) 15 | 16 | - 引入 PutWithoutKey, PutFileWithoutKey 17 | 18 | 19 | ### v6.0.2 20 | 21 | 2013-06-27 issue [#31](https://github.com/qiniu/sdkspec/pull/31) 22 | 23 | - 对 `ListPrefix` 的规格说明进行规范 24 | - IMPL.doc 补充了“开发流程”的规范 25 | 26 | 27 | ### v6.0.1 28 | 29 | 2013-06-24 issue [#30](https://github.com/qiniu/sdkspec/pull/30) 30 | 31 | - Remove fop.Call 32 | 33 | 34 | ### v6.0.0 35 | 36 | 2013-06-21 issue [#27](https://github.com/qiniu/sdkspec/pull/27), [#28](https://github.com/qiniu/sdkspec/pull/28), [#29](https://github.com/qiniu/sdkspec/pull/29) 37 | 38 | - 增加 [SDK 实现规范](https://github.com/qiniu/sdkspec/blob/develop/IMPL.md) 39 | - 增加 [docs.qiniu.com 实现规范](https://github.com/qiniu/sdkspec/blob/develop/DOCS.md) 40 | - 增加 conf.USER_AGENT 变量 41 | 42 | 43 | ### v1.0.3 44 | 45 | 2013-06-20 issue [#25](https://github.com/qiniu/sdkspec/pull/25) 46 | 47 | - io.PutExtra 48 | - Crc32 uint32 49 | - CheckCrc uint32 50 | // CheckCrc == 0: 表示不进行 crc32 校验 51 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 52 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 53 | 54 | 55 | ### v1.0.2 56 | 57 | 2013-06-10 issue [#21](https://github.com/qiniu/sdkspec/pull/21), [#22](https://github.com/qiniu/sdkspec/pull/22) 58 | 59 | - rs.GetPolicy 删除 Scope，也就是不再支持批量下载的授权。 60 | - rs.New, PutPolicy.Token, GetPolicy.MakeRequest 增加 mac *digest.Mac 参数，并默认为 nil。 61 | 62 | 63 | ### v1.0.1 64 | 65 | 2013-05-28 66 | 67 | - io.GetUrl 改为 rs.MakeBaseUrl 和 rs.GetPolicy.MakeRequest 68 | - rs.PutPolicy 增加 ReturnUrl, ReturnBody, CallbackBody；将 Customer 改为 EndUser；删除 CallbackBodyType（只支持 form 格式） 69 | 70 | -------------------------------------------------------------------------------- /DOCS.md: -------------------------------------------------------------------------------- 1 | # docs.qiniu.com Specification 2 | 3 | ## 网站结构 4 | 5 | - guide: QuickStart向导文档 6 | - api: 协议文档 7 | - xxx-sdk: SDK帮助文档（包含Tech文档，未来可能包含Reference文档） 8 | - tools: 工具帮助文档（包含 qrsync, qrsctl，etc） 9 | 10 | 结构如下： 11 | 12 | ``` 13 | /guide 14 | /v1/xxx 15 | /v2/xxx 16 | /v3/xxx 17 | 18 | /api 19 | /v1/xxx 20 | /v2/xxx 21 | /v3/xxx 22 | 23 | /php-sdk 24 | /v1/xxx 25 | /v2/xxx 26 | /v3/xxx 27 | 28 | /python-sdk 29 | /v1/xxx 30 | /v2/xxx 31 | /v3/xxx 32 | 33 | /tools 34 | /v1/xxx 35 | /v2/xxx 36 | /v3/xxx 37 | ``` 38 | 39 | 40 | ## 网站维护 41 | 42 | - api 文档，在 https://github.com/qiniu/apidoc 中维护。 43 | - xxx-sdk 文档，在各个 SDK 本身的 repo 中维护，一般在 repo 下的 docs 目录。 44 | - 其他，在 https://github.com/qiniu/docs.qiniu.com 中维护。 45 | 46 | 47 | ## 版本管理 48 | 49 | - 根据 master 分支下的 CHANGELOG 确定当前版本。 50 | - 智能跳转到当前版本。比如访问 `/guide/`，会自动跳转到 `/guide/v/` 这个 url。 51 | -------------------------------------------------------------------------------- /IMPL.md: -------------------------------------------------------------------------------- 1 | # SDK Implementation Specification 2 | 3 | 4 | ## 目录结构 5 | 6 | 7 | ``` 8 | docs/ - 文档所在目录 9 | tests/ - 单元测试目录，有的语言习惯叫 test 目录。这个建议遵循社区惯例。 10 | README.md - 项目说明文档 11 | CHANGELOG.md - 更新日志 12 | test-env.sh - 测试环境脚本 13 | .travis.yml - Travis-CI 配置文件 14 | ``` 15 | 16 | ## 单元测试环境 17 | 18 | 要运行单元测试，需要先准备单元测试环境(test-env.sh)。此文件默认内容如下： 19 | 20 | ``` 21 | export QINIU_ACCESS_KEY="" 22 | export QINIU_SECRET_KEY="" 23 | export QINIU_TEST_BUCKET="" 24 | export QINIU_TEST_DOMAIN="" 25 | ``` 26 | 27 | SDK 的用户需要先修改此文件，配置上相关的信息，然后 source test-env.sh，就可以正确运行所有单元测试了。test-env.sh 的内容仅限于用户通过 SDK 无法完成的一些管理性操作，比如创建空间（bucket）、关联域名（domain）等等。 28 | 29 | 30 | ## Travis-CI 31 | 32 | 不同语言的 .travis.yml 文件略有不同，但是他们都需要有： 33 | 34 | ``` 35 | before_script: 36 | - export QINIU_ACCESS_KEY="xxxxx" 37 | - export QINIU_SECRET_KEY="xxxxx" 38 | ``` 39 | 40 | 然后在测试案例中通过 getenv("QINIU_ACCESS_KEY") 和 getenv("QINIU_SECRET_KEY") 获得 AccessKey/SecretKey。 41 | 42 | 43 | ## 开发流程 44 | 45 | 准备工作： 46 | 47 | 1. fork qiniu 中的某个 sdk（比如叫 foo-sdk） 48 | 2. git clone git@github.com:yourname/foo-sdk.git 49 | 3. git remote add qiniu git@github.com:qiniu/foo-sdk.git 50 | 4. git fetch qiniu 51 | 52 | 开发流程： 53 | 54 | 1. git checkout -b feature/yyyy qiniu/develop 55 | 2. 开发 (如果qiniu/develop分支别人有merge内容进来，可以随时执行 git pull 合并) 56 | 3. git commit -am "xxx" 57 | 4. git push origin feature/yyyy 58 | 5. 发起 pr 59 | 60 | 其他一些细节： 61 | 62 | 1. 如何同时开发多个feature。很简单：随时可以 git checkout feature/yyyy 到某个分支 63 | 64 | 65 | ## 更新日志 66 | 67 | - 版本 Tag 创建的日期 68 | - 引用 develop 到 master 的 pr 69 | - 引用遵循的 sdkspec 版本 70 | - 引用遵循的 apidoc 版本 71 | - 说明本次修改的主要内容 72 | 73 | 样例： 74 | 75 | ``` 76 | ## CHANGE LOG 77 | 78 | ### v5.0.0 79 | 80 | 2013-06-11 issue [#62](https://github.com/qiniu/api/pull/62) 81 | 82 | - 遵循 [sdkspec v1.0.2](https://github.com/qiniu/sdkspec/tree/v1.0.2) 83 | - rs.GetPolicy 删除 Scope，也就是不再支持批量下载的授权。 84 | - rs.New, PutPolicy.Token, GetPolicy.MakeRequest 增加 mac *digest.Mac 参数。 85 | - 遵循 [apidoc v3.0.0](https://github.com/qiniu/apidoc/tree/v3.0.0) 86 | - 初步整理了 sdk 使用文档。 87 | ``` 88 | 89 | 90 | ## 框架结构/名字空间 91 | 92 | - conf：配置文件相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_` 前缀做名字空间) 93 | - auth.digest: 数字签名相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_` 前缀做名字空间) 94 | - rpc|http: 网络请求相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_` 前缀做名字空间) 95 | - rs: 上传下载凭证、文件管理相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_RS_` 前缀做名字空间) 96 | - rsf: 文件列表相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_RS_` 前缀做名字空间) 97 | - io: 普通上传相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_RS_` 前缀做名字空间) 98 | - resumable.io: 断点续上传相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_RS_` 前缀做名字空间) 99 | - fop: 数据处理相关 (对于不支持名字空间的语言来说，建议用 `Qiniu_FOP_` 前缀做名字空间) 100 | 101 | 102 | ## User-Agent 配置 103 | 104 | - 建议 http 请求的 User-Agent 用 SDK名+版本。比如 "qiniu php-sdk v6.0.0" 105 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：不同语言可以有不同的命名风格。本规范主要按类 Golang 风格进行描述（但不完全是）。 8 | - 名字空间：有的语言没有 package（namespace），通常通过名字前缀来表达。 9 | - 构造函数：有的语言没有构造函数，通过 NewXXX 函数来表达。本规范因为按 Golang 风格，构造函数也是用 NewXXX 进行描述。 10 | - 函数重载：有的语言没有函数重载，通过 XXXYYY 形式命名，其中 XXX 是功能，YYY 是不同重载函数的区分段。支持函数重载的语言没有 YYY 段。 11 | - 函数多返回值：有的语言不支持返回多个返回值，也不支持返回元组（tuple）。 12 | 13 | 14 | ## 各个语言的 SDKSpec 15 | 16 | - [Objective-C (iOS)](https://github.com/qiniu/sdkspec/blob/develop/ios/README.md) 17 | - [Java (Android)](https://github.com/qiniu/sdkspec/blob/develop/android/README.md) 18 | - [Java](https://github.com/qiniu/sdkspec/blob/develop/java/README.md) 19 | - [PHP](https://github.com/qiniu/sdkspec/blob/develop/php/README.md) 20 | - [Python](https://github.com/qiniu/sdkspec/blob/develop/python/README.md) 21 | - [Ruby](https://github.com/qiniu/sdkspec/blob/develop/ruby/README.md) 22 | - [Node.js](https://github.com/qiniu/sdkspec/blob/develop/nodejs/README.md) 23 | - [C#](https://github.com/qiniu/sdkspec/blob/develop/csharp/README.md) 24 | - [C/C++](https://github.com/qiniu/sdkspec/blob/develop/c/README.md) 25 | - [Go](https://github.com/qiniu/sdkspec/blob/develop/golang/README.md) 26 | 27 | -------------------------------------------------------------------------------- /SDK-Docs.md: -------------------------------------------------------------------------------- 1 | # SDK 使用文档编写规范 2 | 3 | SDK 使用文档位于代码库的 `docs/README.md` ，文档需基于 [Markdown](http://markdown.tw/) 语法格式编写。 4 | 5 | 开发者可以基于 Github 提供的在线编辑器编写，也可以使用如下 Markdown 编辑器。 6 | 7 | ## Markdown Editor 8 | 9 | Mac 10 | 11 | * [Mou](http://mouapp.com/) 12 | 13 | Linux 14 | 15 | * [ReText](http://sourceforge.net/p/retext/home/ReText/) 16 | 17 | Windows 18 | 19 | * [MarkdownPad](http://markdownpad.com/) 20 | * [MarkPad](http://code52.org/DownmarkerWPF/) 21 | 22 | Online Tools 23 | 24 | * [Markable.in](http://markable.in/) 25 | * [Dillinger.io](http://dillinger.io/) 26 | 27 | Chrome 28 | 29 | * [MaDe](https://chrome.google.com/webstore/detail/oknndfeeopgpibecfjljjfanledpbkog) (Chrome) 30 | 31 | Others 32 | 33 | * [Sublime Text 2](http://www.sublimetext.com/2) + [MarkdownEditing](http://ttscoff.github.com/MarkdownEditing/) 34 | 35 | 36 | ## SDK 文档书写目录结构（范式） 37 | 38 | - SDK 简介说明 39 | 40 | - SDK 接入/安装/环境依赖说明 41 | 42 | - SDK 使用篇 43 | 44 | - 文件上传 45 | - 生成上传授权凭证（uploadToken） 46 | - 上传文件 47 | - 断点续上传（如果SDK支持） 48 | 49 | - 文件下载 50 | - 公有资源下载（[引导至API说明](http://docs.qiniutek.com/v3/api/io/#public-download)） 51 | - 私有资源下载 52 | - 生成下载授权凭证（downloadToken） 53 | - 高级特性 54 | - 断点续下载（[引导至API说明](http://docs.qiniutek.com/v3/api/io/#download-by-range-bytes)） 55 | - 自定义 404 NotFound（[引导至API说明](http://docs.qiniutek.com/v3/api/io/#download-if-notfound)） 56 | 57 | - 文件操作 58 | - 查看文件基本属性信息 59 | - 复制文件 60 | - 移动文件 61 | - 删除文件 62 | - 批量操作（查看、复制、移动、删除） 63 | 64 | - 云处理 65 | - 图像 66 | - 查看图片属性信息 67 | - 查看图片EXIF信息 68 | - 图像在线处理（缩略、裁剪、旋转、转化） 69 | - 图像在线处理（缩略、裁剪、旋转、转化）后并持久化存储 70 | - 音频 71 | - 视频 72 | 73 | ## 样例参考 74 | 75 | SDK 文档源文件参考： 76 | 77 | Markdown 源文件参考: -------------------------------------------------------------------------------- /SDK-Tests.md: -------------------------------------------------------------------------------- 1 | # SDK单元测试规范 2 | 3 | ## 单元测试写法 4 | 5 | 一般来讲，单元测试的代码量是业务逻辑的3倍，针对每一个业务逻辑要写3个测试： 6 | 7 | - YES 逻辑断言 8 | - FALSE 逻辑断言 9 | - 异常出错逻辑断言（ERROR） 10 | 11 | 单元测试需覆盖所有的业务逻辑。 12 | 13 | 单元测试代码范式如下： 14 | 15 | ```{ruby} 16 | 17 | # 初始化测试环境 18 | 19 | before :all do 20 | 21 | # 使用测试密钥（AccessKey/SecretKey）接入 22 | establish_connection 23 | 24 | # 创建测试Bucket 25 | mk_unique_test_bucket 26 | 27 | end 28 | 29 | 30 | # 测试指定功能点 31 | 32 | context :some_feature do 33 | 34 | # YES逻辑断言 35 | it "should be YES" do 36 | # do some thing 37 | end 38 | 39 | # FALSE逻辑断言 40 | it "should be FALSE" do 41 | # do some thing 42 | end 43 | 44 | # 异常出错逻辑断言 45 | it "should be raise ERROR" do 46 | # do some thing 47 | end 48 | end 49 | 50 | context :yet_another_feature do 51 | # ... 52 | end 53 | 54 | 55 | # 清场 56 | 57 | after :all do 58 | 59 | # 删除之前测试用所创建的临时 Bucket 60 | drop_unique_test_bucket 61 | 62 | # 删除测试过程中所创建的临时文件 63 | clean_tmpfile 64 | 65 | end 66 | ``` 67 | 68 | ## 自动化测试 69 | 70 | 使用 Travis-CI 作为 SDK 的自动化测试工具。 71 | 72 | 在 `.git` 代码库根目录下添加 `.travis.yml` 文件，接入参考： 73 | 74 | 缺省每个 `.git` 代码库会接入 Travis-CI, 开发人员可以根据实际需要更改 `.travis.yml` 文件里边的配置项。 75 | 76 | 自动化测试流程参考如下图示： 77 | 78 | ![自动化测试流程图](http://xudaoli.qiniudn.com/talks/teamwork-with-git-flow/assets/github-pull-request-with-travis-ci.png) 79 | 80 | 接入 Travis-CI 后，开发者向 `.git` 代码主库提交 Pull Request 时，会触发 Travis-CI 自动跑 SDK 单元测试并汇报测试结果。如下示例： 81 | 82 | ![自动化测试流程图1](http://xudaoli.qiniudn.com/talks/teamwork-with-git-flow/assets/github-pull-request-with-travis-ci-step-1.png) 83 | -------------------------------------------------------------------------------- /android/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：不同语言可以有不同的命名风格。本规范主要按类 Golang 风格进行描述（但不完全是）。 8 | - 名字空间：有的语言没有 package（namespace），通常通过名字前缀来表达。 9 | - 构造函数：有的语言没有构造函数，通过 NewXXX 函数来表达。本规范因为按 Golang 风格，构造函数也是用 NewXXX 进行描述。 10 | - 函数重载：有的语言没有函数重载，通过 XXXYYY 形式命名，其中 XXX 是功能，YYY 是不同重载函数的区分段。支持函数重载的语言没有 YYY 段。 11 | - 函数多返回值：有的语言不支持返回多个返回值，也不支持返回元组（tuple）。 12 | 13 | 14 | ## 服务端配置（conf） 15 | 16 | ```{go} 17 | package "qiniu/api/conf" 18 | 19 | var USER_AGENT string // 请求的 User-Agent 值，比如 "qiniu php-sdk v6.0.0" 20 | 21 | var UP_HOST string 22 | var RS_HOST string 23 | var RSF_HOST string 24 | 25 | var ACCESS_KEY string 26 | var SECRET_KEY string // 不要在客户端初始化该变量 27 | ``` 28 | 29 | 范围：服务端和客户端共用 30 | 31 | 32 | ## 签名认证（auth/digest） 33 | 34 | ```{go} 35 | package "qiniu/api/auth/digest" 36 | 37 | type Mac struct { 38 | AccessKey string 39 | SecretKey []byte 40 | } 41 | ``` 42 | 43 | 范围：仅在服务端使用 44 | 45 | 46 | ## 存储API（rs） 47 | 48 | ```{go} 49 | package "qiniu/api/rs" 50 | 51 | type Client struct { 52 | ... 53 | } 54 | 55 | func New(mac *digest.Mac = nil) Client 56 | 57 | func (this Client) Stat(bucket, key string) (entry Entry, err error) 58 | func (this Client) Delete(bucket, key string) (err error) 59 | func (this Client) Move(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 60 | func (this Client) Copy(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 61 | 62 | type Entry struct { 63 | Hash string 64 | Fsize int64 65 | PutTime int64 66 | MimeType string 67 | EndUser string 68 | } 69 | 70 | // batch 71 | 72 | type EntryPath struct { 73 | Bucket string 74 | Key string 75 | } 76 | 77 | type EntryPathPair struct { 78 | Src EntryPath 79 | Dest EntryPath 80 | } 81 | 82 | type BatchItemRet struct { 83 | Error string 84 | Code int 85 | } 86 | 87 | type BatchStatItemRet struct { 88 | Data Entry 89 | Error string 90 | Code int 91 | } 92 | 93 | func (this Client) BatchStat(entries []EntryPath) (rets []BatchStatItemRet, err error) 94 | func (this Client) BatchDelete(entries []EntryPath) (rets []BatchItemRet, err error) 95 | func (this Client) BatchMove(entries []EntryPathPair) (rets []BatchItemRet, err error) 96 | func (this Client) BatchCopy(entries []EntryPathPair) (rets []BatchItemRet, err error) 97 | ``` 98 | 99 | 范围：仅在服务端使用 100 | 101 | 102 | ## 上传/下载授权凭证（uptoken/dntoken） 103 | 104 | ```{go} 105 | package "qiniu/api/rs" 106 | 107 | type PutPolicy struct { 108 | Scope string // 必选。可以是 bucketName 或者 bucketName:key 109 | CallbackUrl string // 可选 110 | CallbackBody string // 可选 111 | ReturnUrl string // 可选 112 | ReturnBody string // 可选 113 | AsyncOps string // 可选 114 | EndUser string // 可选 115 | Expires uint32 // 可选。默认是 3600 秒 116 | } 117 | 118 | func (this *PutPolicy) Token(mac *digest.Mac = nil) (uptoken string) 119 | 120 | type GetPolicy struct { 121 | Expires uint32 // 可选。默认是 3600 秒 122 | } 123 | 124 | func (this GetPolicy) MakeRequest(baseUrl string, mac *digest.Mac = nil) (privateUrl string) 125 | 126 | func MakeBaseUrl(domain, key string) (baseUrl string) 127 | ``` 128 | 129 | 范围：仅在服务端使用 130 | 131 | 132 | ## 存储高级API（rsf） 133 | 134 | ```{go} 135 | package "qiniu/api/rsf" 136 | 137 | type Client struct { 138 | ... 139 | } 140 | 141 | func New(mac *digest.Mac = nil) Client 142 | 143 | func (this Client) ListPrefix( 144 | bucket, prefix, marker string, limit int) (entries []ListItem, markerOut string, err error) 145 | 146 | type ListItem struct { 147 | Key string 148 | Hash string 149 | Fsize int64 150 | PutTime int64 151 | MimeType string 152 | EndUser string 153 | } 154 | ``` 155 | 156 | 范围：仅在服务端使用 157 | 158 | 159 | ## 上传（io） 160 | 161 | ```{go} 162 | package "qiniu/api/io" 163 | 164 | // upload 165 | 166 | const UNDEFINED_KEY = "?" 167 | 168 | type PutExtra struct { 169 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 170 | MimeType string // 可选 171 | Crc32 uint32 172 | CheckCrc uint32 173 | // CheckCrc == 0: 表示不进行 crc32 校验 174 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 175 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 176 | } 177 | 178 | type PutRet struct { 179 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 180 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 181 | } 182 | 183 | func Put( 184 | ret interface{}, uptoken string, key string, body io.Reader, extra *PutExtra) (err error) 185 | 186 | func PutFile( 187 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 188 | ``` 189 | 190 | 范围：客户端和服务端 191 | 192 | 193 | ## 断点续上传（resumable io） 194 | 195 | ```{go} 196 | package "qiniu/api/resumable/io" 197 | 198 | // upload 199 | 200 | const UNDEFINED_KEY = "?" 201 | 202 | type BlkputRet struct { 203 | Ctx string `json:"ctx"` 204 | Checksum string `json:"checksum"` 205 | Crc32 uint32 `json:"crc32"` 206 | Offset uint32 `json:"offset"` 207 | } 208 | 209 | type PutExtra struct { 210 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 211 | MimeType string 212 | ChunkSize int // 可选。每次上传的Chunk大小 213 | TryTimes int // 可选。尝试次数 214 | Progresses []BlkputRet // 可选。上传进度 215 | Notify func(blkIdx int, blkSize int, ret *BlkputRet) // 进度提示。注意blk是并行传输的 216 | NotifyErr func(blkIdx int, blkSize int, err error) 217 | } 218 | 219 | type PutRet struct { 220 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 221 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 222 | } 223 | 224 | func Put( 225 | ret interface{}, uptoken string, 226 | key string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 227 | 228 | func PutFile( 229 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 230 | 231 | func BlockCount(fsize int64) int 232 | 233 | // global settings 234 | 235 | type Settings { 236 | TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4。 237 | Workers int // 并行的工作线程数目。 238 | ChunkSize int // 默认的Chunk大小，不设定则为256k 239 | TryTimes int // 默认的尝试次数，不设定则为3 240 | } 241 | 242 | func SetSettings(settings *Settings) 243 | ``` 244 | 245 | 范围：客户端和服务端 246 | 247 | 248 | ## 数据处理API（fop） 249 | 250 | ```{go} 251 | package "qiniu/api/fop" 252 | 253 | // imageView 254 | 255 | type ImageView struct { 256 | Mode int // 缩略模式 257 | Width int // Width = 0 表示不限定宽度 258 | Height int // Height = 0 表示不限定高度 259 | Quality int // 质量, 1-100 260 | Format string // 输出格式，如jpg, gif, png, tif等等 261 | } 262 | 263 | func (this *ImageView) MakeRequest(url string) (imageViewUrl string) 264 | 265 | // imageMogr 266 | 267 | type ImageMogrify struct { 268 | ... // 待标准化 269 | } 270 | 271 | func (this *ImageMogrify) MakeRequest(url string) (imageMogrUrl string) 272 | 273 | // imageInfo 274 | 275 | type ImageInfoRet struct { 276 | Width int 277 | Height int 278 | Format string 279 | ColorModel string 280 | } 281 | 282 | type ImageInfo struct {} 283 | 284 | func (this ImageInfo) MakeRequest(url string) (imageInfoUrl string) 285 | func (this ImageInfo) Call(url string) (ret ImageInfoRet, err error) 286 | 287 | // exif 288 | 289 | type ExifValType struct { 290 | Val string 291 | Type int 292 | } 293 | 294 | type ExifRet map[string] ExifValType 295 | type Exif struct {} 296 | 297 | func (this Exif) MakeRequest(url string) (imageExifUrl string) 298 | func (this Exif) Call(url string) (ret ExifRet, err error) 299 | ``` 300 | 301 | 范围：客户端和服务端 302 | 303 | -------------------------------------------------------------------------------- /c/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：变量命名用小驼峰法，如：`accessKey` 8 | - 名字空间：C中没有命名空间，用前缀区分，如：`Qiniu_` 9 | - 构造函数：通过 NewXXX 函数来表达。 10 | 11 | ## 服务端配置（conf） 12 | 13 | ```{c} 14 | #include "conf.h" 15 | 16 | const char* QINIU_ACCESS_KEY = ""; 17 | const char* QINIU_SECRET_KEY = ""; 18 | 19 | const char* QINIU_RS_HOST = "http://rs.qiniu.com"; 20 | const char* QINIU_UP_HOST = "http://up.qiniu.com"; 21 | const char* QINIU_RSF_HOST = "http://rsf.qiniu.com"; 22 | 23 | const char* QINIU_USER_AGENT = "" // 请求的 User-Agent 值，比如 "qiniu c-sdk v6.0.0" 24 | ``` 25 | 26 | 范围：服务端和客户端共用 27 | 28 | ## 签名认证（auth/digest） 29 | 30 | ```{c} 31 | typedef struct _Qiniu_Mac { 32 | const char* accessKey; 33 | const char* secretKey; 34 | } Qiniu_Mac; 35 | ``` 36 | 37 | 范围：仅在服务端使用 38 | 39 | ## 存储API（rs） 40 | 41 | ```{c} 42 | // "rs.h" 43 | 44 | typedef struct _Qiniu_RS_StatRet { 45 | const char* hash; 46 | const char* mimeType; 47 | const char* endUser; 48 | Qiniu_Int64 fsize; 49 | Qiniu_Int64 putTime; 50 | } Qiniu_RS_StatRet; 51 | 52 | // 获取文件信息 53 | Qiniu_Error Qiniu_RS_Stat( 54 | Qiniu_Client* self, Qiniu_RS_StatRet* ret, const char* bucket, const char* key); 55 | // 删除文件 56 | Qiniu_Error Qiniu_RS_Delete(Qiniu_Client* self, const char* bucket, const char* key); 57 | // 移动文件 58 | Qiniu_Error Qiniu_RS_Move(Qiniu_Client* self, 59 | const char* tableNameSrc, const char* keySrc, 60 | const char* tableNameDest, const char* keyDest); 61 | // 复制文件 62 | Qiniu_Error Qiniu_RS_Copy(Qiniu_Client* self, 63 | const char* tableNameSrc, const char* keySrc, 64 | const char* tableNameDest, const char* keyDest); 65 | 66 | // batch 67 | 68 | typedef struct _Qiniu_RS_EntryPath { 69 | const char* bucket; 70 | const char* key; 71 | } Qiniu_RS_EntryPath; 72 | 73 | typedef struct _Qiniu_RS_EntryPathPair { 74 | Qiniu_RS_EntryPath src; 75 | Qiniu_RS_EntryPath dest; 76 | } Qiniu_RS_EntryPathPair; 77 | 78 | typedef struct _Qiniu_RS_BatchItemRet { 79 | const char* error; 80 | int code; 81 | }Qiniu_RS_BatchItemRet; 82 | 83 | typedef struct _Qiniu_RS_BatchStatRet { 84 | Qiniu_RS_StatRet data; 85 | const char* error; 86 | int code; 87 | }Qiniu_RS_BatchStatRet; 88 | 89 | // 批量查看文件信息 90 | Qiniu_Error Qiniu_RS_BatchStat( 91 | Qiniu_Client* self, Qiniu_RS_BatchStatRet* rets, 92 | Qiniu_RS_EntryPath* entries, Qiniu_ItemCount entryCount); 93 | // 批量删除 94 | Qiniu_Error Qiniu_RS_BatchDelete( 95 | Qiniu_Client* self, Qiniu_RS_BatchItemRet* rets, 96 | Qiniu_RS_EntryPath* entries, Qiniu_ItemCount entryCount); 97 | // 批量移动 98 | Qiniu_Error Qiniu_RS_BatchMove( 99 | Qiniu_Client* self, Qiniu_RS_BatchItemRet* rets, 100 | Qiniu_RS_EntryPathPair* entryPairs, Qiniu_ItemCount entryCount); 101 | // 批量复制 102 | Qiniu_Error Qiniu_RS_BatchCopy( 103 | Qiniu_Client* self, Qiniu_RS_BatchItemRet* rets, 104 | Qiniu_RS_EntryPathPair* entryPairs, Qiniu_ItemCount entryCount); 105 | ``` 106 | 107 | 范围：仅在服务端使用 108 | 109 | ## 上传/下载授权凭证（uptoken/dntoken） 110 | 111 | ```{c} 112 | // "rs.h" 113 | typedef struct _Qiniu_RS_PutPolicy { 114 | const char* scope; // 必选。可以是 bucketName 或者 bucketName:key 115 | const char* callbackUrl; // 可选 116 | const char* callbackBody; // 可选 117 | const char* returnUrl; // 可选 118 | const char* returnBody; // 可选 119 | const char* endUser; // 可选 120 | const char* asyncOps; // 可选 121 | Qiniu_Uint32 expires; // 可选。默认 3600 秒 122 | } Qiniu_RS_PutPolicy; 123 | 124 | // 获取上传token 125 | char* Qiniu_RS_PutPolicy_Token(Qiniu_RS_PutPolicy* policy, Qiniu_Mac* mac); 126 | 127 | typedef struct _Qiniu_RS_GetPolicy { 128 | Qiniu_Uint32 expires; // 可选。默认 3600 秒 129 | } Qiniu_RS_GetPolicy; 130 | 131 | // 获取私有资源url 132 | char* Qiniu_RS_GetPolicy_MakeRequest(Qiniu_RS_GetPolicy* policy, const char* baseUrl, Qiniu_Mac* mac); 133 | // 获取escape转义的url 134 | char* Qiniu_RS_MakeBaseUrl(const char* domain, const char* key); 135 | ``` 136 | 137 | 范围：仅在服务端使用 138 | 139 | ## 存储高级API（rsf） 140 | 141 | ```{c} 142 | // "rsf.h" 143 | 144 | Qiniu_Error Qiniu_RSF_ListPrefix( 145 | Qiniu_Client* self, Qiniu_RSF_ListItem* ret, const char* bucket, const char* prefix, 146 | const char* marker, int limit); 147 | 148 | type struct _Qiniu_RSF_ListItem { 149 | const char* key; 150 | const char* hash; 151 | const char* mimeType; 152 | const char* endUser; 153 | Qiniu_Uint64 fsize; 154 | Qiniu_Uint64 putTime; 155 | } Qiniu_RSF_ListItem; 156 | ``` 157 | 158 | 范围：仅在服务端使用 159 | 160 | ## 上传（io） 161 | 162 | ```{c} 163 | // "io.h" 164 | 165 | // upload 166 | 167 | #ifndef QINIU_UNDEFINED_KEY 168 | #define QINIU_UNDEFINED_KEY NULL 169 | #endif 170 | 171 | typedef struct _Qiniu_Io_PutExtraParam { 172 | const char* key; 173 | const char* value; 174 | struct _Qiniu_Io_PutExtraParam* next; 175 | } Qiniu_Io_PutExtraParam; 176 | 177 | typedef struct _Qiniu_Io_PutExtra { 178 | Qiniu_Io_PutExtraParam* params; // 用户自定义参数，key必须以 "x:" 开头 179 | const char* mimeType; // 可选 180 | Qiniu_Uint32 crc32; 181 | Qiniu_Uint32 checkCrc32; 182 | // checkCrc32 == 0: 表示不进行 crc32 校验 183 | // checkCrc32 == 1: 对于 Put 等同于 checkCrc32 = 2；对于 PutFile 会自动计算 crc32 值 184 | // checkCrc32 == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 crc32 变量 185 | } Qiniu_Io_PutExtra; 186 | 187 | typedef struct _Qiniu_Io_PutRet { 188 | const char* hash; // hash 是对文件内容的hash值 189 | const char* key; // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key = hash 190 | } Qiniu_Io_PutRet; 191 | 192 | // 从内存中上传文件 193 | Qiniu_Error Qiniu_Io_PutBuffer( 194 | Qiniu_Client* self, Qiniu_Io_PutRet* ret, 195 | const char* uptoken, const char* key, const char* buf, size_t fsize, Qiniu_Io_PutExtra* extra); 196 | 197 | // 根据文件名上传文件 198 | Qiniu_Error Qiniu_Io_PutBuffer( 199 | Qiniu_Client* self, Qiniu_Io_PutRet* ret, 200 | const char* uptoken, const char* key, const char* buf, size_t fsize, Qiniu_Io_PutExtra* extra); 201 | ``` 202 | 203 | 范围：客户端和服务端 204 | 205 | ## 断点续上传（resumable io） 206 | 207 | ```{c} 208 | // “resumeable_io.h” 209 | 210 | // upload 211 | 212 | #ifndef QINIU_UNDEFINED_KEY 213 | #define QINIU_UNDEFINED_KEY NULL 214 | #endif 215 | 216 | typedef struct _Qiniu_Rio_BlkputRet { 217 | const char* ctx; 218 | const char* checksum; 219 | Qiniu_Uint32 crc32; 220 | Qiniu_Uint32 offset; 221 | const char* host; 222 | } Qiniu_Rio_BlkputRet; 223 | 224 | typedef struct _Qiniu_Rio_PutExtra { 225 | const char* callbackParams; 226 | const char* bucket; 227 | const char* customMeta; 228 | const char* mimeType; 229 | int chunkSize; // 可选。每次上传的Chunk大小 230 | int tryTimes; // 可选。上传进度 231 | void* notifyRecvr; 232 | Qiniu_Rio_FnNotify notify; // 进度提示。注意blk是并行传输的 233 | Qiniu_Rio_FnNotifyErr notifyErr; 234 | Qiniu_Rio_BlkputRet* progresses; // 可选。上传进度 235 | size_t blockCnt; 236 | Qiniu_Rio_ThreadModel threadModel; 237 | } Qiniu_Rio_PutExtra; 238 | 239 | typedef Qiniu_Io_PutRet Qiniu_Rio_PutRet; 240 | 241 | Qiniu_Error Qiniu_Rio_Put( 242 | Qiniu_Client* self, Qiniu_Rio_PutRet* ret, 243 | const char* uptoken, const char* key, Qiniu_ReaderAt f, Qiniu_Int64 fsize, Qiniu_Rio_PutExtra* extra); 244 | 245 | Qiniu_Error Qiniu_Rio_PutFile( 246 | Qiniu_Client* self, Qiniu_Rio_PutRet* ret, 247 | const char* uptoken, const char* key, const char* localFile, Qiniu_Rio_PutExtra* extra); 248 | 249 | int Qiniu_Rio_BlockCount(Qiniu_Int64 fsize); 250 | 251 | // global settings 252 | 253 | typedef struct _Qiniu_Rio_Settings { 254 | int taskQsize; // 可选。任务队列大小。为 0 表示取 Workers * 4。 255 | int workers; // 并行的工作线程数目。 256 | int chunkSize; // 默认的Chunk大小，不设定则为256k 257 | int tryTimes; // 默认的尝试次数，不设定则为3 258 | Qiniu_Rio_ThreadModel threadModel; 259 | } Qiniu_Rio_Settings; 260 | 261 | void Qiniu_Rio_SetSettings(Qiniu_Rio_Settings* v); 262 | ``` 263 | 264 | 范围：客户端和服务端 265 | 266 | ## 数据处理API（fop） 267 | 268 | ```{c} 269 | // "fop.h" 270 | 271 | // imageView 272 | typedef struct _Qiniu_Fop_ImageView { 273 | int mode; 274 | int width; 275 | int height; 276 | int quality; 277 | const char* format; 278 | } Qiniu_Fop_ImageView; 279 | 280 | const char* Qiniu_Fop_ImageView_MakeRequest(Qiniu_Fop_ImageView* imageView, const char* url); 281 | 282 | // imageInfo 283 | typedef struct _Qiniu_Fop_ImageInfoRet { 284 | int width; 285 | int height; 286 | const char* format; 287 | const char* colorModel; 288 | } Qiniu_Fop_ImageInfoRet; 289 | 290 | Qiniu_Fop_ImageInfoRet* Qiniu_Fop_ImageInfo_Call(const char* url); 291 | 292 | ``` 293 | 294 | 范围：客户端和服务端 295 | -------------------------------------------------------------------------------- /csharp/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage C# SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 服务端配置（conf） 6 | 7 | 服务端app.config 文件配置节点 8 | ``` xml 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | ``` 20 | 21 | ``` c# 22 | namespace Qiniu.Conf 23 | { 24 | public class Config 25 | { 26 | public static string USER_AGENT = "qiniu csharp-sdk v6.0.0"; 27 | #region 帐户信息 28 | /// 29 | /// 七牛提供的公钥，用于识别用户 30 | /// 31 | public static string ACCESS_KEY = ""; 32 | /// 33 | /// 七牛提供的秘钥，不要在客户端初始化该变量 34 | /// 35 | public static string SECRET_KEY = ""; 36 | #endregion 37 | #region 七牛服务器地址 38 | /// 39 | /// 七牛资源管理服务器地址 40 | /// 41 | public static string RS_HOST; 42 | /// 43 | /// 七牛资源上传服务器地址. 44 | /// 45 | public static string UP_HOST; 46 | /// 47 | /// 七牛资源列表服务器地址. 48 | /// 49 | public static string RSF_HOST; 50 | #endregion 51 | /// 52 | /// 七牛SDK对所有的字节编码采用utf-8形式 . 53 | /// 54 | public static Encoding Encoding = Encoding.UTF8; 55 | 56 | /// 57 | /// 初始化七牛帐户、请求地址等信息，不应在客户端调用。 58 | /// 59 | public static void Init (); 60 | } 61 | } 62 | ``` 63 | 64 | 范围：服务端和客户端共用 65 | 66 | 67 | ## 签名认证（auth/digest） 68 | 69 | ``` c# 70 | namespace Qiniu.Auth.digest 71 | { 72 | /// 73 | /// 七牛消息认证(Message Authentication) 74 | /// 75 | public class Mac 76 | { 77 | /// 78 | /// Gets or sets the access key. 79 | /// 80 | public string AccessKey {get; set; } 81 | 82 | /// 83 | /// Gets the secret key. 84 | /// 85 | public byte[] SecretKey {get; } 86 | 87 | public Mac ();//直接从Config中读取帐户信息 88 | public Mac (string access, byte[] secretKey); 89 | public string Sign (byte[] b); 90 | public string SignWithData (byte[] data); 91 | } 92 | } 93 | ``` 94 | 95 | 范围：仅在服务端使用 96 | 97 | 98 | ## 存储API（rs） 99 | 100 | ``` c# 101 | namespace Qiniu.RS 102 | { 103 | public class Entry 104 | { 105 | /// 106 | /// 文件的Hash值 107 | /// 108 | public string Hash { get; private set; } 109 | 110 | /// 111 | /// 文件的大小(单位: 字节) 112 | /// 113 | public long Fsize { get; private set; } 114 | 115 | /// 116 | /// 文件上传到七牛云的时间(Unix时间戳) 117 | /// 118 | public long PutTime { get; private set; } 119 | 120 | /// 121 | /// 文件的媒体类型，比如"image/gif" 122 | /// 123 | public string MimeType { get; private set; } 124 | 125 | /// 126 | /// Gets the customer. 127 | /// 128 | public string Customer { get; private set; } 129 | } 130 | 131 | /// 132 | /// 资源路径 bucket+ ":"+ key 133 | /// 134 | public class EntryPath 135 | { 136 | /// 137 | /// 七牛云存储空间名 138 | /// 139 | public string Bucket {get;} 140 | 141 | /// 142 | /// 文件key 143 | /// 144 | public string Key {get;} 145 | 146 | public EntryPath (string bucket, string key); 147 | } 148 | /// 149 | /// 二元操作路径 150 | /// 151 | public class EntryPathPair 152 | { 153 | public EntryPath Src{ get; set; }; 154 | public EntryPath Dest{ get; set; }; 155 | 156 | /// 157 | /// 二元操作路径构造函数 158 | /// 159 | public EntryPathPair (EntryPath src, EntryPath Dest); 160 | } 161 | 162 | /// 163 | /// 批操作返回结果 164 | /// 165 | public class BatchRetItem 166 | { 167 | public int code; 168 | public BatchRetData data; 169 | } 170 | 171 | /// 172 | /// 批操作返回结果 173 | /// 174 | public class BatchRetData 175 | { 176 | /// 177 | /// 文件大小. 178 | /// 179 | public Int64 FSize {get; set;} 180 | 181 | /// 182 | /// 修改时间. 183 | /// 184 | public Int64 PutTime {get; set;} 185 | 186 | /// 187 | /// 文件名. 188 | /// 189 | public string Key {get; set;} 190 | 191 | /// 192 | /// Gets a value indicating whether this instance hash. 193 | /// 194 | public string Hash {get; set ;} 195 | 196 | /// 197 | /// Gets the MIME. 198 | /// 199 | public string Mime {get; set;} 200 | 201 | /// 202 | /// Gets the EndUser 203 | /// 204 | public string EndUser {get; set;} 205 | 206 | /// 207 | /// Error 208 | /// 209 | public string Error {get; set; } 210 | } 211 | 212 | /// 213 | /// 资源存储客户端，提供对文件的查看（stat），移动(move)，复制（copy）,删除（delete）操作 214 | /// 以及与这些操作对应的批量操作 215 | /// 216 | public class RSClient 217 | { 218 | private static string[] OPS = new string[] { "stat", "move", "copy", "delet" }; 219 | 220 | public RSClient (Mac mac=null); 221 | 222 | #region 单文件操作 223 | /// 224 | /// 查看文件 225 | /// 226 | public Entry Stat (EntryPath scope); 227 | 228 | /// 229 | /// 删除文件 230 | /// 231 | public CallRet Delete (EntryPath scope); 232 | 233 | /// 234 | /// 移动文件 235 | /// 236 | public CallRet Move (EntryPathPair pathPair); 237 | 238 | /// 239 | /// 复制 240 | /// 241 | public CallRet Copy (EntryPathPair pathPair); 242 | #endregion 243 | 244 | 245 | #region 批文件操作 246 | /// 247 | /// 批操作：文件查看 248 | /// 249 | public List BatchStat (EntryPath[] keys); 250 | 251 | /// 252 | /// 批操作：文件移动 253 | /// 254 | public CallRet BatchMove (EntryPathPair[] entryPathPairs); 255 | 256 | /// 257 | /// 批操作：文件复制 258 | /// 259 | public CallRet BatchCopy (EntryPathPair[] entryPathPari); 260 | 261 | /// 262 | /// 批操作：删除 263 | /// 264 | public CallRet BatchDelete (EntryPath[] keys); 265 | #endregion 266 | } 267 | } 268 | ``` 269 | 270 | 范围：仅在服务端使用 271 | 272 | 273 | ## 上传/下载授权凭证（uptoken/dntoken） 274 | 275 | ``` c# 276 | namespace Qiniu.RS 277 | { 278 | /// 279 | /// 上传凭证 280 | /// 281 | public class PutPolicy 282 | { 283 | /// 284 | /// 一般指文件要上传到的目标存储空间（Bucket）。若为”Bucket”，表示限定只能传到该Bucket（仅限于新增文件）；若为”Bucket:Key”，表示限定特定的文件，可修改该文件。 285 | /// 286 | public string Scope {get; set; } 287 | 288 | /// 289 | /// 文件上传成功后，Qiniu-Cloud-Server 向 App-Server 发送POST请求的URL，必须是公网上可以正常进行POST请求并能响应 HTTP Status 200 OK 的有效 URL 290 | /// 291 | public string CallBackUrl {get; set; } 292 | 293 | /// 294 | /// 文件上传成功后，Qiniu-Cloud-Server 向 App-Server 发送POST请求的数据。支持 魔法变量 和 自定义变量，不可与 returnBody 同时使用。 295 | /// 296 | public string CallBackBody {get; set; } 297 | 298 | /// 299 | /// 设置用于浏览器端文件上传成功后，浏览器执行301跳转的URL，一般为 HTML Form 上传时使用。文件上传成功后会跳转到 returnUrl?query_string, query_string 会包含 returnBody 内容。returnUrl 不可与 callbackUrl 同时使用 300 | /// 301 | public string ReturnUrl {get; set; } 302 | 303 | /// 304 | /// 文件上传成功后，自定义从 Qiniu-Cloud-Server 最终返回給终端 App-Client 的数据。支持 魔法变量，不可与 callbackBody 同时使用。 305 | /// 306 | public string ReturnBody {get; set; } 307 | 308 | /// 309 | /// 指定文件（图片/音频/视频）上传成功后异步地执行指定的预转操作。每个预转指令是一个API规格字符串，多个预转指令可以使用分号“;”隔开 310 | /// 311 | public string AsyncOps {get; set; } 312 | 313 | /// 314 | /// 给上传的文件添加唯一属主标识，特殊场景下非常有用，比如根据终端用户标识给图片或视频打水印 315 | /// 316 | public string EndUser {get; set; } 317 | 318 | /// 319 | /// 定义 uploadToken 的失效时间，Unix时间戳，精确到秒，缺省为 3600 秒 320 | /// 321 | [JsonProperty("deadline")] 322 | public string Expires {get; set; } 323 | 324 | /// 325 | /// 构造函数 326 | /// 327 | public PutPolicy (string scope, UInt32 expires=3600); 328 | 329 | /// 330 | /// 生成上传Token 331 | /// 332 | public string Token (Mac mac=null); 333 | } 334 | 335 | /// 336 | /// 下载凭证 337 | /// 338 | public class GetPolicy 339 | { 340 | /// 341 | /// 对请求进行签名 342 | /// 343 | public static string MakeRequest (string baseUrl, UInt32 expires = 3600, Mac mac = null); 344 | 345 | /// 346 | /// 构造请求URL 347 | /// 348 | public static string MakeBaseUrl (string domain, string key); 349 | } 350 | } 351 | ``` 352 | 353 | 范围：仅在服务端使用 354 | 355 | 356 | ## 存储高级API（rsf） 357 | 358 | ``` c# 359 | namespace Qiniu.RSF 360 | { 361 | /// 362 | /// RS Fetch 363 | /// 364 | public class RSFClient : QiniuAuthClient 365 | { 366 | //单次fetch获取结果数目最大限制 367 | private const int MAX_LIMIT = 1000; 368 | //失败重试次数 369 | private const int RETRY_TIME = 3; 370 | 371 | /// 372 | /// bucket name 373 | /// 374 | public string BucketName { get; private set; } 375 | 376 | /// 377 | /// Fetch返回结果条目数量限制 378 | /// 379 | public int Limit {get ; set ; } 380 | 381 | /// 382 | /// 文件前缀 383 | /// 384 | public string Prefix {get ; set ; } 385 | 386 | /// 387 | /// Fetch 定位符. 388 | /// 389 | public string Marker {get ; set ; } 390 | 391 | /// 392 | /// RS Fetch Client 393 | /// 394 | public RSFClient (string bucketName); 395 | 396 | /// 397 | /// 获取资源列表 398 | /// 399 | public DumpRet ListPrefix (string bucketName, string prefix="", string markerIn="", int limit = MAX_LIMIT); 400 | } 401 | } 402 | ``` 403 | 404 | 范围：仅在服务端使用 405 | 406 | 407 | ## 上传（io） 408 | 409 | ``` c# 410 | namespace Qiniu.IO 411 | { 412 | 413 | /// 414 | /// CRC检查类型 415 | /// 416 | public enum CheckCrcType 417 | { 418 | /// 419 | /// default 420 | /// 421 | DEFAULT_CHECK = -1, 422 | /// 423 | /// 表示不进行 crc32 校验 424 | /// 425 | NO_CHECK = 0, 426 | /// 427 | ///对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 428 | /// 429 | CHECK_AUTO = 1, 430 | /// 431 | /// 表示进行 crc32 校验，且 crc32 值就是PutExtra:Crc32 432 | /// 433 | CHECK = 2 434 | } 435 | 436 | public class PutExtra 437 | { 438 | /// 439 | /// 用户自定义参数，key必须以 "x:" 开头 440 | /// 441 | public Dictionary Params{ get; set; } 442 | 443 | /// 444 | /// 文件的媒体类型 445 | /// 446 | public string MimeType { get; set; } 447 | 448 | /// 449 | /// crc32值 450 | /// 451 | public Int32 Crc32 { get; set; } 452 | public CheckCrcType CheckCrc { get; set; } 453 | public string Scope { get; set; } 454 | 455 | public PutExtra (); 456 | public PutExtra (string bucket, string mimeType); 457 | } 458 | 459 | public class PutRet 460 | { 461 | /// 462 | /// 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 463 | /// 464 | public string Hash { get; private set; } 465 | 466 | /// 467 | /// 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 468 | /// 469 | public string key { get; private set; } 470 | } 471 | /// 472 | /// 上传客户端 473 | /// 474 | public class IOClient 475 | { 476 | private const string UNDEFINED_KEY = "?" 477 | /// 478 | /// 无论成功或失败，上传结束时触发的事件 479 | /// 480 | public event EventHandler PutFinished; 481 | 482 | /// 483 | /// 上传文件 484 | /// 485 | public PutRet PutFile(string upToken, string key, string localFile, PutExtra extra); 486 | 487 | /// 488 | /// Puts the file without key. 489 | /// 490 | public PutRet PutFileWithoutKey(string upToken,string localFile,PutExtra extra); 491 | 492 | /// 493 | /// 上传流 494 | /// 495 | public PutRet Put(string upToken, string key, System.IO.Stream putStream, PutExtra extra); 496 | } 497 | } 498 | ``` 499 | 500 | 范围：客户端和服务端 501 | 502 | 503 | ## 断点续上传（resumable io） 504 | 505 | ``` c# 506 | namespace Qiniu.IO.Resumable 507 | { 508 | /// 509 | /// Block上传成功事件参数 510 | /// 511 | public class PutNotifyEvent:EventArgs 512 | { 513 | public int BlkIdx {get;} 514 | 515 | public int BlkSize {get;} 516 | 517 | public BlkputRet Ret {get;} 518 | 519 | public PutNotifyEvent (int blkIdx, int blkSize, BlkputRet ret); 520 | } 521 | 522 | /// 523 | /// 上传错误事件参数 524 | /// 525 | public class PutNotifyErrorEvent:EventArgs 526 | { 527 | public int BlkIdx {get;} 528 | 529 | public int BlkSize {get;} 530 | 531 | public string Error {get;} 532 | 533 | public PutNotifyErrorEvent (int blkIdx, int blkSize, string error); 534 | } 535 | 536 | /// 537 | /// 断点续上传参数 538 | /// 539 | public class ResumablePutExtra 540 | { 541 | public string CallbackParams; 542 | public string Bucket; 543 | public string CustomMeta; 544 | public string MimeType; 545 | public int chunkSize; 546 | public int tryTimes; 547 | public BlkputRet[] Progresses; 548 | public event EventHandler Notify; 549 | public event EventHandler NotifyErr; 550 | } 551 | 552 | /// 553 | /// 块上传结果 554 | /// 555 | public class BlkputRet 556 | { 557 | public string ctx; 558 | public string checkSum; 559 | public UInt32 crc32; 560 | public UInt32 offset; 561 | } 562 | 563 | /// 564 | /// 异步并行断点上传类 565 | /// 566 | public class ResumablePut 567 | { 568 | private const string UNDEFINED_KEY = "?" 569 | /// 570 | /// 上传完成事件 571 | /// 572 | public event EventHandler PutFinished; 573 | 574 | /// 575 | /// 进度提示事件 576 | /// 577 | public event Action Progress; 578 | 579 | /// 580 | /// 上传设置 581 | /// 582 | public Settings PutSetting {get; set;} 583 | 584 | /// 585 | /// PutExtra 586 | /// 587 | public ResumablePutExtra Extra {get; set;} 588 | 589 | /// 590 | /// 构造函数 591 | /// 592 | public ResumablePut (Settings putSetting, ResumablePutExtra extra); 593 | 594 | /// 595 | /// 上传文件 596 | /// 597 | public void PutFile (string upToken, string localFile, string key); 598 | } 599 | } 600 | ``` 601 | 602 | 范围：客户端和服务端 603 | 604 | 605 | ## 数据处理API（fop） 606 | 607 | ``` c# 608 | namespace Qiniu.FileOP{ 609 | public class ImageView 610 | { 611 | /// 612 | /// 缩略模式 613 | /// 614 | public int Mode { get; set; } 615 | 616 | /// 617 | /// Width = 0 表示不限定宽度 618 | /// 619 | public int Width { get; set; } 620 | 621 | /// 622 | /// Height = 0 表示不限定高度 623 | /// 624 | public int Height { get; set; } 625 | 626 | /// 627 | ///质量, 1-100 628 | /// 629 | public int Quality { get; set; } 630 | 631 | /// 632 | /// 输出格式，如jpg, gif, png, tif等等 633 | /// 634 | public string Format { get; set; } 635 | 636 | /// 637 | /// Makes the request. 638 | /// 639 | public string MakeRequest (string url); 640 | } 641 | 642 | /// 643 | ///高级图像处理接口（第二版）（缩略、裁剪、旋转、转化） 644 | /// 645 | public class ImageMogrify 646 | { 647 | public bool AutoOrient { get; set; } 648 | 649 | public string Thumbnail { get; set; } 650 | 651 | public string Gravity { get; set; } 652 | 653 | public string Crop { get; set; } 654 | 655 | public int Quality { get; set; } 656 | 657 | public int Rotate { get; set; } 658 | 659 | public string Format { get; set; } 660 | 661 | public string MakeRequest (string url); 662 | } 663 | 664 | 665 | /// 666 | /// 获取图片基本信息，图片基本信息包括图片格式,图片大小，色彩模式 667 | /// 668 | public class ImageInfoRet 669 | { 670 | /// 671 | /// "png", "jpeg", "gif", "bmp", etc. 672 | /// 673 | public int Width { get; private set; } 674 | 675 | /// 676 | /// 图片高度 677 | /// 678 | public int Height { get; private set; } 679 | 680 | /// 681 | /// 图片宽度 682 | /// 683 | public string Format { get; private set; } 684 | 685 | /// 686 | /// "palette16", "ycbcr", etc. 687 | /// 688 | public string ColorModel { get; private set; } 689 | } 690 | 691 | public static class ImageInfo 692 | { 693 | public static string MakeRequest (string url); 694 | 695 | public static ImageInfoRet Call (string url); 696 | } 697 | 698 | public class ExifValType 699 | { 700 | public string val { get; set; } 701 | public int type { get; set; } 702 | } 703 | public class ExifRet : CallRet 704 | { 705 | public ExifValType this [string key] {get;} 706 | } 707 | } 708 | ``` 709 | 710 | 范围：客户端和服务端 711 | 712 | -------------------------------------------------------------------------------- /golang/README.md: -------------------------------------------------------------------------------- 1 | # Golang SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 服务端配置（conf） 6 | 7 | ```{go} 8 | package "qiniu/api/conf" 9 | 10 | var USER_AGENT string // 请求的 User-Agent 值，比如 "qiniu php-sdk v6.0.0" 11 | 12 | var UP_HOST string 13 | var RS_HOST string 14 | var RSF_HOST string 15 | 16 | var ACCESS_KEY string 17 | var SECRET_KEY string // 不要在客户端初始化该变量 18 | ``` 19 | 20 | 范围：服务端和客户端共用 21 | 22 | 23 | ## 签名认证（auth/digest） 24 | 25 | ```{go} 26 | package "qiniu/api/auth/digest" 27 | 28 | type Mac struct { 29 | AccessKey string 30 | SecretKey []byte 31 | } 32 | ``` 33 | 34 | 范围：仅在服务端使用 35 | 36 | 37 | ## 存储API（rs） 38 | 39 | ```{go} 40 | package "qiniu/api/rs" 41 | 42 | type Client struct { 43 | ... 44 | } 45 | 46 | func New(mac *digest.Mac = nil) Client 47 | 48 | func (this Client) Stat(bucket, key string) (entry Entry, err error) 49 | func (this Client) Delete(bucket, key string) (err error) 50 | func (this Client) Move(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 51 | func (this Client) Copy(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 52 | 53 | type Entry struct { 54 | Hash string 55 | Fsize int64 56 | PutTime int64 57 | MimeType string 58 | EndUser string 59 | } 60 | 61 | // batch 62 | 63 | type EntryPath struct { 64 | Bucket string 65 | Key string 66 | } 67 | 68 | type EntryPathPair struct { 69 | Src EntryPath 70 | Dest EntryPath 71 | } 72 | 73 | type BatchItemRet struct { 74 | Error string 75 | Code int 76 | } 77 | 78 | type BatchStatItemRet struct { 79 | Data Entry 80 | Error string 81 | Code int 82 | } 83 | 84 | func (this Client) BatchStat(entries []EntryPath) (rets []BatchStatItemRet, err error) 85 | func (this Client) BatchDelete(entries []EntryPath) (rets []BatchItemRet, err error) 86 | func (this Client) BatchMove(entries []EntryPathPair) (rets []BatchItemRet, err error) 87 | func (this Client) BatchCopy(entries []EntryPathPair) (rets []BatchItemRet, err error) 88 | ``` 89 | 90 | 范围：仅在服务端使用 91 | 92 | 93 | ## 上传/下载授权凭证（uptoken/dntoken） 94 | 95 | ```{go} 96 | package "qiniu/api/rs" 97 | 98 | type PutPolicy struct { 99 | Scope string // 必选。可以是 bucketName 或者 bucketName:key 100 | CallbackUrl string // 可选。 101 | CallbackBody string // 可选 102 | ReturnUrl string // 可选 103 | ReturnBody string // 可选 104 | AsyncOps string // 可选 105 | EndUser string // 可选 106 | Expires uint32 // 可选。默认是 3600 秒 107 | } 108 | 109 | // 通常只有在key为非utf编码序列时候，才会返回错误 110 | func (this *PutPolicy) Token(mac *digest.Mac = nil) (uptoken string， err error) 111 | 112 | type GetPolicy struct { 113 | Expires uint32 // 可选。默认是 3600 秒 114 | } 115 | 116 | func (this GetPolicy) MakeRequest(baseUrl string, mac *digest.Mac = nil) (privateUrl string) 117 | 118 | func MakeBaseUrl(domain, key string) (baseUrl string) 119 | ``` 120 | 121 | 范围：仅在服务端使用 122 | 123 | 124 | ## 存储高级API（rsf） 125 | 126 | ```{go} 127 | package "qiniu/api/rsf" 128 | 129 | type Client struct { 130 | ... 131 | } 132 | 133 | func New(mac *digest.Mac = nil) Client 134 | 135 | func (this Client) ListPrefix( 136 | bucket, prefix, marker string, limit int) (entries []ListItem, markerOut string, err error) 137 | // 1. 首次请求 marker = "" 138 | // 2. 无论 err 值如何，均应该先看 entries 是否有内容 139 | // 3. 如果后续没有更多数据，err 返回 EOF，markerOut 返回 ""（但不通过该特征来判断是否结束） 140 | 141 | type ListItem struct { 142 | Key string 143 | Hash string 144 | Fsize int64 145 | PutTime int64 146 | MimeType string 147 | EndUser string 148 | } 149 | ``` 150 | 151 | 这个 `ListPrefix` 的标准用法如下： 152 | 153 | ```{go} 154 | import "qiniu/api/rsf" 155 | 156 | func listAll(rs rsf.Client, bucket, prefix string, limit int) { 157 | 158 | var items []rsf.ListItem 159 | var marker string 160 | var err error 161 | for err == nil { 162 | items, marker, err = rs.ListPrefix(bucket, prefix, marker, limit) 163 | for _, item := range items { 164 | ... // 处理item 165 | } 166 | } 167 | if err != rsf.EOF { 168 | ... // 错误处理 169 | } 170 | } 171 | ``` 172 | 173 | 范围：仅在服务端使用 174 | 175 | 176 | ## 上传（io） 177 | 178 | ```{go} 179 | package "qiniu/api/io" 180 | 181 | type PutExtra struct { 182 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 183 | MimeType string // 可选 184 | Crc32 uint32 185 | CheckCrc uint32 186 | // CheckCrc == 0: 表示不进行 crc32 校验 187 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 188 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 189 | } 190 | 191 | // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 192 | type PutRet struct { 193 | Hash string 194 | Key string 195 | } 196 | 197 | func Put( 198 | ret interface{}, uptoken string, key string, body io.Reader, extra *PutExtra) (err error) 199 | 200 | func PutWithoutKey( 201 | ret interface{}, uptoken string, body io.Reader, extra *PutExtra) (err error) 202 | 203 | func PutFile( 204 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 205 | 206 | func PutFileWithoutKey( 207 | ret interface{}, uptoken string, localFile string, extra *PutExtra) (err error) 208 | ``` 209 | 210 | 范围：客户端和服务端 211 | 212 | 213 | ## 断点续上传（resumable io） 214 | 215 | ```{go} 216 | package "qiniu/api/resumable/io" 217 | 218 | // upload 219 | 220 | type BlkputRet struct { 221 | Ctx string `json:"ctx"` 222 | Checksum string `json:"checksum"` 223 | Crc32 uint32 `json:"crc32"` 224 | Offset uint32 `json:"offset"` 225 | } 226 | 227 | type PutExtra struct { 228 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 229 | MimeType string // 可选。若为"" 则服务端自动判断 230 | ChunkSize int // 可选。每次上传的Chunk大小 231 | TryTimes int // 可选。尝试次数 232 | Progresses []BlkputRet // 可选。上传进度 233 | Notify func(blkIdx int, blkSize int, ret *BlkputRet) // 进度提示。注意blk是并行传输的 234 | NotifyErr func(blkIdx int, blkSize int, err error) 235 | } 236 | 237 | // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 238 | type PutRet struct { 239 | Hash string 240 | Key string 241 | } 242 | 243 | func Put( 244 | ret interface{}, uptoken string, 245 | key string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 246 | 247 | func PutWithoutKey( 248 | ret interface{}, uptoken string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 249 | 250 | func PutFile( 251 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 252 | 253 | func PutFileWithoutKey( 254 | ret interface{}, uptoken string, localFile string, extra *PutExtra) (err error) 255 | 256 | func BlockCount(fsize int64) int 257 | 258 | // global settings 259 | 260 | type Settings { 261 | TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4 262 | Workers int // 并行的工作线程数目。 263 | ChunkSize int // 默认的Chunk大小，不设定则为256k 264 | TryTimes int // 默认的尝试次数，不设定则为3 265 | } 266 | 267 | func SetSettings(settings *Settings) 268 | ``` 269 | 270 | 范围：客户端和服务端 271 | 272 | 273 | ## 数据处理API（fop） 274 | 275 | ```{go} 276 | package "qiniu/api/fop" 277 | 278 | // imageView 279 | 280 | type ImageView struct { 281 | Mode int // 缩略模式 282 | Width int // Width = 0 表示不限定宽度 283 | Height int // Height = 0 表示不限定高度 284 | Quality int // 质量, 1-100 285 | Format string // 输出格式，如jpg, gif, png, tif等等 286 | } 287 | 288 | func (this *ImageView) MakeRequest(url string) (imageViewUrl string) 289 | 290 | // imageMogr 291 | 292 | type ImageMogrify struct { 293 | ... // 待标准化 294 | } 295 | 296 | func (this *ImageMogrify) MakeRequest(url string) (imageMogrUrl string) 297 | 298 | // imageInfo 299 | 300 | type ImageInfoRet struct { 301 | Width int 302 | Height int 303 | Format string 304 | ColorModel string 305 | } 306 | 307 | type ImageInfo struct {} 308 | 309 | func (this ImageInfo) MakeRequest(url string) (imageInfoUrl string) 310 | 311 | // exif 312 | 313 | type Exif struct {} 314 | 315 | func (this Exif) MakeRequest(url string) (imageExifUrl string) 316 | ``` 317 | 318 | 范围：客户端和服务端 319 | 320 | 321 | ## 服务端上传（rsutil） 322 | 323 | ```{go} 324 | package "qiniu/api/rsutil" 325 | 326 | import ( 327 | "qiniu/api/rs" 328 | sio "qiniu/api/io" 329 | rio "qiniu/api/resumable/io" 330 | ) 331 | 332 | // simple upload 333 | 334 | func Put( 335 | c rs.Client, bucket string, 336 | key string, body io.Reader, extra *sio.PutExtra) (ret sio.PutRet, err error) 337 | 338 | func PutWithoutKey( 339 | c rs.Client, bucket string, 340 | body io.Reader, extra *sio.PutExtra) (ret sio.PutRet, err error) 341 | 342 | func PutFile( 343 | c rs.Client, bucket string, 344 | key string, localFile string, extra *sio.PutExtra) (ret sio.PutRet, err error) 345 | 346 | func PutFileWithoutKey( 347 | c rs.Client, bucket string, 348 | localFile string, extra *sio.PutExtra) (ret sio.PutRet, err error) 349 | 350 | // resumable upload 351 | 352 | func Rput( 353 | c rs.Client, bucket string, 354 | key string, f io.ReaderAt, fsize int64, extra *rio.PutExtra) (ret rio.PutRet, err error) 355 | 356 | func RputWithoutKey( 357 | c rs.Client, bucket string, 358 | f io.ReaderAt, fsize int64, extra *rio.PutExtra) (ret rio.PutRet, err error) 359 | 360 | func RputFile( 361 | c rs.Client, bucket string, 362 | key string, localFile string, extra *rio.PutExtra) (ret rio.PutRet, err error) 363 | 364 | func RputFileWithoutKey( 365 | c rs.Client, bucket string, 366 | localFile string, extra *rio.PutExtra) (ret rio.PutRet, err error) 367 | ``` 368 | 范围：仅在服务端使用。本模块仅仅是 rs + io/rio 的简单包装。 369 | 370 | ## 错误处理规范 371 | 1. 原则上`err`不应当跨`package`直接传递，比如 `api/io.put`调用`rpc`包的某个函数产生错误，不应该直接`return err`，可以适当的封装点一些信息比如 `err = fmt.Errorf("rpc net %v", err)` 372 | 2. 在适当的层级可以对`err`隐藏隔离，定义具有自己意义的错误，而没必要一味的返回，比如`PutPolicy.Token`中的 `json.Unmarshal`时候可能遇到错误`json.InvalidUTF8Error`。`io.Put`通常也会遇到非`utf8 key`, key中包含`\n`等问题。这种情况可以统一定义个`EINVALIDKEY = errors.New("invalid key format")`。 373 | 374 | ## 单元测试规范 375 | 1. 测试环境的初始化和清理工作应当看做单元测试的一部分。 376 | 2. SDK对外的接口都应该覆盖到，测试部分的代码风格和质量也要得到保证。 377 | -------------------------------------------------------------------------------- /ios/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：不同语言可以有不同的命名风格。本规范主要按类 Golang 风格进行描述（但不完全是）。 8 | - 名字空间：有的语言没有 package（namespace），通常通过名字前缀来表达。 9 | - 构造函数：有的语言没有构造函数，通过 NewXXX 函数来表达。本规范因为按 Golang 风格，构造函数也是用 NewXXX 进行描述。 10 | - 函数重载：有的语言没有函数重载，通过 XXXYYY 形式命名，其中 XXX 是功能，YYY 是不同重载函数的区分段。支持函数重载的语言没有 YYY 段。 11 | - 函数多返回值：有的语言不支持返回多个返回值，也不支持返回元组（tuple）。 12 | 13 | 14 | ## 服务端配置（conf） 15 | 16 | ```{go} 17 | package "qiniu/api/conf" 18 | 19 | var USER_AGENT string // 请求的 User-Agent 值，比如 "qiniu php-sdk v6.0.0" 20 | 21 | var UP_HOST string 22 | var RS_HOST string 23 | var RSF_HOST string 24 | 25 | var ACCESS_KEY string 26 | var SECRET_KEY string // 不要在客户端初始化该变量 27 | ``` 28 | 29 | 范围：服务端和客户端共用 30 | 31 | 32 | ## 签名认证（auth/digest） 33 | 34 | ```{go} 35 | package "qiniu/api/auth/digest" 36 | 37 | type Mac struct { 38 | AccessKey string 39 | SecretKey []byte 40 | } 41 | ``` 42 | 43 | 范围：仅在服务端使用 44 | 45 | 46 | ## 存储API（rs） 47 | 48 | ```{go} 49 | package "qiniu/api/rs" 50 | 51 | type Client struct { 52 | ... 53 | } 54 | 55 | func New(mac *digest.Mac = nil) Client 56 | 57 | func (this Client) Stat(bucket, key string) (entry Entry, err error) 58 | func (this Client) Delete(bucket, key string) (err error) 59 | func (this Client) Move(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 60 | func (this Client) Copy(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 61 | 62 | type Entry struct { 63 | Hash string 64 | Fsize int64 65 | PutTime int64 66 | MimeType string 67 | EndUser string 68 | } 69 | 70 | // batch 71 | 72 | type EntryPath struct { 73 | Bucket string 74 | Key string 75 | } 76 | 77 | type EntryPathPair struct { 78 | Src EntryPath 79 | Dest EntryPath 80 | } 81 | 82 | type BatchItemRet struct { 83 | Error string 84 | Code int 85 | } 86 | 87 | type BatchStatItemRet struct { 88 | Data Entry 89 | Error string 90 | Code int 91 | } 92 | 93 | func (this Client) BatchStat(entries []EntryPath) (rets []BatchStatItemRet, err error) 94 | func (this Client) BatchDelete(entries []EntryPath) (rets []BatchItemRet, err error) 95 | func (this Client) BatchMove(entries []EntryPathPair) (rets []BatchItemRet, err error) 96 | func (this Client) BatchCopy(entries []EntryPathPair) (rets []BatchItemRet, err error) 97 | ``` 98 | 99 | 范围：仅在服务端使用 100 | 101 | 102 | ## 上传/下载授权凭证（uptoken/dntoken） 103 | 104 | ```{go} 105 | package "qiniu/api/rs" 106 | 107 | type PutPolicy struct { 108 | Scope string // 必选。可以是 bucketName 或者 bucketName:key 109 | CallbackUrl string // 可选 110 | CallbackBody string // 可选 111 | ReturnUrl string // 可选 112 | ReturnBody string // 可选 113 | AsyncOps string // 可选 114 | EndUser string // 可选 115 | Expires uint32 // 可选。默认是 3600 秒 116 | } 117 | 118 | func (this *PutPolicy) Token(mac *digest.Mac = nil) (uptoken string) 119 | 120 | type GetPolicy struct { 121 | Expires uint32 // 可选。默认是 3600 秒 122 | } 123 | 124 | func (this GetPolicy) MakeRequest(baseUrl string, mac *digest.Mac = nil) (privateUrl string) 125 | 126 | func MakeBaseUrl(domain, key string) (baseUrl string) 127 | ``` 128 | 129 | 范围：仅在服务端使用 130 | 131 | 132 | ## 存储高级API（rsf） 133 | 134 | ```{go} 135 | package "qiniu/api/rsf" 136 | 137 | type Client struct { 138 | ... 139 | } 140 | 141 | func New(mac *digest.Mac = nil) Client 142 | 143 | func (this Client) ListPrefix( 144 | bucket, prefix, marker string, limit int) (entries []ListItem, markerOut string, err error) 145 | 146 | type ListItem struct { 147 | Key string 148 | Hash string 149 | Fsize int64 150 | PutTime int64 151 | MimeType string 152 | EndUser string 153 | } 154 | ``` 155 | 156 | 范围：仅在服务端使用 157 | 158 | 159 | ## 上传（io） 160 | 161 | ```{go} 162 | package "qiniu/api/io" 163 | 164 | // upload 165 | 166 | const UNDEFINED_KEY = "?" 167 | 168 | type PutExtra struct { 169 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 170 | MimeType string // 可选 171 | Crc32 uint32 172 | CheckCrc uint32 173 | // CheckCrc == 0: 表示不进行 crc32 校验 174 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 175 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 176 | } 177 | 178 | type PutRet struct { 179 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 180 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 181 | } 182 | 183 | func Put( 184 | ret interface{}, uptoken string, key string, body io.Reader, extra *PutExtra) (err error) 185 | 186 | func PutFile( 187 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 188 | ``` 189 | 190 | 范围：客户端和服务端 191 | 192 | 193 | ## 断点续上传（resumable io） 194 | 195 | ```{go} 196 | package "qiniu/api/resumable/io" 197 | 198 | // upload 199 | 200 | const UNDEFINED_KEY = "?" 201 | 202 | type BlkputRet struct { 203 | Ctx string `json:"ctx"` 204 | Checksum string `json:"checksum"` 205 | Crc32 uint32 `json:"crc32"` 206 | Offset uint32 `json:"offset"` 207 | } 208 | 209 | type PutExtra struct { 210 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 211 | MimeType string 212 | ChunkSize int // 可选。每次上传的Chunk大小 213 | TryTimes int // 可选。尝试次数 214 | Progresses []BlkputRet // 可选。上传进度 215 | Notify func(blkIdx int, blkSize int, ret *BlkputRet) // 进度提示。注意blk是并行传输的 216 | NotifyErr func(blkIdx int, blkSize int, err error) 217 | } 218 | 219 | type PutRet struct { 220 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 221 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 222 | } 223 | 224 | func Put( 225 | ret interface{}, uptoken string, 226 | key string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 227 | 228 | func PutFile( 229 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 230 | 231 | func BlockCount(fsize int64) int 232 | 233 | // global settings 234 | 235 | type Settings { 236 | TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4。 237 | Workers int // 并行的工作线程数目。 238 | ChunkSize int // 默认的Chunk大小，不设定则为256k 239 | TryTimes int // 默认的尝试次数，不设定则为3 240 | } 241 | 242 | func SetSettings(settings *Settings) 243 | ``` 244 | 245 | 范围：客户端和服务端 246 | 247 | 248 | ## 数据处理API（fop） 249 | 250 | ```{go} 251 | package "qiniu/api/fop" 252 | 253 | // imageView 254 | 255 | type ImageView struct { 256 | Mode int // 缩略模式 257 | Width int // Width = 0 表示不限定宽度 258 | Height int // Height = 0 表示不限定高度 259 | Quality int // 质量, 1-100 260 | Format string // 输出格式，如jpg, gif, png, tif等等 261 | } 262 | 263 | func (this *ImageView) MakeRequest(url string) (imageViewUrl string) 264 | 265 | // imageMogr 266 | 267 | type ImageMogrify struct { 268 | ... // 待标准化 269 | } 270 | 271 | func (this *ImageMogrify) MakeRequest(url string) (imageMogrUrl string) 272 | 273 | // imageInfo 274 | 275 | type ImageInfoRet struct { 276 | Width int 277 | Height int 278 | Format string 279 | ColorModel string 280 | } 281 | 282 | type ImageInfo struct {} 283 | 284 | func (this ImageInfo) MakeRequest(url string) (imageInfoUrl string) 285 | func (this ImageInfo) Call(url string) (ret ImageInfoRet, err error) 286 | 287 | // exif 288 | 289 | type ExifValType struct { 290 | Val string 291 | Type int 292 | } 293 | 294 | type ExifRet map[string] ExifValType 295 | type Exif struct {} 296 | 297 | func (this Exif) MakeRequest(url string) (imageExifUrl string) 298 | func (this Exif) Call(url string) (ret ExifRet, err error) 299 | ``` 300 | 301 | 范围：客户端和服务端 302 | 303 | -------------------------------------------------------------------------------- /java/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：不同语言可以有不同的命名风格。本规范主要按类 Golang 风格进行描述（但不完全是）。 8 | - 名字空间：有的语言没有 package（namespace），通常通过名字前缀来表达。 9 | - 构造函数：有的语言没有构造函数，通过 NewXXX 函数来表达。本规范因为按 Golang 风格，构造函数也是用 NewXXX 进行描述。 10 | - 函数重载：有的语言没有函数重载，通过 XXXYYY 形式命名，其中 XXX 是功能，YYY 是不同重载函数的区分段。支持函数重载的语言没有 YYY 段。 11 | - 函数多返回值：有的语言不支持返回多个返回值，也不支持返回元组（tuple）。 12 | 13 | 14 | ## 服务端配置（conf） 15 | 16 | ```{go} 17 | package "qiniu/api/conf" 18 | 19 | var USER_AGENT string // 请求的 User-Agent 值，比如 "qiniu php-sdk v6.0.0" 20 | 21 | var UP_HOST string 22 | var RS_HOST string 23 | var RSF_HOST string 24 | 25 | var ACCESS_KEY string 26 | var SECRET_KEY string // 不要在客户端初始化该变量 27 | ``` 28 | 29 | 范围：服务端和客户端共用 30 | 31 | 32 | ## 签名认证（auth/digest） 33 | 34 | ```{go} 35 | package "qiniu/api/auth/digest" 36 | 37 | type Mac struct { 38 | AccessKey string 39 | SecretKey []byte 40 | } 41 | ``` 42 | 43 | 范围：仅在服务端使用 44 | 45 | 46 | ## 存储API（rs） 47 | 48 | ```{go} 49 | package "qiniu/api/rs" 50 | 51 | type Client struct { 52 | ... 53 | } 54 | 55 | func New(mac *digest.Mac = nil) Client 56 | 57 | func (this Client) Stat(bucket, key string) (entry Entry, err error) 58 | func (this Client) Delete(bucket, key string) (err error) 59 | func (this Client) Move(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 60 | func (this Client) Copy(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 61 | 62 | type Entry struct { 63 | Hash string 64 | Fsize int64 65 | PutTime int64 66 | MimeType string 67 | EndUser string 68 | } 69 | 70 | // batch 71 | 72 | type EntryPath struct { 73 | Bucket string 74 | Key string 75 | } 76 | 77 | type EntryPathPair struct { 78 | Src EntryPath 79 | Dest EntryPath 80 | } 81 | 82 | type BatchItemRet struct { 83 | Error string 84 | Code int 85 | } 86 | 87 | type BatchStatItemRet struct { 88 | Data Entry 89 | Error string 90 | Code int 91 | } 92 | 93 | func (this Client) BatchStat(entries []EntryPath) (rets []BatchStatItemRet, err error) 94 | func (this Client) BatchDelete(entries []EntryPath) (rets []BatchItemRet, err error) 95 | func (this Client) BatchMove(entries []EntryPathPair) (rets []BatchItemRet, err error) 96 | func (this Client) BatchCopy(entries []EntryPathPair) (rets []BatchItemRet, err error) 97 | ``` 98 | 99 | 范围：仅在服务端使用 100 | 101 | 102 | ## 上传/下载授权凭证（uptoken/dntoken） 103 | 104 | ```{go} 105 | package "qiniu/api/rs" 106 | 107 | type PutPolicy struct { 108 | Scope string // 必选。可以是 bucketName 或者 bucketName:key 109 | CallbackUrl string // 可选 110 | CallbackBody string // 可选 111 | ReturnUrl string // 可选 112 | ReturnBody string // 可选 113 | AsyncOps string // 可选 114 | EndUser string // 可选 115 | Expires uint32 // 可选。默认是 3600 秒 116 | } 117 | 118 | func (this *PutPolicy) Token(mac *digest.Mac = nil) (uptoken string) 119 | 120 | type GetPolicy struct { 121 | Expires uint32 // 可选。默认是 3600 秒 122 | } 123 | 124 | func (this GetPolicy) MakeRequest(baseUrl string, mac *digest.Mac = nil) (privateUrl string) 125 | 126 | func MakeBaseUrl(domain, key string) (baseUrl string) 127 | ``` 128 | 129 | 范围：仅在服务端使用 130 | 131 | 132 | ## 存储高级API（rsf） 133 | 134 | ```{go} 135 | package "qiniu/api/rsf" 136 | 137 | type Client struct { 138 | ... 139 | } 140 | 141 | func New(mac *digest.Mac = nil) Client 142 | 143 | func (this Client) ListPrefix( 144 | bucket, prefix, marker string, limit int) (entries []ListItem, markerOut string, err error) 145 | 146 | type ListItem struct { 147 | Key string 148 | Hash string 149 | Fsize int64 150 | PutTime int64 151 | MimeType string 152 | EndUser string 153 | } 154 | ``` 155 | 156 | 范围：仅在服务端使用 157 | 158 | 159 | ## 上传（io） 160 | 161 | ```{go} 162 | package "qiniu/api/io" 163 | 164 | // upload 165 | 166 | const UNDEFINED_KEY = "?" 167 | 168 | type PutExtra struct { 169 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 170 | MimeType string // 可选 171 | Crc32 uint32 172 | CheckCrc uint32 173 | // CheckCrc == 0: 表示不进行 crc32 校验 174 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 175 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 176 | } 177 | 178 | type PutRet struct { 179 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 180 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 181 | } 182 | 183 | func Put( 184 | ret interface{}, uptoken string, key string, body io.Reader, extra *PutExtra) (err error) 185 | 186 | func PutFile( 187 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 188 | ``` 189 | 190 | 范围：客户端和服务端 191 | 192 | 193 | ## 断点续上传（resumable io） 194 | 195 | ```{go} 196 | package "qiniu/api/resumable/io" 197 | 198 | // upload 199 | 200 | const UNDEFINED_KEY = "?" 201 | 202 | type BlkputRet struct { 203 | Ctx string `json:"ctx"` 204 | Checksum string `json:"checksum"` 205 | Crc32 uint32 `json:"crc32"` 206 | Offset uint32 `json:"offset"` 207 | } 208 | 209 | type PutExtra struct { 210 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 211 | MimeType string 212 | ChunkSize int // 可选。每次上传的Chunk大小 213 | TryTimes int // 可选。尝试次数 214 | Progresses []BlkputRet // 可选。上传进度 215 | Notify func(blkIdx int, blkSize int, ret *BlkputRet) // 进度提示。注意blk是并行传输的 216 | NotifyErr func(blkIdx int, blkSize int, err error) 217 | } 218 | 219 | type PutRet struct { 220 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 221 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 222 | } 223 | 224 | func Put( 225 | ret interface{}, uptoken string, 226 | key string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 227 | 228 | func PutFile( 229 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 230 | 231 | func BlockCount(fsize int64) int 232 | 233 | // global settings 234 | 235 | type Settings { 236 | TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4。 237 | Workers int // 并行的工作线程数目。 238 | ChunkSize int // 默认的Chunk大小，不设定则为256k 239 | TryTimes int // 默认的尝试次数，不设定则为3 240 | } 241 | 242 | func SetSettings(settings *Settings) 243 | ``` 244 | 245 | 范围：客户端和服务端 246 | 247 | 248 | ## 数据处理API（fop） 249 | 250 | ```{go} 251 | package "qiniu/api/fop" 252 | 253 | // imageView 254 | 255 | type ImageView struct { 256 | Mode int // 缩略模式 257 | Width int // Width = 0 表示不限定宽度 258 | Height int // Height = 0 表示不限定高度 259 | Quality int // 质量, 1-100 260 | Format string // 输出格式，如jpg, gif, png, tif等等 261 | } 262 | 263 | func (this *ImageView) MakeRequest(url string) (imageViewUrl string) 264 | 265 | // imageMogr 266 | 267 | type ImageMogrify struct { 268 | ... // 待标准化 269 | } 270 | 271 | func (this *ImageMogrify) MakeRequest(url string) (imageMogrUrl string) 272 | 273 | // imageInfo 274 | 275 | type ImageInfoRet struct { 276 | Width int 277 | Height int 278 | Format string 279 | ColorModel string 280 | } 281 | 282 | type ImageInfo struct {} 283 | 284 | func (this ImageInfo) MakeRequest(url string) (imageInfoUrl string) 285 | func (this ImageInfo) Call(url string) (ret ImageInfoRet, err error) 286 | 287 | // exif 288 | 289 | type ExifValType struct { 290 | Val string 291 | Type int 292 | } 293 | 294 | type ExifRet map[string] ExifValType 295 | type Exif struct {} 296 | 297 | func (this Exif) MakeRequest(url string) (imageExifUrl string) 298 | func (this Exif) Call(url string) (ret ExifRet, err error) 299 | ``` 300 | 301 | 范围：客户端和服务端 302 | 303 | -------------------------------------------------------------------------------- /nodejs/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | 6 | - 命名风格：按照 [http://nodeguide.com/style.html](http://nodeguide.com/style.html) 7 | - callback： sdk中出现的`onret`都是`function(err, resp){}`形式 8 | - 以Key为对象进行大部分操作，支持stream上传下载。 9 | - Bucket, Key, Batch 一共这3个对象操作 10 | 11 | 12 | ## 服务端配置（conf） 13 | 14 | ```{js} 15 | var USER_AGENT = ''// 请求的 User-Agent 值，比如 'qiniu nodejs-sdk v7.0.0' 16 | 17 | var UP_HOST = 'http://up.qiniu.com'; 18 | var RS_HOST = 'http://rs.qiniu.com'; 19 | var RSF_HOST = 'http://rsf.qiniu.com'; 20 | 21 | var ACCESS_KEY = ''; 22 | var SECRET_KEY = ''; 23 | 24 | conf = { 25 | 'accessKey': accessKey, 26 | 'secretKey': secretKey 27 | }; 28 | exports.SetConf(conf); 29 | ``` 30 | 31 | 范围：服务端和客户端共用 32 | 33 | ## bucket 34 | 35 | ```{js} 36 | exports.Bucket = Bucket; 37 | 38 | conf = { 39 | ... 40 | 'bucketName': bucketname, 41 | 'dnHost': dnHost, // 没有指定则为 http://.qiniudn.com 42 | 'public': true || false 43 | } 44 | Bucket = function(conf) {} 45 | 46 | // 获取key，keyname可为null 47 | Bucket.prototype.key = function([keyname]) {} 48 | // 列出 prefix 前缀的文件 49 | Bucket.prototype.listPrefix = function(prefix, marker, limit, onret) {} 50 | ``` 51 | 52 | 范围：服务端和客户端共用 53 | 54 | ## 存储API（rs） 55 | 56 | ```{js} 57 | Key.prototype.stat = function(onret) {} 58 | Key.prototype.remove = function(onret) {} 59 | Key.prototype.move = function(dstKey, onret) {} 60 | Key.prototype.copy = function(dstKey, onret) {} 61 | 62 | // conf 在操作非default accesskey时候用 63 | exports.Batch = Batch; 64 | Batch = function(conf) {} 65 | 66 | Batch.prototype.stat = function([key, ...], onret) {} 67 | Batch.prototype.copy = function([[src, dst], ...], onret) {} 68 | Batch.prototype.move = function([[src, dst], ...], onret) {} 69 | Batch.prototype.remove = function([key, ...], onret) {} 70 | ``` 71 | 72 | 范围：仅在服务端使用 73 | 74 | 75 | ## 上传/下载授权凭证（uptoken/dntoken） 76 | 77 | ```{js} 78 | putPolicy = { 79 | 'callbackUrl': callbackUrl, 80 | 'callbackBody': callbackBody, 81 | 'returnUrl': returnUrl, 82 | 'returnBody': returnBody, 83 | 'asyncOps': asyncOps, 84 | 'endUser': endUser, 85 | 'expires': expires 86 | } 87 | 88 | // bucket 89 | Bucket.prototype.uptoken = function([putPolicy]) 90 | // bucket:key 91 | Key.prototype.uptoken = function([putPolicy]) 92 | ``` 93 | 94 | 范围：仅在服务端使用 95 | 96 | 97 | ## 上传（io） 98 | 99 | ```{js} 100 | extra = { 101 | 'params': {...}, 102 | 'mimeType': 'image/webp', 103 | 'crc32': 'crc32 code', 104 | 'checkCrc': 0 || 1 || 2 105 | // checkCrc == 0: 表示不进行 crc32 校验 106 | // checkCrc == 1: 对于 Put 等同于 checkCrc = 2；对于 PutFile 会自动计算 crc32 值 107 | // checkCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 crc32 变量 108 | } 109 | 110 | // 可以指定2、3、4个参数 111 | // 从内存中上传文件 112 | Key.prototype.put = function(body, [extra], [uptoken], onret) {} 113 | // 根据文件名上传文件 114 | Key.prototype.putFile = function(loadFile, [extra], [uptoken], onret) {} 115 | // 根据文件名上传文件，不指定key 116 | 117 | 118 | Key.prototype.setToken = function(token) {} 119 | Key.prototype.setExtra = function(extra) {} 120 | 121 | read = createReadStream("xxx"); 122 | read.pipe(key) 123 | 124 | // download, auto public or private 125 | Key.prototype.downloadUrl = function([expires]) {} 126 | ``` 127 | 128 | 范围：客户端和服务端 129 | 130 | ## 数据处理API（fop） 131 | 132 | ```{js} 133 | // imageInfo 134 | Key.prototype.imageInfoUrl = function() {} 135 | Key.prototype.imageInfoCall = function([imageInfoUrl], onret) {} 136 | 137 | // exif 138 | Key.prototype.exifUrl = function() {} 139 | Key.prototype.exifCall = function([exifUrl], onret) {} 140 | 141 | // qrcode 142 | Key.prototype.qrcodeUrl = function() {} 143 | 144 | // imageView 145 | imageView = { 146 | 'mode': mode, // 缩略模式 147 | 'width': width, // Width = 0 表示不限定宽度 148 | 'height': height, // Height = 0 表示不限定高度 149 | 'quality': quality, // 质量, 1-100 150 | 'format': format // 输出格式，如jpg, gif, png, tif等等 151 | } 152 | 153 | Key.prototype.imageViewUrl = function(imageView) {} 154 | 155 | // imageMogr 156 | imageMogr = { 157 | ... 158 | } 159 | 160 | Key.prototype.imageMogrUrl = function(imageMogr) {} 161 | ``` 162 | 163 | 范围：客户端和服务端 164 | -------------------------------------------------------------------------------- /php/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage PHP SDK Specification 2 | 3 | [![Qiniu Lophp](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 服务端配置（conf） 6 | 7 | ``` 8 | {php} 9 | //资源上传服务器地址 10 | $QINIU_UP_HOST = 'http://up.qiniu.com'; 11 | 12 | //资源管理服务器地址 13 | $QINIU_RS_HOST = 'http://rs.qbox.me'; 14 | 15 | //资源列表服务器地址 16 | $QINIU_RSF_HOST = 'http://rsf.qbox.me'; 17 | 18 | //公钥 19 | $QINIU_ACCESS_KEY = ''; 20 | 21 | //私钥 不要在客户端初始化该变量 22 | $QINIU_SECRET_KEY = ''; 23 | 24 | ``` 25 | 26 | 27 | ## 签名认证（auth digest） 28 | 29 | ``` 30 | {php} 31 | 32 | class Qiniu_Mac { 33 | 34 | public $AccessKey; 35 | public $SecretKey; 36 | 37 | public function Sign ($data) {} 38 | public function SignWithData ($data) {} 39 | public function SignRequest ($req, $incbody) {} 40 | } 41 | 42 | ``` 43 | 44 | 范围：仅在服务端使用 45 | 46 | 47 | ## http客户端（http） 48 | 49 | ``` 50 | 51 | class Qiniu_Error 52 | { 53 | /** 54 | * @var string 55 | */ 56 | public $Err; // string 57 | 58 | /** 59 | * @var string 60 | */ 61 | public $Reqid; // string 62 | 63 | /** 64 | * @var []string 65 | */ 66 | public $Details; // []string 67 | 68 | /** 69 | * @var int 70 | */ 71 | public $Code; // int 72 | 73 | public function __construct($code, $err) 74 | { 75 | $this->Code = $code; 76 | $this->Err = $err; 77 | } 78 | } 79 | 80 | class Qiniu_Request 81 | { 82 | /** 83 | * @var string 84 | */ 85 | public $URL; 86 | 87 | /** 88 | * @var []string 89 | */ 90 | public $Header; 91 | 92 | /** 93 | * @var mixed 94 | */ 95 | public $Body; 96 | 97 | public function __construct($url, $body) 98 | { 99 | $this->URL = $url; 100 | $this->Header = array(); 101 | $this->Body = $body; 102 | } 103 | } 104 | 105 | 106 | class Qiniu_Response 107 | { 108 | /** 109 | * @var int 状态码 110 | */ 111 | public $StatusCode; 112 | 113 | /** 114 | * @var []string 115 | */ 116 | public $Header; 117 | 118 | /** 119 | * @var int 120 | */ 121 | public $ContentLength; 122 | 123 | /** 124 | * @var mixed 125 | */ 126 | public $Body; 127 | 128 | public function __construct($code, $body) 129 | { 130 | $this->StatusCode = $code; 131 | $this->Header = array(); 132 | $this->Body = $body; 133 | $this->ContentLength = strlen($body); 134 | } 135 | } 136 | 137 | /** 138 | * httpclient 139 | */ 140 | class Qiniu_HttpClient 141 | { 142 | /** 143 | * @param Qiniu_Request $req 144 | * @return array(Qiniu_Response $resp, Qiniu_Error $error) 145 | */ 146 | public function RoundTrip($req) {} 147 | } 148 | 149 | /** 150 | * 经过认证的httpclient 151 | */ 152 | class Qiniu_MacHttpClient 153 | { 154 | /** 155 | * @var Qiniu_Mac 156 | */ 157 | public $Mac; 158 | 159 | public function __construct($mac) {} 160 | 161 | /** 162 | * @param Qiniu_Request $req 163 | * @return array(Qiniu_Response $resp, Qiniu_Error $error) 164 | */ 165 | public function RoundTrip($req) {} 166 | } 167 | 168 | ``` 169 | 170 | 171 | 172 | ## 存储API（rs） 173 | 174 | ``` 175 | {php} 176 | 177 | /** 178 | * 资源路径: $bucket . ':' . $key 179 | */ 180 | class Qiniu_RS_EntryPath 181 | { 182 | /** 183 | * @var string Bucket name 184 | */ 185 | public $bucket; 186 | 187 | /** 188 | * @var string file key 189 | */ 190 | public $key; 191 | 192 | public function __construct($bucket, $key) 193 | { 194 | $this->bucket = $bucket; 195 | $this->key = $key; 196 | } 197 | } 198 | 199 | /** 200 | * 二元操作路径 201 | */ 202 | class Qiniu_RS_EntryPathPair 203 | { 204 | /** 205 | * @var Qiniu_RS_EntryPath 206 | */ 207 | public $src; 208 | 209 | /** 210 | * @var Qiniu_RS_EntryPath 211 | */ 212 | public $dest; 213 | 214 | public function __construct($src, $dest) 215 | { 216 | $this->src = $src; 217 | $this->dest = $dest; 218 | } 219 | } 220 | 221 | /** 222 | * 查看单个文件的信息 223 | * @param Qiniu_MacHttpClient $self 224 | * @param string $bucket 225 | * @param string $key 226 | * @return array($statRet, Qiniu_ResponseError $error) 227 | */ 228 | function Qiniu_RS_Stat($self, $bucket, $key) {} 229 | 230 | /** 231 | * 删除单个文件 232 | * @param Qiniu_MacHttpClient $self 233 | * @param string $bucket 234 | * @param string $key 235 | * @return Qiniu_ResponseError $error 236 | */ 237 | function Qiniu_RS_Delete($self, $bucket, $key) {} 238 | 239 | /** 240 | * 移动文件 241 | * @param Qiniu_MacHttpClient $self 242 | * @param string $bucketSrc 243 | * @param string $keySrc 244 | * @param string $bucketDest 245 | * @param string $keyDest 246 | * @return Qiniu_ResponseError $error 247 | */ 248 | function Qiniu_RS_Move($self, $bucketSrc, $keySrc, $bucketDest, $keyDest) {} 249 | 250 | /** 251 | * 文件复制 252 | * @param Qiniu_MacHttpClient $self 253 | * @param string $bucketSrc 254 | * @param string $keySrc 255 | * @param string $bucketDest 256 | * @param string $keyDest 257 | * @return Qiniu_ResponseError $error 258 | */ 259 | function Qiniu_RS_Copy($self, $bucketSrc, $keySrc, $bucketDest, $keyDest) {} 260 | 261 | function Qiniu_RS_Batch($self, $ops) {} 262 | 263 | /** 264 | * 批量文件查看 265 | * @param Qiniu_MacHttpClient $self 266 | * @param Array Qiniu_RS_EntryPath $entryPaths 267 | * @return array($statRet, Qiniu_ResponseError $err) 268 | */ 269 | function Qiniu_RS_BatchStat($self, $entryPaths) {} 270 | 271 | /** 272 | * 批量文件查看 273 | * @param Qiniu_MacHttpClient $self 274 | * @param Array Qiniu_RS_EntryPath $entryPaths 275 | * @return array($statRet, Qiniu_ResponseError $err) 276 | */ 277 | function Qiniu_RS_BatchDelete($self, $entryPaths) {} 278 | 279 | /** 280 | * 批量文件查看 281 | * @param Qiniu_MacHttpClient $self 282 | * @param Array Qiniu_RS_EntryPathPair $entryPairs 283 | * @return array($statRet, Qiniu_ResponseError $err) 284 | */ 285 | function Qiniu_RS_BatchMove($self, $entryPairs) {} 286 | 287 | /** 288 | * 批量文件查看 289 | * @param Qiniu_MacHttpClient $self 290 | * @param Array Qiniu_RS_EntryPathPair $entryPairs 291 | * @return array($statRet, Qiniu_ResponseError $err) 292 | */ 293 | function Qiniu_RS_BatchCopy($self, $entryPairs) {} 294 | 295 | ``` 296 | 297 | 范围：仅在服务端使用 298 | 299 | 300 | ## 上传/下载授权凭证（uptoken/dntoken） 301 | 302 | ``` 303 | {php} 304 | 305 | class Qiniu_RS_PutPolicy 306 | { 307 | 308 | /** 309 | * 一般指文件要上传到的目标存储空间（Bucket）。 310 | * 若为”Bucket”，表示限定只能传到该Bucket（仅限于新增文件）。 311 | * 若为”Bucket:Key”，表示限定特定的文件，可修改该文件。 312 | */ 313 | public $Scope; 314 | 315 | /** 316 | * 文件上传成功后，Qiniu-Cloud-Server 向 App-Server 发送POST请求的URL. 317 | * 必须是公网上可以正常进行POST请求并能响应 HTTP Status 200 OK 的有效 URL 318 | */ 319 | public $CallbackUrl; 320 | 321 | /** 322 | * 文件上传成功后，Qiniu-Cloud-Server 向 App-Server 发送POST请求的数据。 323 | * 支持 魔法变量 和 自定义变量，不可与 returnBody 同时使用。 324 | */ 325 | public $CallbackBody; 326 | 327 | /** 328 | * 设置用于浏览器端文件上传成功后，浏览器执行301跳转的URL，一般为 HTML Form 上传时使用。 329 | * 文件上传成功后会跳转到 returnUrl?query_string, query_string 会包含 returnBody 内容。 330 | * returnUrl 不可与 callbackUrl 同时使用。 331 | */ 332 | public $ReturnUrl; 333 | 334 | /** 335 | * 文件上传成功后，自定义从 Qiniu-Cloud-Server 最终返回給终端 App-Client 的数据。 336 | * 支持 魔法变量，不可与 callbackBody 同时使用。 337 | */ 338 | public $ReturnBody; 339 | 340 | /** 341 | * 指定文件（图片/音频/视频）上传成功后异步地执行指定的预转操作。 342 | * 每个预转指令是一个API规格字符串，多个预转指令可以使用分号“;”隔开。 343 | */ 344 | public $AsyncOps; 345 | 346 | /** 347 | * 给上传的文件添加唯一属主标识，特殊场景下非常有用，比如根据终端用户标识给图片或视频打水印 348 | */ 349 | public $EndUser; 350 | 351 | /** 352 | * 定义 uploadToken 的失效时间，Unix时间戳，精确到秒，缺省为 3600 秒 353 | */ 354 | public $Expires; 355 | 356 | 357 | /** 358 | * 构造函数 359 | */ 360 | public function __construct($scope) 361 | { 362 | $this->Scope = $scope; 363 | } 364 | 365 | /** 366 | * 生成upload token 367 | */ 368 | public function Token($mac) {} 369 | 370 | } 371 | 372 | class Qiniu_RS_GetPolicy 373 | { 374 | 375 | /** 376 | * 可选， 默认3600秒 377 | */ 378 | public $Expires; 379 | 380 | /** 381 | * 对请求url 进行前面 382 | */ 383 | public function MakeRequest($baseUrl, $mac) {} 384 | } 385 | 386 | /** 387 | * 构造请求url 388 | */ 389 | function Qiniu_RS_MakeBaseUrl($domain, $key) {} 390 | ``` 391 | 392 | 范围：仅在服务端使用 393 | 394 | 395 | ## 存储高级API（rsf） 396 | 397 | ``` 398 | {php} 399 | /** 400 | * 1. 首次请求 marker = "" 401 | * 2. 无论 err 值如何，均应该先看 items 是否有内容 402 | * 3. 如果后续没有更多数据，err 返回 EOF，markerOut 返回 ""（但不通过该特征来判断是否结束） 403 | * @param $self Qiniu_MacHttpClient 404 | * @param $bucket string 405 | * Bucket name. 406 | * @param $prefix string 407 | * 要list文件的前缀 408 | * @param $marker string 409 | * Fetch 定位符. 410 | * @param $limit int 411 | * Fetch返回结果条目数量限制 412 | * 413 | */ 414 | function Qiniu_RSF_ListPrefix( 415 | $self, $bucket, $prefix = '', $marker = '', $limit = 0) {} 416 | ``` 417 | 418 | 419 | ## 上传（io） 420 | 421 | ``` 422 | {php} 423 | 424 | class Qiniu_PutExtra 425 | { 426 | /** 427 | * 用户自定义参数，key必须以 "x:" 开头 428 | */ 429 | public $Params = null; 430 | 431 | /** 432 | * 文件的媒体类型 433 | */ 434 | public $MimeType = null; 435 | 436 | /** 437 | * crc32 值 438 | */ 439 | public $Crc32 = 0; 440 | 441 | /** 442 | * 是否对上传内容进行 crc32 检验 443 | * CheckCrc == 0: 表示不进行 crc32 校验 444 | * CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 445 | * CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 446 | */ 447 | public $CheckCrc = 0; 448 | } 449 | 450 | function Qiniu_Put($upToken, $key, $body, $putExtra) {} 451 | 452 | function Qiniu_PutFile($upToken, $key, $localFile, $putExtra) {} 453 | 454 | ``` 455 | 456 | 范围：客户端和服务端 457 | 458 | 459 | ## 断点续上传（resumable io） 460 | 461 | ``` 462 | 463 | {php} 464 | 465 | class Qiniu_Rio_PutExtra 466 | { 467 | /** 468 | * @var string 必选 （未来会没有这个字段）。 469 | */ 470 | public $Bucket = null; 471 | 472 | /** 473 | * @var array 用户自定义参数，key必须以 "x:" 开头 474 | */ 475 | public $Params = null; 476 | 477 | /** 478 | * @var string 479 | */ 480 | public $MimeType = null; 481 | 482 | /** 483 | * @var int 可选。每次上传的Chunk大小 484 | */ 485 | public $ChunkSize = 0; 486 | 487 | /** 488 | * @var int 可选。尝试次数 489 | */ 490 | public $TryTimes = 0; 491 | 492 | /** 493 | * @var []BlkputRet 可选。上传进度 494 | */ 495 | public $Progresses = null; 496 | 497 | /** 498 | * @var func(blkIdx int, blkSize int, ret *BlkputRet) 进度通知 499 | */ 500 | public $Notify = null; 501 | 502 | /** 503 | * @var func(blkIdx int, blkSize int, err error) 错误通知 504 | */ 505 | public $NotifyErr = null; 506 | 507 | public function __construct($bucket = null) { 508 | $this->Bucket = $bucket; 509 | } 510 | } 511 | 512 | 513 | function Qiniu_Rio_Mkblock ($self, $host, $reader, $size) {} 514 | function Qiniu_Rio_Mkfile($self, $host, $key, $fsize, $extra) {} 515 | 516 | class Qiniu_Rio_UploadClient 517 | { 518 | public $uptoken; 519 | 520 | public function __construct($uptoken) 521 | { 522 | $this->uptoken = $uptoken; 523 | } 524 | 525 | public function RoundTrip ($req) {} 526 | 527 | } 528 | 529 | 530 | /** 531 | * @param string $upToken 532 | * @param string $key 533 | * @param mixed $body 534 | * @param int $fsize 535 | * @param Qiniu_Rio_PutExtra $putExtra 536 | * @return array($putRet, $err) 537 | */ 538 | function Qiniu_Rio_Put($upToken, $key, $body, $fsize, $putExtra) {} 539 | 540 | /** 541 | * @param string $upToken 542 | * @param string $key 543 | * @param string $localFile 544 | * @param Qiniu_Rio_PutExtra $putExtra 545 | * @return array($putRet, $err) 546 | */ 547 | function Qiniu_Rio_PutFile($upToken, $key, $localFile, $putExtra) {} 548 | 549 | ``` 550 | 551 | 范围：客户端和服务端 552 | 553 | 554 | ## 数据处理API（fop） 555 | 556 | ``` 557 | {php} 558 | 559 | class Qiniu_ImageView { 560 | /** 561 | * @var int 缩略模式 562 | */ 563 | public $Mode; 564 | 565 | /** 566 | * @var int 不设置时，不限定宽度。 567 | */ 568 | public $Width; 569 | 570 | /** 571 | * @var int 不设置时，不限定宽度。 572 | */ 573 | public $Height; 574 | 575 | /** 576 | * @var int 图片质量： 1-100 577 | */ 578 | public $Quality; 579 | 580 | /** 581 | * @var string 图片输出格式 如 png, jpg 等 582 | */ 583 | public $Format; 584 | 585 | /** 586 | * @param string $url 587 | * 图片的url 588 | * @return string 589 | */ 590 | public function MakeRequest($url) {} 591 | } 592 | 593 | class Qiniu_Exif { 594 | /** 595 | * @param string $url 596 | * 图片的url 597 | * @return string 598 | */ 599 | public function MakeRequest($url) {} 600 | 601 | } 602 | 603 | class Qiniu_ImageInfo { 604 | 605 | /** 606 | * @param string $url 607 | * 图片的url 608 | * @return string 609 | */ 610 | public function MakeRequest($url) {} 611 | } 612 | ``` 613 | 614 | 范围：客户端和服务端 615 | 616 | -------------------------------------------------------------------------------- /python/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：本规范主要按类 Python 风格进行描述。 8 | 9 | ## 服务端配置（conf） 10 | 11 | ```{python} 12 | ACCESS_KEY = "" 13 | SECRET_KEY = "" 14 | 15 | RS_HOST = "rs.qbox.me" 16 | RSF_HOST = "rsf.qbox.me" 17 | UP_HOST = "up.qiniu.com" 18 | 19 | USER_AGENT = "qiniu python-sdk v%s" % __version__ 20 | ``` 21 | 22 | 范围：服务端和客户端共用 23 | 24 | ## 签名认证（auth/digest） 25 | 26 | ```{python} 27 | import auth.digest 28 | 29 | class Mac(object): 30 | access = None 31 | secret = None 32 | 33 | def __init__(self, access=None, secret=None): 34 | self.access = access 35 | self.secret = secret 36 | ``` 37 | 38 | 范围：仅在服务端使用 39 | 40 | Bucket 41 | 42 | ```{python} 43 | conf = { 44 | "bucket": , 45 | "dn_host": , 46 | "public": True|False 47 | } 48 | 49 | class Bucket(Object): 50 | bucket_name = None 51 | domain = None 52 | public = None 53 | 54 | def __init__(self, conf=None): 55 | if isinstance(conf, str): 56 | self.bucket_name = conf 57 | if isinstance(conf, dict): 58 | self.bucket_name = conf["bucket"] 59 | self.domain = conf"dn_host"] 60 | self.public = conf["public"] 61 | 62 | def key(self, key): 63 | return 64 | 65 | def list_prefix(self, prefix, marker, limit): 66 | return [{ 67 | "Key": , 68 | "Hash": , 69 | "Fsize": , 70 | "PutTime": , 71 | "MimeType": , 72 | "EndUser": 73 | } 74 | ... 75 | ] 76 | 77 | ``` 78 | 79 | ## 存储API（rs） 80 | 81 | ```{python} 82 | 83 | class Key(Object): 84 | bucket_obj = None 85 | key = None 86 | 87 | def __init__(self, bucket_obj, key): 88 | self.bucket_obj = bucket_obj 89 | self.key = key 90 | 91 | def stat(self): 92 | return (, , , , ) 93 | def remove(self): 94 | return err 95 | def move(self, dst_key): 96 | """ 97 | @dst_key: dst_key is also a Key object, for example, Bucket("mybucket").key(["mykey"]) 98 | """ 99 | return err 100 | def copy(self, dst_key): 101 | """ 102 | @dst_key: dst_key is also a Key object, for example, Bucket("mybucket").key(["mykey"]) 103 | """ 104 | return err 105 | 106 | ``` 107 | 108 | Batch Key operations 109 | 110 | ```{python} 111 | 112 | class Batch_Key(Object): 113 | bucket_obj = None 114 | key_list = None 115 | 116 | def __init__(self, bucket_obj, [key1, key2, ...]): 117 | self.bucket_obj = bucket_obj 118 | self.key_list = [key1, key2, ...] 119 | 120 | def stat(self): 121 | return [{ 122 | "data":{"hash":, "fsize":, "mimeType":, "endUser":}, 123 | "error":"err_string", 124 | "code": 125 | }, 126 | ... 127 | ] 128 | def remove(self): 129 | return [{"error":"err_string","code":}...] 130 | def move(self, dst_batch_key): 131 | """ 132 | @dst_batch_key: a Batch_Key object 133 | """ 134 | return [{"error":"err_string","code":}...] 135 | def copy(self, dst_batch_key): 136 | """ 137 | @dst_batch_key: a Batch_Key object 138 | """ 139 | return [{"error":"err_string","code":}...] 140 | ``` 141 | 142 | 范围：仅在服务端使用 143 | 144 | ## 上传/下载授权凭证（uptoken/dntoken） 145 | 146 | ```{python} 147 | 148 | put_policy = { 149 | "CallbackUrl": , 150 | "CallbackBody: , 151 | "ReturnUrl": , 152 | "ReturnBody": , 153 | "AsyncOps": , 154 | "EndUser": , 155 | "Expires": 156 | } 157 | 158 | get_policy = { 159 | "Expires": 160 | } 161 | 162 | class Bucket(Object): 163 | 164 | ... ... 165 | 166 | def uptoken(self, put_policy): 167 | """ Up Token of scope """ 168 | pass 169 | 170 | class Key(Object): 171 | 172 | ... ... 173 | 174 | def uptoken(self, put_policy): 175 | """ uptoken of scope: : """ 176 | pass 177 | 178 | def dntoken(self, get_policy): pass 179 | 180 | Bucket("foo").uptoken(put_policy) 181 | Bucket("foo").key("bar").uptoken(put_policy) 182 | Bucket("foo").key("bar").dntoken(get_policy) 183 | 184 | ``` 185 | 范围：仅在服务端使用 186 | 187 | 188 | ## 上传/下载 (io) 189 | 190 | ```{python} 191 | extra = { 192 | 'params': {...}, 193 | 'mimeType': , 194 | 'crc32': , 195 | 'checkCrc': 0 || 1 || 2 196 | // checkCrc == 0: 表示不进行 crc32 校验 197 | // checkCrc == 1: 对于 Put 等同于 checkCrc = 2；对于 PutFile 会自动计算 crc32 值 198 | // checkCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 crc32 变量 199 | } 200 | 201 | class Key(Object): 202 | 203 | ... ... 204 | 205 | def put(self, body, extra=None, uptoken=None): pass 206 | 207 | def put_file(self, load_file, extra=None, uptoken=None): pass 208 | 209 | def download_url(self, expires=3600): pass 210 | 211 | Bucket("foo").key("bar").put(body, extra, uptoken) 212 | Bucket("foo").key("bar").put(load_file, extra, uptoken) 213 | Bucket("foo").key("bar").download_url(expires) 214 | ``` 215 | 216 | 数据处理API（fop） 217 | 218 | ```{python} 219 | 220 | // imageView 221 | imageView = { 222 | 'mode': mode, // 缩略模式 223 | 'width': width, // Width = 0 表示不限定宽度 224 | 'height': height, // Height = 0 表示不限定高度 225 | 'quality': quality, // 质量, 1-100 226 | 'format': format // 输出格式，如jpg, gif, png, tif等等 227 | } 228 | 229 | // imageMogr 230 | imageMogr = { 231 | ... 232 | } 233 | 234 | class Key(Object): 235 | 236 | ... ... 237 | 238 | def image_info_url(self): pass 239 | 240 | def image_info_call(self, image_info_url=None): pass 241 | 242 | def exif_url(self): pass 243 | 244 | def exif_call(self, exif_url=None): pass 245 | 246 | def qrcode_url(self): pass 247 | 248 | def image_view_url(self, image_view): pass 249 | 250 | def image_mogr_url(self, image_mogr): pass 251 | 252 | Bucket("foo").key("bar").image_view_url() 253 | Bucket("foo").key("bar").image_mogr_url() 254 | ``` 255 | -------------------------------------------------------------------------------- /ruby/README.md: -------------------------------------------------------------------------------- 1 | # Qiniu Cloud Storage SDK Specification 2 | 3 | [![Qiniu Logo](http://qiniutek.com/images/logo-2.png)](http://qiniu.com/) 4 | 5 | ## 语言差异性 6 | 7 | - 命名风格：不同语言可以有不同的命名风格。本规范主要按类 Golang 风格进行描述（但不完全是）。 8 | - 名字空间：有的语言没有 package（namespace），通常通过名字前缀来表达。 9 | - 构造函数：有的语言没有构造函数，通过 NewXXX 函数来表达。本规范因为按 Golang 风格，构造函数也是用 NewXXX 进行描述。 10 | - 函数重载：有的语言没有函数重载，通过 XXXYYY 形式命名，其中 XXX 是功能，YYY 是不同重载函数的区分段。支持函数重载的语言没有 YYY 段。 11 | - 函数多返回值：有的语言不支持返回多个返回值，也不支持返回元组（tuple）。 12 | 13 | 14 | ## 服务端配置（conf） 15 | 16 | ```{go} 17 | package "qiniu/api/conf" 18 | 19 | var USER_AGENT string // 请求的 User-Agent 值，比如 "qiniu php-sdk v6.0.0" 20 | 21 | var UP_HOST string 22 | var RS_HOST string 23 | var RSF_HOST string 24 | 25 | var ACCESS_KEY string 26 | var SECRET_KEY string // 不要在客户端初始化该变量 27 | ``` 28 | 29 | 范围：服务端和客户端共用 30 | 31 | 32 | ## 签名认证（auth/digest） 33 | 34 | ```{go} 35 | package "qiniu/api/auth/digest" 36 | 37 | type Mac struct { 38 | AccessKey string 39 | SecretKey []byte 40 | } 41 | ``` 42 | 43 | 范围：仅在服务端使用 44 | 45 | 46 | ## 存储API（rs） 47 | 48 | ```{go} 49 | package "qiniu/api/rs" 50 | 51 | type Client struct { 52 | ... 53 | } 54 | 55 | func New(mac *digest.Mac = nil) Client 56 | 57 | func (this Client) Stat(bucket, key string) (entry Entry, err error) 58 | func (this Client) Delete(bucket, key string) (err error) 59 | func (this Client) Move(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 60 | func (this Client) Copy(bucketSrc, keySrc, bucketDest, keyDest string) (err error) 61 | 62 | type Entry struct { 63 | Hash string 64 | Fsize int64 65 | PutTime int64 66 | MimeType string 67 | EndUser string 68 | } 69 | 70 | // batch 71 | 72 | type EntryPath struct { 73 | Bucket string 74 | Key string 75 | } 76 | 77 | type EntryPathPair struct { 78 | Src EntryPath 79 | Dest EntryPath 80 | } 81 | 82 | type BatchItemRet struct { 83 | Error string 84 | Code int 85 | } 86 | 87 | type BatchStatItemRet struct { 88 | Data Entry 89 | Error string 90 | Code int 91 | } 92 | 93 | func (this Client) BatchStat(entries []EntryPath) (rets []BatchStatItemRet, err error) 94 | func (this Client) BatchDelete(entries []EntryPath) (rets []BatchItemRet, err error) 95 | func (this Client) BatchMove(entries []EntryPathPair) (rets []BatchItemRet, err error) 96 | func (this Client) BatchCopy(entries []EntryPathPair) (rets []BatchItemRet, err error) 97 | ``` 98 | 99 | 范围：仅在服务端使用 100 | 101 | 102 | ## 上传/下载授权凭证（uptoken/dntoken） 103 | 104 | ```{go} 105 | package "qiniu/api/rs" 106 | 107 | type PutPolicy struct { 108 | Scope string // 必选。可以是 bucketName 或者 bucketName:key 109 | CallbackUrl string // 可选 110 | CallbackBody string // 可选 111 | ReturnUrl string // 可选 112 | ReturnBody string // 可选 113 | AsyncOps string // 可选 114 | EndUser string // 可选 115 | Expires uint32 // 可选。默认是 3600 秒 116 | } 117 | 118 | func (this *PutPolicy) Token(mac *digest.Mac = nil) (uptoken string) 119 | 120 | type GetPolicy struct { 121 | Expires uint32 // 可选。默认是 3600 秒 122 | } 123 | 124 | func (this GetPolicy) MakeRequest(baseUrl string, mac *digest.Mac = nil) (privateUrl string) 125 | 126 | func MakeBaseUrl(domain, key string) (baseUrl string) 127 | ``` 128 | 129 | 范围：仅在服务端使用 130 | 131 | 132 | ## 存储高级API（rsf） 133 | 134 | ```{go} 135 | package "qiniu/api/rsf" 136 | 137 | type Client struct { 138 | ... 139 | } 140 | 141 | func New(mac *digest.Mac = nil) Client 142 | 143 | func (this Client) ListPrefix( 144 | bucket, prefix, marker string, limit int) (entries []ListItem, markerOut string, err error) 145 | 146 | type ListItem struct { 147 | Key string 148 | Hash string 149 | Fsize int64 150 | PutTime int64 151 | MimeType string 152 | EndUser string 153 | } 154 | ``` 155 | 156 | 范围：仅在服务端使用 157 | 158 | 159 | ## 上传（io） 160 | 161 | ```{go} 162 | package "qiniu/api/io" 163 | 164 | // upload 165 | 166 | const UNDEFINED_KEY = "?" 167 | 168 | type PutExtra struct { 169 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 170 | MimeType string // 可选 171 | Crc32 uint32 172 | CheckCrc uint32 173 | // CheckCrc == 0: 表示不进行 crc32 校验 174 | // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值 175 | // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量 176 | } 177 | 178 | type PutRet struct { 179 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 180 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 181 | } 182 | 183 | func Put( 184 | ret interface{}, uptoken string, key string, body io.Reader, extra *PutExtra) (err error) 185 | 186 | func PutFile( 187 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 188 | ``` 189 | 190 | 范围：客户端和服务端 191 | 192 | 193 | ## 断点续上传（resumable io） 194 | 195 | ```{go} 196 | package "qiniu/api/resumable/io" 197 | 198 | // upload 199 | 200 | const UNDEFINED_KEY = "?" 201 | 202 | type BlkputRet struct { 203 | Ctx string `json:"ctx"` 204 | Checksum string `json:"checksum"` 205 | Crc32 uint32 `json:"crc32"` 206 | Offset uint32 `json:"offset"` 207 | } 208 | 209 | type PutExtra struct { 210 | Params map[string]string // 用户自定义参数，key必须以 "x:" 开头 211 | MimeType string 212 | ChunkSize int // 可选。每次上传的Chunk大小 213 | TryTimes int // 可选。尝试次数 214 | Progresses []BlkputRet // 可选。上传进度 215 | Notify func(blkIdx int, blkSize int, ret *BlkputRet) // 进度提示。注意blk是并行传输的 216 | NotifyErr func(blkIdx int, blkSize int, err error) 217 | } 218 | 219 | type PutRet struct { 220 | Hash string // 如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构 221 | Key string // 如果传入的 key == UNDEFINED_KEY，则服务端返回 key 222 | } 223 | 224 | func Put( 225 | ret interface{}, uptoken string, 226 | key string, f io.ReaderAt, fsize int64, extra *PutExtra) (err error) 227 | 228 | func PutFile( 229 | ret interface{}, uptoken string, key string, localFile string, extra *PutExtra) (err error) 230 | 231 | func BlockCount(fsize int64) int 232 | 233 | // global settings 234 | 235 | type Settings { 236 | TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4。 237 | Workers int // 并行的工作线程数目。 238 | ChunkSize int // 默认的Chunk大小，不设定则为256k 239 | TryTimes int // 默认的尝试次数，不设定则为3 240 | } 241 | 242 | func SetSettings(settings *Settings) 243 | ``` 244 | 245 | 范围：客户端和服务端 246 | 247 | 248 | ## 数据处理API（fop） 249 | 250 | ```{go} 251 | package "qiniu/api/fop" 252 | 253 | // imageView 254 | 255 | type ImageView struct { 256 | Mode int // 缩略模式 257 | Width int // Width = 0 表示不限定宽度 258 | Height int // Height = 0 表示不限定高度 259 | Quality int // 质量, 1-100 260 | Format string // 输出格式，如jpg, gif, png, tif等等 261 | } 262 | 263 | func (this *ImageView) MakeRequest(url string) (imageViewUrl string) 264 | 265 | // imageMogr 266 | 267 | type ImageMogrify struct { 268 | ... // 待标准化 269 | } 270 | 271 | func (this *ImageMogrify) MakeRequest(url string) (imageMogrUrl string) 272 | 273 | // imageInfo 274 | 275 | type ImageInfoRet struct { 276 | Width int 277 | Height int 278 | Format string 279 | ColorModel string 280 | } 281 | 282 | type ImageInfo struct {} 283 | 284 | func (this ImageInfo) MakeRequest(url string) (imageInfoUrl string) 285 | func (this ImageInfo) Call(url string) (ret ImageInfoRet, err error) 286 | 287 | // exif 288 | 289 | type ExifValType struct { 290 | Val string 291 | Type int 292 | } 293 | 294 | type ExifRet map[string] ExifValType 295 | type Exif struct {} 296 | 297 | func (this Exif) MakeRequest(url string) (imageExifUrl string) 298 | func (this Exif) Call(url string) (ret ExifRet, err error) 299 | ``` 300 | 301 | 范围：客户端和服务端 302 | 303 | --------------------------------------------------------------------------------