diff --git a/docs/v6/api/overview/rs/rs.md b/docs/v6/api/overview/rs/rs.md index 82b9830d..44f992fb 100644 --- a/docs/v6/api/overview/rs/rs.md +++ b/docs/v6/api/overview/rs/rs.md @@ -23,46 +23,46 @@ order: 298 ## 查看资源信息 (stat) -查看资源信息操作查看的基本信息,包含:文件哈希值、文件大小、媒体类型及上传时间。具体参考[查看资源信息(stat)](/docs/v6/api/reference/rs/stat.html)。 +查看资源信息操作查看的基本信息,包含:文件哈希值、文件大小、媒体类型及上传时间。具体参考[查看资源信息(stat)](/docs/v6/api/reference/rs/stat.html)和[多区域查看资源信息(glb-stat)](/docs/v6/api/reference/glb-rs/stat.html)。 ## 移动资源 (move) -移动资源操作允许将一个资源在同一个Bucket或者不同的Bucket之间移动。例如,在bucket1下面有一个名为key1的资源,可以将这个资源key1移动到bucket1下面的key2,也可以将其移动到bucket2下的key2。通过移动操作可以实现文件重命名。具体参考[移动资源(move)](/docs/v6/api/reference/rs/move.html)。 +移动资源操作允许将一个资源在同一个Bucket或者不同的Bucket之间移动。例如,在bucket1下面有一个名为key1的资源,可以将这个资源key1移动到bucket1下面的key2,也可以将其移动到bucket2下的key2。通过移动操作可以实现文件重命名。具体参考[移动资源(move)](/docs/v6/api/reference/rs/move.html)和[多区域移动资源(glb/move)](/docs/v6/api/reference/glb-rs/move.html)。 ## 复制资源 (copy) -复制资源操作操作允许在同一个bucket进行,也可以在两个不同的bucket之间进行。与资源的移动操作相比,复制资源操作保留原文件,因此会增加用户的存储空间。具体参考[复制资源(copy)](/docs/v6/api/reference/rs/copy.html)。 +复制资源操作操作允许在同一个bucket进行,也可以在两个不同的bucket之间进行。与资源的移动操作相比,复制资源操作保留原文件,因此会增加用户的存储空间。具体参考[复制资源(copy)](/docs/v6/api/reference/rs/copy.html)和[多区域复制资源(glb/copy)](/docs/v6/api/reference/glb-rs/copy.html)。 ## 删除资源 (delete) -删除资源与删除文件类似,但是七牛云存储不提供回收站的功能,因此在删除前请确认待删除的资源确实不再需要。具体参考[删除资源(delete)](/docs/v6/api/reference/rs/delete.html)。 +删除资源与删除文件类似,但是七牛云存储不提供回收站的功能,因此在删除前请确认待删除的资源确实不再需要。具体参考[删除资源(delete)](/docs/v6/api/reference/rs/delete.html)和[多区域删除资源(glb/delete)](/docs/v6/api/reference/glb-rs/delete.html)。 ## 抓取资源 (fetch) -抓取资源操作用于从指定的URL抓取资源,并将该资源存储到指定空间中。具体参考[抓取资源(fetch)](/docs/v6/api/reference/rs/fetch.html)。 +抓取资源操作用于从指定的URL抓取资源,并将该资源存储到指定空间中。具体参考[抓取资源(fetch)](/docs/v6/api/reference/rs/fetch.html)和[多区域抓取资源(glb/fetch)](/docs/v6/api/reference/glb-rs/fetch.html)。 ## 列举资源 (list) -列举资源操作用于将指定空间内的资源分批列出。具体参考[列举资源(list)](/docs/v6/api/reference/rs/list.html)。 +列举资源操作用于将指定空间内的资源分批列出。具体参考[列举资源(list)](/docs/v6/api/reference/rs/list.html)和[多区域列举资源(glb/list)](/docs/v6/api/reference/glb-rs/list.html)。 ## 批量操作 (batch) -除了对单一资源进行操作,还可以在一次请求中对多个资源进行批量的查看、移动、复制及删除操作。具体参考[批量操作(batch)](/docs/v6/api/reference/rs/batch.html)。 +除了对单一资源进行操作,还可以在一次请求中对多个资源进行批量的查看、移动、复制及删除操作。具体参考[批量操作(batch)](/docs/v6/api/reference/rs/batch.html)和[多区域批量操作(glb/batch)](/docs/v6/api/reference/glb-rs/batch.html)。 ## 修改元信息 (chgm) -修改元信息操作用于修改资源的mimeType,可以在七牛服务器自动识别文件类型错误或者是类型描述不够详细的情况下,自定义的对空间已有资源的类型进行修改。具体参考[修改元信息 (chgm) ](/docs/v6/api/reference/rs/chgm.html)。 +修改元信息操作用于修改资源的mimeType,可以在七牛服务器自动识别文件类型错误或者是类型描述不够详细的情况下,自定义的对空间已有资源的类型进行修改。具体参考[修改元信息 (chgm) ](/docs/v6/api/reference/rs/chgm.html)和[多区域修改元信息 (glb/chgm) ](/docs/v6/api/reference/glb-rs/chgm.html)。 ## 更新镜像资源(prefetch) -对于设置了镜像存储的空间,从镜像源站抓取指定名称的资源并存储到该空间中。如果该空间中已存在该名称的资源,则将镜像源站的资源覆盖空间的资源。具体参考[更新镜像资源(prefetch)](/docs/v6/api/reference/rs/prefetch.html)。 +对于设置了镜像存储的空间,从镜像源站抓取指定名称的资源并存储到该空间中。如果该空间中已存在该名称的资源,则将镜像源站的资源覆盖空间的资源。具体参考[更新镜像资源(prefetch)](/docs/v6/api/reference/rs/prefetch.html)和[多区域更新镜像资源(glb/prefetch)](/docs/v6/api/reference/glb-rs/prefetch.html)。 diff --git a/docs/v6/api/overview/up/upload-models/upload-types.md b/docs/v6/api/overview/up/upload-models/upload-types.md index a18bb8de..528538c0 100755 --- a/docs/v6/api/overview/up/upload-models/upload-types.md +++ b/docs/v6/api/overview/up/upload-models/upload-types.md @@ -136,7 +136,7 @@ Content-Type: ### 基本流程 -与分片上传相关的API有这几个:[创建块(mkblk)][mkblkHref]、[上传片(bput)][bputHref]、[创建资源(mkfile)][mkfileHref]。一个完整的分片上传流程可用下图表示: +与分片上传相关的API有这几个:[创建块(mkblk)][mkblkHref]、[上传片(bput)][bputHref]、[创建资源(mkfile)][mkfileHref]。多区域分片上传的API有:[多区域创建块(glb/mkblk)][glb-mkblkHref]、[多区域上传片(glb/bput)][glb-bputHref]、[多区域创建资源(glb/mkfile)][glb-mkfileHref]。一个完整的分片上传流程可用下图表示: ![分片上传流程](img/chunked-upload-workflow.png) @@ -182,6 +182,9 @@ Content-Type: [mkblkHref]: /docs/v6/api/reference/up/mkblk.html "创建块" [bputHref]: /docs/v6/api/reference/up/bput.html "上传片" [mkfileHref]: /docs/v6/api/reference/up/mkfile.html "创建资源" +[glb-mkblkHref]: /docs/v6/api/reference/glb-up/mkblk.html "多区域创建块" +[glb-bputHref]: /docs/v6/api/reference/glb-up/bput.html "多区域上传片" +[glb-mkfileHref]: /docs/v6/api/reference/glb-up/mkfile.html "多区域创建资源" [uploadTokenHref]: /docs/v6/api/reference/security/upload-token.html "上传凭证" [varsHref]: /docs/v6/api/overview/up/response/vars.html "变量" diff --git a/docs/v6/api/reference/codes.md b/docs/v6/api/reference/codes.md index 8d8bb892..85dc1692 100644 --- a/docs/v6/api/reference/codes.md +++ b/docs/v6/api/reference/codes.md @@ -27,7 +27,7 @@ HTTP状态码 | 说明 614 | 目标资源已存在。 630 | 已创建的空间数量达到上限,无法创建新空间。 631 | 指定空间不存在。 -640 | 调用[列举资源(list)](/docs/v6/api/reference/rs/list.html)接口时,指定非法的`marker`参数。 +640 | 调用[列举资源(list)](/docs/v6/api/reference/rs/list.html)和[多区域列举资源(glb/list)](/docs/v6/api/reference/glb-rs/list.html)接口时,指定非法的`marker`参数。 701 | 在断点续上传过程中,后续上传接收地址不正确或ctx信息已过期。 如遇5xx系列错误,请将完整的错误信息(包括所有的HTTP响应头部)[通过邮件发送](mailto:support@qiniu.com?subject=5xx错误日志)给我们。情况严重时请直接拨打400-808-9176转2上报给运维部,我们将尽快处理。 diff --git a/docs/v6/api/reference/data-formats.md b/docs/v6/api/reference/data-formats.md index 1bc6eda0..d7dfece9 100644 --- a/docs/v6/api/reference/data-formats.md +++ b/docs/v6/api/reference/data-formats.md @@ -20,6 +20,7 @@ encodedEntryURI = urlsafe_base64_encode(entry) ``` 假设entry为`qiniuphotos:gogopher.jpg`,则对应的encodedEntryURI为`cWluaXVwaG90b3M6Z29nb3BoZXIuanBn`。 +假设一个多区域entry为`qiniuphotos:z1/gogopher.jpg`,则对应的encodedEntryURI为`cWluaXVwaG90b3M6ejEvZ29nb3BoZXIuanBn`。 ## 内部参考资源 diff --git a/docs/v6/api/reference/glb-rs/batch.md b/docs/v6/api/reference/glb-rs/batch.md new file mode 100644 index 00000000..b4c35085 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/batch.md @@ -0,0 +1,211 @@ +--- +title: 批量操作(batch) +order: 500 +--- + + +# 多区域批量操作(glb/batch) + +- [描述](#batch-description) +- [请求](#batch-request) + - [请求语法](#batch-request-syntax) + - [访问权限](#batch-request-auth) + - [请求参数](#batch-request-params) + - [头部信息](#batch-request-headers) + - [请求内容](#batch-request-body) +- [响应](#batch-response) + - [响应语法](#batch-response-headers) + - [头部信息](#batch-response-headers) + - [响应内容](#batch-response-body) + - [响应状态码](#batch-response-batchus) +- [附注](#batch-remarks) +- [相关资源](#batch-related-resources) + + +## 描述 + +批量操作意指在单一请求中执行多次获取元信息/移动/复制/删除操作,极大提高资源管理效率。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/batch HTTP/1.1 +Host: rs.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox + +op=&op=&... +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + +其中`op=`是单一资源操作指令。例如`/stat/`,`/delete/`等。 +EncodeEntryURI、EncodedEntryURISrc与EncodedEntryURIDest的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Content-Type | 是 | 固定为application/x-www-form-urlencoded +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +#### 批量获取元信息 + +``` +op=/glb/stat/&op=/stat/&... +``` + +#### 批量复制资源 + +``` +op=/glb/copy//&op=/glb/copy//&... +``` + +#### 批量移动资源 + +``` +op=/glb/move//&op=/glb/move//&... +``` + +#### 批量删除资源 + +``` +op=/glb/delete/&op=/glb/delete/&... +``` + +#### 混合多种操作 + +``` +op=/glb/stat/ +&op=/glb/copy// +&op=/glb/move//&... +&op=/glb/delete/&... +``` + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +#### 批量获取元信息 + +``` +[ + { "code": , "data": }, + { "code": , "data": }, + { "code": , "data": { "error": "" } }, + ... +] +``` + +#### 批量复制资源 + +``` +[ + { "code": }, + { "code": }, + { "code": , "data": { "error": "" } }, + ... +] +``` + +#### 批量移动资源 + +``` +[ + { "code": }, + { "code": }, + { "code": , "data": { "error": "" } }, + ... +] +``` + +#### 批量删除资源 + +``` +[ + { "code": }, + { "code": }, + { "code": , "data": { "error": "" } }, + ... +] +``` + +#### 混合多种操作 + +``` +[ + { "code": , "data": }, + { "code": }, + { "code": }, + { "code": }, + { "code": , "data": { "error": "" } }, + ... +] +``` + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 所有请求操作都已成功完成 +298 | 部分或所有请求操作失败(出错信息参看上述响应内容) +400 | 请求报文格式错误 +401 | 管理凭证无效 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 + + +## 附注 + +无。 + + +## 相关资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-rs/chgm.md b/docs/v6/api/reference/glb-rs/chgm.md new file mode 100644 index 00000000..d6efb4bf --- /dev/null +++ b/docs/v6/api/reference/glb-rs/chgm.md @@ -0,0 +1,187 @@ +--- +layout: docs +title: 多区域修改元信息(chgm) +order: 499 +--- + + +# 多区域修改元信息(glb/chgm) + +- [描述](#chgm-description) +- [请求](#chgm-request) + - [请求语法](#chgm-request-syntax) + - [访问权限](#chgm-request-auth) + - [请求参数](#chgm-request-params) + - [头部信息](#chgm-request-headers) + - [请求内容](#chgm-request-body) +- [响应](#chgm-response) + - [响应语法](#chgm-response-syntax) + - [头部信息](#chgm-response-headers) + - [响应内容](#chgm-response-body) + - [响应状态码](#chgm-response-status) +- [示例](#chgm-samples) + - [命令行示例](#chgm-sample1-command) + - [请求示例](#chgm-sample1-request) + - [响应示例](#chgm-sample1-response) +- [附注](#chgm-remarks) +- [内部参考资源](#chgm-internal-resources) + + + +## 描述 + +主动修改指定资源的文件类型,也就是资源的[mimeType](http://www.iana.org/assignments/media-types/media-types.xhtml)。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/chgm//mime/ HTTP/1.1 +Host: rs.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedEntryURI和EncodedMimeType的细节请查看[EncodedEntryURI格式][encodedEntryURIHref],而EncodedMimeType编码前的明文为要设置的新mimeType。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox bt500PzCG9tV0bccCOdnrmC...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +### mimeType命名规则 +* 目前所有的`mimetype`包括如下字符集:a-z, A-Z, 0-9, ., +, /, - +* 因为`mimetype`日后还会增加,为保证兼容将来的增加如下字符“;=,_”和空格 +* 目前`mimetype`最大长度为79, 为保证兼容将来的这里限制最大长度为200 +* `mimetype`为空这里认为合法,因为如果为空后面会进一步检测并设置 +* `mimetype`可以包括空格,例如:“text/plain; charset=iso-8859-1” +* 禁止转义,如"%0A"表示"\n",所以禁止出现"%" + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,不返回任何内容。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "" +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 更改成功 +400 | 请求报文格式错误
当``解析失败,返回400 Bad Request {"error":"invalid argument"}
当``不符合UTF-8编码,返回400 Bad Request {"error":"key must be utf8 encoding"} +401 | 管理凭证无效 +612 | 目标资源不存在 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 + + +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox bt500PzCG9tV0bccCOdnrmCHPXCPLieGSDEprB7M:4wG...' \ + -X POST \ + 'http://rs.qiniu.com/glb/chgm/aXRpc2F0ZXN0OmdvZ29waGVyLmpwZw==/mime/YXBwbGljYXRpb24vdGVzdA==' +``` + + +### 请求示例 + +``` +POST /glb/chgm/aXRpc2F0ZXN0OmdvZ29waGVyLmpwZw==/mime/YXBwbGljYXRpb24vdGVzdA== HTTP/1.1 +User-Agent: curl/7.30.0 +Host: rs.qiniu.com +Accept: */* +Authorization: QBox bt500PzCG9tV0bccCOdnrmCHPXCPLieGSDEprB7M:4wG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.4.4 +Date: Wed, 17 Sep 2014 07:53:25 GMT +Content-Type: application/json +Content-Length: 0 +Connection: keep-alive +X-Log: rs7_3.chgm;MQ;mc.d:1;RS:3 +X-Reqid: vDEAAG2lN7zSqpQT +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-rs/copy.md b/docs/v6/api/reference/glb-rs/copy.md new file mode 100644 index 00000000..f569539d --- /dev/null +++ b/docs/v6/api/reference/glb-rs/copy.md @@ -0,0 +1,176 @@ +--- +layout: docs +title: 复制(copy) +order: 700 +--- + + +# 多区域复制资源(glb/copy) + +- [描述](#copy-description) +- [请求](#copy-request) + - [请求语法](#copy-request-syntax) + - [访问权限](#copy-request-auth) + - [请求参数](#copy-request-params) + - [头部信息](#copy-request-headers) + - [请求内容](#copy-request-body) +- [响应](#copy-response) + - [响应语法](#copy-response-syntax) + - [头部信息](#copy-response-headers) + - [响应内容](#copy-response-body) + - [响应状态码](#copy-response-copyus) +- [示例](#copy-samples) + - [命令行示例](#copy-sample1-command) + - [请求示例](#copy-sample1-request) + - [响应示例](#copy-sample1-response) +- [附注](#copy-remarks) +- [内部参考资源](#copy-internal-resources) + + +## 描述 + +将指定资源复制为新命名资源。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/copy// HTTP/1.1 +Host: rs.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedEntryURISrc与EncodedEntryURIDest的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + + +### 响应内容 + +■ 如果请求成功,不返回任何内容。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`code` | 是 | HTTP状态码,请参考[响应状态](#copy-response-copyus) +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 复制成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +612 | 待复制资源不存在 +614 | 目标资源已存在 + + +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...' \ + -X POST \ + 'http://rs.qiniu.com/glb/copy/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ=' +``` + + +### 请求示例 + +``` +POST /glb/copy/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1 +User-Agent: curl/7.30.0 +Host: rs.qiniu.com +Accept: */* +Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Thu, 05 Dec 2013 06:55:29 GMT +Content-Type: application/json +Connection: keep-alive +Content-Length: 0 +X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5 +X-Reqid: wxIAAD3btw-v3TwT +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" diff --git a/docs/v6/api/reference/glb-rs/delete.md b/docs/v6/api/reference/glb-rs/delete.md new file mode 100644 index 00000000..2f401089 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/delete.md @@ -0,0 +1,177 @@ +--- +layout: docs +title: 删除(delete) +order: 600 +--- + + +# 多区域删除资源(glb/delete) + +- [描述](#delete-description) +- [请求](#delete-request) + - [请求语法](#delete-request-syntax) + - [访问权限](#delete-request-auth) + - [请求参数](#delete-request-params) + - [头部信息](#delete-request-headers) + - [请求内容](#delete-request-body) +- [响应](#delete-response) + - [响应语法](#delete-response-syntax) + - [头部信息](#delete-response-headers) + - [响应内容](#delete-response-body) + - [响应状态码](#delete-response-status) +- [示例](#delete-samples) + - [命令行示例](#delete-example1-command) + - [请求示例](#delete-example1-request) + - [响应示例](#delete-example1-response) +- [附注](#delete-remarks) +- [内部参考资源](#delete-internal-resources) + + +## 描述 + +删除指定资源。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/delete/ HTTP/1.1 +Host: rs.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedEntryURI的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,不返回任何内容。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 删除成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +612 | 待删除资源不存在 + + +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...' \ + -X POST \ + 'http://rs.qiniu.com/glb/delete/bmV3ZG9jczpmaW5kX21hbi50eHQ=' +``` + + +### 请求示例 + +``` +POST /glb/delete/bmV3ZG9jczpmaW5kX21hbi50eHQ= HTTP/1.1 +User-Agent: curl/7.30.0 +Host: rs.qiniu.com +Accept: */* +Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Thu, 05 Dec 2013 06:55:29 GMT +Content-Type: application/json +Connection: keep-alive +Content-Length: 0 +X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5 +X-Reqid: wxIAAD3btw-v3TwT +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-rs/fetch.md b/docs/v6/api/reference/glb-rs/fetch.md new file mode 100644 index 00000000..e0936a17 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/fetch.md @@ -0,0 +1,185 @@ +--- +layout: docs +title: 抓取(fetch) +order: 599 +--- + + +# 多区域抓取资源(glb/fetch) + +- [描述](#fetch-description) +- [请求](#fetch-request) + - [请求语法](#fetch-request-syntax) + - [访问权限](#fetch-request-auth) + - [请求参数](#fetch-request-params) + - [头部信息](#fetch-request-headers) + - [请求内容](#fetch-request-body) +- [响应](#fetch-response) + - [响应语法](#fetch-response-headers) + - [头部信息](#fetch-response-headers) + - [响应内容](#fetch-response-body) + - [响应状态码](#fetch-response-fetchus) +- [示例](#fetch-samples) + - [命令行示例](#fetch-sample1-command) + - [请求示例](#fetch-sample1-request) + - [响应示例](#fetch-sample1-response) +- [附注](#fetch-remarks) +- [内部参考资源](#fetch-internal-resources) + + +## 描述 + +从指定URL抓取资源,并将该资源存储到指定空间中。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/fetch//to/ HTTP/1.1 +Host: api.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedURL参数为对指定URL地址进行[URL安全的Base64编码][urlsafeBase64Href]后的字符串,[EncodedEntryURI][encodedEntryURIHref]为 `:` 或者 `` 的 urlsafe base64 编码。如果指定为``的 urlsafe base64 编码,默认文件的[hash][qetag]值作为key。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "hash": "", + "key": "" +} +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +- 如果请求成功,返回文件的[hash][qetag]值和key。 +- 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 抓取成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +404 | 抓取资源不存在 +478 | 源站返回404外,所有非200的response都返回478 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +其余状态码 | 源站返回的状态码,请检查源站资源的可访问性 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...' \ + -X POST \ + 'http://api.qiniu.com/glb/fetch/aHR0cDovL3Fpbml1LmNvbS9pbmRleC5odG1s/to/bmV3ZG9jczpmaW5kLm1hbi50eHQ=' +``` + + +### 请求示例 + +``` +POST /glb/fetch/aHR0cDovL3Fpbml1LmNvbS9pbmRleC5odG1s/to/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1 +User-Agent: curl/7.30.0 +Host: api.qiniu.com +Accept: */* +Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Thu, 05 Dec 2013 06:55:29 GMT +Content-Type: application/json +Connection: keep-alive +Content-Length: 0 +X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5 +X-Reqid: wxIAAD3btw-v3TwT +``` + + +## 附注 + +- 本接口执行同步操作,如果抓取的资源过大,可能会导致超时。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] +- [URL安全的Base64编码][urlsafeBase64Href] +- [七牛etag算法][qetag] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" + +[urlsafeBase64Href]: http://developer.qiniu.com/docs/v6/api/overview/appendix.html#urlsafe-base64 "URL安全的Base64编码" +[qetag]: http://developer.qiniu.com/docs/v6/api/overview/appendix.html "文件etag算法" diff --git a/docs/v6/api/reference/glb-rs/index.md b/docs/v6/api/reference/glb-rs/index.md new file mode 100644 index 00000000..07f88607 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/index.md @@ -0,0 +1,31 @@ +--- +layout: docs +title: 多区域资源管理 +order: 600 +--- + + +# 多区域资源管理 + +本节描述资源管理相关的接口规格,涵盖以下内容: + +* [多区域查看(glb/stat)][statHref] +* [多区域移动(glb/move)][moveHref] +* [多区域复制(glb/copy)][copyHref] +* [多区域删除(glb/delete)][deleteHref] +* [多区域抓取(glb/fetch)][fetchHref] +* [多区域列举(glb/list)][listHref] +* [多区域批量操作(glb/batch)][batchHref] +* [多区域修改元信息(glb/chgm)][chgmHref] +* [多区域更新镜像资源(glb/prefetch)][prefetchHref] + +[statHref]: stat.html "多区域查看资源信息" +[copyHref]: copy.html "多区域复制资源" +[moveHref]: move.html "多区域移动资源" +[deleteHref]: delete.html "多区域删除资源" +[batchHref]: batch.html "多区域批量操作" + +[fetchHref]: fetch.html "多区域抓取资源" +[listHref]: list.html "多区域列举资源" +[prefetchHref]: prefetch.html "多区域更新镜像资源" +[chgmHref]: chgm.html "多区域修改元信息" diff --git a/docs/v6/api/reference/glb-rs/list.md b/docs/v6/api/reference/glb-rs/list.md new file mode 100644 index 00000000..9d608843 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/list.md @@ -0,0 +1,229 @@ +--- +layout: docs +title: 列举(list) +order: 598 +--- + + +# 多区域列举资源(glb/list) + +- [描述](#list-description) +- [接口规格](#list-description) +- [请求](#list-request) + - [请求报文格式](#list-request-syntax) + - [访问权限](#list-request-auth) + - [头部信息](#list-request-headers) + - [请求内容](#list-request-body) +- [响应](#list-response) + - [响应报文格式](#list-response-headers) + - [头部信息](#list-response-headers) + - [响应内容](#list-response-body) + - [响应状态码](#list-response-status) +- [示例](#list-samples) +- [附注](#list-remarks) +- [内部参考资源](#list-internal-resources) +- [外部参考资源](#list-external-resources) + + +## 描述 + +本接口用于将指定空间内的资源分批列出。 + + +## 接口规格 + +``` +bucket=&marker=&limit=&prefix=&delimiter= +``` + +参数名称 | 必填 | 说明 +:---------- | :--- | :----------------------------- +`bucket` | 是 | 指定空间。 +`limit` | | 本次列举的条目数,范围为1-1000。

缺省值为1000。 +`prefix` | | 指定前缀,只有资源名匹配该前缀的资源会被列出。

缺省值为空字符串。 +`delimiter` | | 指定目录分隔符,列出所有公共前缀(模拟列出目录效果)。

缺省值为空字符串。 +`marker` | | 上一次列举返回的位置标记,作为本次列举的起点信息。

缺省值为空字符串。 + + +## 请求 + + +### 请求报文格式 + +``` +POST /glb/list? HTTP/1.1 +Host: rsf.qbox.me +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 头部信息 + +该请求必须指定以下头部信息。 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Host | 是 | 管理服务器域名,固定为`rsf.qbox.me`。 +Content-Type | 是 | 请求内容MIME类型,固定为`application/x-www-form-urlencoded`。 +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码。

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...`。 + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应报文格式 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 说明 +:------------ | :-------------------------------------------------------------------- +Content-Type | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "marker": "", + "commonPrefixes": [ + "xxx", + "yyy" + ], + "items": [ + { + "key": "", + "putTime": , + "hash": "", + "fsize": , + "mimeType": "", + "customer": "" + }, + ... + ] +} +``` + +字段名称 | 必填 | 说明 +:--------------- | :--- | :------------------------------------------------------------------------------------ +`marker` | | 有剩余条目则返回非空字符串,作为下一次列举的参数传入。

如果没有剩余条目则返回空字符串。 +`commonPrefixes` | | 所有目录名的数组,如没有指定`delimiter`参数则不输出。 +`items` | 是 | 所有返回条目的数组,如没有剩余条目则为空数组。 + `key` | 是 | 资源名。 + `putTime` | 是 | 上传时间,单位:100纳秒,其值去掉低七位即为[Unix时间][unixTimeHref]。 + `fsize` | 是 | 资源内容的大小,单位:字节。 + `hash` | 是 | 资源内容的[ETag](http://developer.qiniu.com/docs/v6/api/overview/appendix.html#qiniu-etag)值。 + `mimeType` | 是 | 资源内容的MIME类型。 + `customer` | | 资源内容的唯一属主标识,请参考[上传策略][putPolicyHref]。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本。 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 列举成功。 +400 | 请求报文格式错误。 +401 | 管理凭证无效。 +599 | 服务端操作失败。

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。 + + + +## 示例 + +1. 列出所有`00`打头的资源: + +``` +接口规格 +bucket=qiniu-ts-demo&prefix=00 + +返回结果 +{"items"=>[{"key"=>"00000001.txt", "hash"=>"Fi2XEahn6IfmwBLwvXb0HGowjyym", "fsize"=>93966, "mimeType"=>"text/plain", "putTime"=>13993416549476933}, {"key"=>"00000002.txt", "hash"=>"Foiz8WAEOgOo8B-lyYegCHcl6VSb", "fsize"=>172422, "mimeType"=>"text/plain", "putTime"=>13993416551051809}, {"key"=>"00000003.txt", "hash"=>"FgsZJh9ACX9-tz2PWjKfFpURlXU2", "fsize"=>175778, "mimeType"=>"text/plain", "putTime"=>13993416553903813}, ...更多内容已省略...]} +``` + +2. 列出所有`00`打头的资源,每批2个: + +``` +接口规格 +bucket=qiniu-ts-demo&prefix=00&limit=2 + +返回结果 +{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwMDIuRENNIn0=", "items"=>[{"key"=>"00000001.txt", "hash"=>"Fi2XEahn6IfmwBLwvXb0HGowjyym", "fsize"=>93966, "mimeType"=>"text/plain", "putTime"=>13993416549476933}, {"key"=>"00000002.txt", "hash"=>"Foiz8WAEOgOo8B-lyYegCHcl6VSb", "fsize"=>172422, "mimeType"=>"text/plain", "putTime"=>13993416551051809}]} +{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwMDQuRENNIn0=", "items"=>[{"key"=>"00000003.txt", "hash"=>"FgsZJh9ACX9-tz2PWjKfFpURlXU2", "fsize"=>175778, "mimeType"=>"text/plain", "putTime"=>13993416553903813}, {"key"=>"00000004.txt", "hash"=>"FikIBhnekDHYA8xugBDchkOrnpEx", "fsize"=>177876, "mimeType"=>"text/plain", "putTime"=>13993416555380554}]} +...更多内容已省略... +``` + +3. 列出所有`00`打头的资源,包括目录,每批2个: + +``` +接口规格 +bucket=qiniu-ts-demo&prefix=00&limit=2&delimiter=%2F + +返回结果 +{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwQ0MuRENNIn0=", "items"=>[{"key"=>"000000CB.txt", "hash"=>"FhSEKlNHeuI1w89AvZMP4ZtlijrO", "fsize"=>208472, "mimeType"=>"text/plain", "putTime"=>13993417254549955}, {"key"=>"000000CC.txt", "hash"=>"FtEIQ24V4Dbx9PVrgK-6S1R3zvbn", "fsize"=>209004, "mimeType"=>"text/plain", "putTime"=>13993417256200466}]} +{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwQ0UuRENNIn0=", "items"=>[{"key"=>"000000CD.txt", "hash"=>"FsfU5MxvxQxhvxts1KBBbZYPwhui", "fsize"=>210170, "mimeType"=>"text/plain", "putTime"=>13993417258134446}, {"key"=>"000000CE.txt", "hash"=>"FjLnLfzKyNpPHAWcjhRLnwEj-1EP", "fsize"=>209276, "mimeType"=>"text/plain", "putTime"=>13993417259836335}]} +{"marker"=>"eyJjIjowLCJrIjoiMDAyLzAwMDAwMDAyLkRDTSJ9", "items"=>[], "commonPrefixes"=>["001/", "002/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDA0LzAwMDAwMDA0LkRDTSJ9", "items"=>[], "commonPrefixes"=>["003/", "004/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDA2LzAwMDAwMDA2LkRDTSJ9", "items"=>[], "commonPrefixes"=>["005/", "006/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDA4LzAwMDAwMDA4LkRDTSJ9", "items"=>[], "commonPrefixes"=>["007/", "008/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDBBLzAwMDAwMDBBLkRDTSJ9", "items"=>[], "commonPrefixes"=>["009/", "00A/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDBDLzAwMDAwMDBDLkRDTSJ9", "items"=>[], "commonPrefixes"=>["00B/", "00C/"]} +{"marker"=>"eyJjIjowLCJrIjoiMDBFLzAwMDAwMDBFLkRDTSJ9", "items"=>[], "commonPrefixes"=>["00D/", "00E/"]} +{"items"=>[], "commonPrefixes"=>["00F/"]} +``` + + +## 附注 + +无。 + + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [上传策略][putPolicyHref] + + +## 外部参考资源 + +- [Unix时间][unixTimeHref] +- [URL转义][urlescapeHref] + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" +[putPolicyHref]: http://developer.qiniu.com/docs/v6/api/reference/security/put-policy.html "上传策略" + +[unixTimeHref]: http://en.wikipedia.org/wiki/Unix_time "Unix时间" + +[urlescapeHref]: http://zh.wikipedia.org/wiki/%E7%99%BE%E5%88%86%E5%8F%B7%E7%BC%96%E7%A0%81 diff --git a/docs/v6/api/reference/glb-rs/move.md b/docs/v6/api/reference/glb-rs/move.md new file mode 100644 index 00000000..0c170ea0 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/move.md @@ -0,0 +1,178 @@ +--- +layout: docs +title: 移动(move) +order: 800 +--- + + +# 多区域移动资源(glb/move) + +- [描述](#move-description) +- [请求](#move-request) + - [请求语法](#move-request-syntax) + - [访问权限](#move-request-auth) + - [请求参数](#move-request-params) + - [头部信息](#move-request-headers) + - [请求内容](#move-request-body) +- [响应](#move-response) + - [响应语法](#move-response-headers) + - [头部信息](#move-response-headers) + - [响应内容](#move-response-body) + - [响应状态码](#move-response-status) +- [示例](#move-samples) + - [命令行示例](#move-sample1-command) + - [请求示例](#move-sample1-request) + - [响应示例](#move-sample1-response) +- [附注](#move-remarks) +- [内部参考资源](#move-internal-resources) + + +## 描述 + +将源空间的指定资源移动到目标空间,或在同一空间内对资源重命名。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/move// HTTP/1.1 +Host: rs.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedEntryURISrc与EncodedEntryURIDest的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,不返回任何内容。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 移动成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +612 | 待移动资源不存在 +614 | 目标资源已存在 + + +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...' \ + -X POST \ + 'http://rs.qiniu.com/glb/move/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ=' +``` + + +### 请求示例 + +``` +POST /glb/move/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1 +User-Agent: curl/7.30.0 +Host: rs.qiniu.com +Accept: */* +Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Thu, 05 Dec 2013 06:55:29 GMT +Content-Type: application/json +Connection: keep-alive +Content-Length: 0 +X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5 +X-Reqid: wxIAAD3btw-v3TwT +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-rs/prefetch.md b/docs/v6/api/reference/glb-rs/prefetch.md new file mode 100644 index 00000000..9357952d --- /dev/null +++ b/docs/v6/api/reference/glb-rs/prefetch.md @@ -0,0 +1,180 @@ +--- +layout: docs +title: 更新镜像资源(prefetch) +order: 498 +--- + + +# 多区域更新镜像资源(glb/prefetch) + +- [描述](#prefetch-description) +- [请求](#prefetch-request) + - [请求语法](#prefetch-request-syntax) + - [访问权限](#prefetch-request-auth) + - [请求参数](#prefetch-request-params) + - [头部信息](#prefetch-request-headers) + - [请求内容](#prefetch-request-body) +- [响应](#prefetch-response) + - [响应语法](#prefetch-response-syntax) + - [头部信息](#prefetch-response-headers) + - [响应内容](#prefetch-response-body) + - [响应状态码](#prefetch-response-status) +- [示例](#prefetch-samples) + - [命令行示例](#prefetch-sample1-command) + - [请求示例](#prefetch-sample1-request) + - [响应示例](#prefetch-sample1-response) +- [附注](#prefetch-remarks) +- [内部参考资源](#prefetch-internal-resources) + + +## 描述 + +对于设置了镜像存储的空间,从镜像源站抓取指定名称的资源并存储到该空间中。 +如果该空间中已存在该名称的资源,则会将镜像源站的资源覆盖空间中相同名称的资源。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/prefetch/ +Host: api.qiniu.com +Content-Type: application/x-www-form-urlencoded +Authorization: QBox +``` + +EncodedEntryURI的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 响应语法 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +``` + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,不返回任何内容。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 抓取成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +404 | 抓取资源不存在 +478 | 源站返回404外,所有非200的response都返回478 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +其余状态码 | 源站返回的状态码,请检查源站资源的可访问性 + +prefetch +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -o - \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...' \ + -X POST \ + 'http://api.qiniu.com/glb/prefetch/bmV3ZG9jczpmaW5kLm1hbi50eHQ=' +``` + + +### 请求示例 + +``` +POST /glb/prefetch/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1 +User-Agent: curl/7.30.0 +Host: api.qiniu.com +Accept: */* +Authorization: QBox u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Thu, 05 Dec 2013 06:55:29 GMT +Content-Type: application/json +Connection: keep-alive +Content-Length: 0 +X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5 +X-Reqid: wxIAAD3btw-v3TwT +``` + + +## 附注 + +- 本接口执行同步操作,如果抓取的资源过大,可能会导致超时。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-rs/stat.md b/docs/v6/api/reference/glb-rs/stat.md new file mode 100644 index 00000000..371c2e01 --- /dev/null +++ b/docs/v6/api/reference/glb-rs/stat.md @@ -0,0 +1,193 @@ +--- +layout: docs +title: 查看(stat) +order: 900 +--- + + +# 多区域查看资源信息(glb/stat) + +- [描述](#stat-description) +- [请求](#stat-request) + - [请求语法](#stat-request-syntax) + - [访问权限](#stat-request-auth) + - [请求参数](#stat-request-params) + - [头部信息](#stat-request-headers) + - [请求内容](#stat-request-body) +- [响应](#stat-response) + - [头部信息](#stat-response-headers) + - [响应内容](#stat-response-body) + - [响应状态码](#stat-response-status) +- [示例](#stat-samples) + - [命令行示例](#stat-sample1-command) + - [请求示例](#stat-sample1-request) + - [响应示例](#stat-sample1-response) +- [附注](#stat-remarks) +- [内部参考资源](#stat-internal-resources) + + + +## 描述 + +仅获取资源的Metadata信息,不返回资源内容。 + + +## 请求 + + +### 请求语法 + +``` +GET /glb/stat/ HTTP/1.1 +Host: rs.qiniu.com +Authorization: QBox +``` + +EncodedEntryURI的细节请查看[EncodedEntryURI格式][encodedEntryURIHref]。 + + +### 访问权限 + +[管理凭证][accessTokenHref]方式。 + + +### 请求参数 + +该请求无需设置任何参数。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------- +Authorization | 是 | 该参数应严格按照[管理凭证][accessTokenHref]格式进行填充,否则会返回401错误码

一个合法的Authorization值应类似于:`QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...` + + +### 请求内容 + +该请求无需指定请求内容。 + + +## 响应 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :----------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息 + +其它可能返回的头部信息,请参考[常见响应头部信息][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "fsize": , + "hash": "", + "mimeType": "", + "putTime": +} +``` + +字段含义如下: + +字段名称 | 必填 | 说明 +:------------- | :--- | :------------------------------ +`fsize` | 是 | 文件尺寸,单位:字节(Byte) +`hash` | 是 | 文件的ETag信息 +`mimeType` | 是 | 以MIME信息表达的文件类型

关于各种MIME值的含义,请参见[MIME Media Types][mimeMediaTypesHref](内容由IANA维护) +`putTime` | 是 | 文件上传时的服务器端Epoch时间戳,单位:100纳秒

例如值为`13603956734587420`的时间对应实际时间为`2013-02-09 15:41:13` + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "error": "" +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`error` | 是 | 与HTTP状态码对应的消息文本 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 获取Metadata成功 +400 | 请求报文格式错误 +401 | 管理凭证无效 +599 | 服务端操作失败

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们 +612 | 目标资源不存在 + + +## 示例 + + +### 命令行示例 + +``` +curl -i \ + -H "Authorization: QBox QNJi_bYJlmO5LeY..." \ + "http://rs.qiniu.com/glb/stat/ZGVtbzoyMDEzLTAyLTA5LTA3LTM5LTIwLmpwZw==" +``` + + +### 请求示例 + +``` +GET /glb/stat/ZGVtbzoyMDEzLTAyLTA5LTA3LTM5LTIwLmpwZw== HTTP/1.1 +User-Agent: curl/7.30.0 +Host: rs.qiniu.com +Accept: */* +Authorization: QBox QNJi_bYJlmO5LeY08FfoNj9w_r72Vsn...(过长已省略) +``` + +注意:要在Authorization头部的``前添加`QBox`和半角空格。 + + +### 响应示例 + +以下响应中JSON字符串经过格式化,以便阅读。 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Sun, 03 Nov 2013 14:01:28 GMT +Content-Type: application/json +Connection: keep-alive +Cache-Control: no-store +Content-Length: 121 +X-Log: qtbl.get;RS +X-Reqid: swEAAMipp-5bIjMT + +{ + "fsize": 5122935, + "hash": "ljfockr0lOil_bZfyaI2ZY78HWoH", + "mimeType": "application/octet-stream", + "putTime": 13603956734587420 +} +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [管理凭证][accessTokenHref] +- [EncodedEntryURI格式][encodedEntryURIHref] + +[encodedEntryURIHref]: http://developer.qiniu.com/docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" +[accessTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/access-token.html "管理凭证" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[mimeMediaTypesHref]: http://www.iana.org/assignments/media-types "MIME媒体类型" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-up/bput.md b/docs/v6/api/reference/glb-up/bput.md new file mode 100644 index 00000000..886b15b0 --- /dev/null +++ b/docs/v6/api/reference/glb-up/bput.md @@ -0,0 +1,149 @@ +--- +layout: docs +title: 上传片 +order: 90 +--- + + +# 多区域上传片 + +- [描述](#bput-description) +- [请求](#bput-request) + - [请求语法](#bput-request-syntax) + - [请求参数](#bput-request-params) + - [头部信息](#bput-request-headers) + - [请求内容](#bput-request-body) + - [访问权限](#bput-request-auth) +- [响应](#bput-response) + - [头部信息](#bput-response-headers) + - [响应内容](#bput-response-body) + - [响应状态码](#bput-response-status) +- [附注](#bput-remarks) +- [内部参考资源](#bput-internal-resources) + + +## 描述 + +上传指定块的一片数据,具体数据量可根据现场环境调整。 +同一块的每片数据必须串行上传。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/bput// HTTP/1.1 +Host: +Content-Type: application/octet-stream +Content-Length: +Authorization: UpToken + + +``` + + +### 请求参数 + +参数名称 | 必填 | 类型 | 说明 +:------------------ | :--- | :----- | :------------------------------ +`` | 是 | string | 前一次上传返回的块级上传控制信息。 +`` | 是 | int64 | 当前片在整个块中的起始偏移。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------- | :--- | :------------------------------------- +Host | 是 | 上一次上传响应返回的后续上传接收地址。 +Content-Type | 是 | 固定为application/octet-stream。 +Content-Length | 是 | 当前片的内容长度,单位:字节(Byte)。 +Authorization | 是 | 该参数应严格按照[上传凭证][uploadTokenHref]格式进行填充,否则会返回401错误码。
一个合法的Authorization值应类似于:`UpToken QNJi_bYJlmO5LeY08FfoNj9w_r7...`。 + + +### 请求内容 + +该请求的内容为当前片的二进制内容。 + + +### 访问权限 + +[上传凭证][uploadTokenHref]方式。 + + +## 响应 + + +### 头部信息 + +头部名称 | 说明 +:------------ | :-------------------------------------------------------------------- +Content-Type | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息。 + +其它可能返回的头部信息,请参考[HTTP响应扩展字段][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "ctx": "", + "checksum": "", + "crc32": , + "offset": , + "host": "" +} +``` + +字段名称 | 必填 | 说明 +:------------- | :--- | :------------------------------ +ctx | 是 | 本次上传成功后的块级上传控制信息,用于后续[上传片](http://developer.qiniu.com/docs/v6/api/reference/glb-up/bput.html)及[创建文件](http://developer.qiniu.com/docs/v6/api/reference/glb-up/mkfile.html)。
本字段是只能被七牛服务器解读使用的不透明字段,上传端不应修改其内容。
每次返回的``都只对应紧随其后的下一个上传数据片,上传非对应数据片会返回701状态码。 +checksum | 是 | 本块已上传部分的校验码,只能被七牛服务器解读使用。 +crc32 | 是 | 本块已上传部分的CRC32值,上传端可通过此字段对本块已上传部分的完整性进行校验。 +offset | 是 | 下一个上传片在上传块中的偏移。 +host | 是 | 后续上传接收地址。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "code": , + "error": "" +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`code` | 是 | HTTP状态码,请参考[响应状态码](#bput-response-status)。 +`error` | 是 | 与HTTP状态码对应的消息文本。 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 上传片成功。 +400 | 请求报文格式错误,报文构造不正确或者没有完整发送。 +401 | 上传凭证无效。 +599 | 服务端操作失败。
如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。 +701 | 后续上传接收地址不正确,或ctx信息已过期。 + + +## 附注 + +- 可以复用创建块时使用的上传凭证。 +- 上传凭证将被重新验证,若已过期,可以使用重新生成的凭证。 + + +## 内部参考资源 + +- [上传凭证][uploadTokenHref] +- [上传片](bput.html) +- [创建文件](mkfile.html) + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[uploadTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/upload-token.html "上传凭证" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-up/index.md b/docs/v6/api/reference/glb-up/index.md new file mode 100644 index 00000000..a05f2a1b --- /dev/null +++ b/docs/v6/api/reference/glb-up/index.md @@ -0,0 +1,19 @@ +--- +layout: docs +title: 多区域上传 +order: 800 +--- + +# 多区域上传 + +本节描述资源上传相关的接口规格,涵盖以下内容: + +* [多区域直传文件(upload)][uploadHref] +* [多区域创建块(mkblk)][mkblkHref] +* [多区域上传片(bput)][bputHref] +* [多区域创建文件(mkfile)][mkfileHref] + +[uploadHref]: upload.html "多区域直传文件" +[mkblkHref]: mkblk.html "多区域创建块" +[bputHref]: bput.html "多区域上传片" +[mkfileHref]: mkfile.html "多区域创建文件" diff --git a/docs/v6/api/reference/glb-up/mkblk.md b/docs/v6/api/reference/glb-up/mkblk.md new file mode 100644 index 00000000..8266621d --- /dev/null +++ b/docs/v6/api/reference/glb-up/mkblk.md @@ -0,0 +1,202 @@ +--- +layout: docs +title: 创建块 +order: 100 +--- + + +# 多区域创建块 + +- [描述](#mkblk-description) +- [请求](#mkblk-request) + - [请求语法](#mkblk-request-syntax) + - [访问权限](#mkblk-request-auth) + - [请求参数](#mkblk-request-params) + - [头部信息](#mkblk-request-headers) + - [请求内容](#mkblk-request-body) +- [响应](#mkblk-response) + - [头部信息](#mkblk-response-headers) + - [响应内容](#mkblk-response-body) + - [响应状态码](#mkblk-response-status) +- [示例](#mkblk-examples) + - [命令行示例](#mkblk-example1-command) + - [请求示例](#mkblk-example1-request) + - [响应示例](#mkblk-example1-response) +- [附注](#mkblk-remarks) +- [内部参考资源](#mkblk-internal-resources) + + + +## 描述 + +为后续分片上传创建一个新的块,同时上传第一片数据。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/mkblk/ HTTP/1.1 +Host: up-glb.qiniu.com +Content-Type: application/octet-stream +Content-Length: +Authorization: UpToken + + +``` + + +### 访问权限 + +[上传凭证][uploadTokenHref]方式。 + + +### 请求参数 + +参数名称 | 必填 | 类型 | 说明 +:------------------ | :--- | :----- | :------------------------------ +`` | 是 | int64 | 块大小,为4MB,最后一块大小不超过4MB。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------- | :--- | :-------------------------------- +Host | 是 | 上传服务器域名。
● 分块上传的首块上传域名为:`up-glb.qiniu.com`。
● 后续片的上传为上一次上传响应返回的后续上传接收地址。 +Content-Type | 是 | 固定为application/octet-stream。 +Content-Length | 是 | 第一个片的内容长度,单位为字节。 +Authorization | 是 | 该参数应严格按照[上传凭证][uploadTokenHref]格式进行填充,否则会返回401错误码。
一个合法的Authorization值应类似于:`UpToken QNJi_bYJlmO5LeY08FfoNj9w_r7...`。 + + +### 请求内容 + +该请求的内容为第一个片的二进制内容。 + + +## 响应 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :-------------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息。 + +其它可能返回的头部信息,请参考[HTTP响应扩展字段][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "ctx": "", + "checksum": "", + "crc32": , + "offset": , + "host": "" +} +``` + +字段名称 | 必填 | 说明 +:------------- | :--- | :------------------------------ +ctx | 是 | 本次上传成功后的块级上传控制信息,用于后续[上传片](bput.html)及[创建文件](mkfile.html)。
本字段是只能被七牛服务器解读使用的不透明字段,上传端不应修改其内容。
每次返回的``都只对应紧随其后的下一个上传数据片,上传非对应数据片会返回701状态码。 +checksum | 是 | 上传块校验码。 +crc32 | 是 | 上传块Crc32,客户可通过此字段对上传块的完整性进行校验。 +offset | 是 | 下一个上传块在切割块中的偏移。 +host | 是 | 后续上传接收地址。 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "code": , + "error": "" +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`code` | 是 | HTTP状态码,请参考[响应状态码](#mkblk-response-status)。 +`error` | 是 | 与HTTP状态码对应的消息文本。 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 创建块成功。 +400 | 请求报文格式错误,报文构造不正确或者没有完整发送。 +401 | 上传凭证无效。 +599 | 服务端操作失败。
如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。 + + +## 示例 + +我们拿一个小文件作为示例,该文件的大小适合作为一次完整上传展示。 + + +### 命令行示例 + +``` +curl -i \ + --data-binary '@test.txt' \ + -H "Authorization: UpToken QNJi_bYJlmO5LeY..." \ + -H "Content-Length: 1024" \ + "http://up-glb.qiniu.com/glb/mkblk/1024" +``` + + +### 请求示例 + +``` +POST /glb/mkblk/1024 HTTP/1.1 +User-Agent: curl/7.30.0 +Host: up-glb.qiniu.com +Accept: */* +Authorization: UpToken QNJi_bYJlmO5LeY08FfoNj9w_r...(过长已省略) +``` + + +### 响应示例 + +以下响应中JSON字符串经过格式化,以便查看。 + +``` +HTTP/1.1 200 OK +Server: nginx/1.0.8 +Date: Sun, 03 Nov 2013 14:01:28 GMT +Content-Type: application/json +Connection: keep-alive +Cache-Control: no-store +Content-Length: 121 +X-Log: qtbl.get;RS +X-Reqid: swEAAMipp-5bIjMT + +{ + "ctx": "ctx", + "checksum": "checksum", + "crc32": 1345, + "offset": 0, + "host": "http://up-nb-5.qbox.me" +} +``` + + +## 附注 + +无。 + + +## 内部参考资源 + +- [上传凭证][uploadTokenHref] +- [上传片](bput.html) +- [创建文件](mkfile.html) + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[uploadTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/upload-token.html "上传凭证" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" diff --git a/docs/v6/api/reference/glb-up/mkfile.md b/docs/v6/api/reference/glb-up/mkfile.md new file mode 100644 index 00000000..e11bc630 --- /dev/null +++ b/docs/v6/api/reference/glb-up/mkfile.md @@ -0,0 +1,153 @@ +--- +layout: docs +title: 创建文件 +order: 10 +--- + + +# 多区域创建文件 + +- [描述](#mkfile-description) +- [请求](#mkfile-request) + - [请求语法](#mkfile-request-syntax) + - [请求参数](#mkfile-request-params) + - [头部信息](#mkfile-request-headers) + - [请求内容](#mkfile-request-body) + - [访问权限](#mkfile-request-auth) +- [响应](#mkfile-response) + - [头部信息](#mkfile-response-headers) + - [响应内容](#mkfile-response-body) + - [响应状态码](#mkfile-response-status) +- [附注](#mkfile-remarks) +- [内部参考资源](#mkfile-internal-resources) + + +## 描述 + +将上传好的所有数据块按指定顺序合并成一个资源文件。 + + +## 请求 + + +### 请求语法 + +``` +POST /glb/mkfile//key//mimeType//x:user-var/ HTTP/1.1 +Host: +Content-Type: text/plain +Content-Length: +Authorization: UpToken + + +``` + + +### 请求参数 + +参数名称 | 必填 | 类型 | 说明 +:------------------ | :--- | :----- | :------------------------------ +`/` | 是 | int64 | 资源文件大小。 +`/key/` | | string | 进行[URL安全的Base64编码][urlsafeBase64Href]后的资源名
若未指定,则使用[saveKey](http://developer.qiniu.com/docs/v6/api/reference/security/put-policy.html#put-policy-save-key);
若未指定`saveKey`,则使用资源内容的SHA1值作为资源名。 +`mimeType/` | | string | 进行[URL安全的Base64编码][urlsafeBase64Href]后的文件mimeType
若未指定,则根据文件内容自动检测mimeType +`/x:user-var/` | | string | 指定[自定义变量](http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html#xvar)。 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------- | :--- | :---------------------------------------- +Host | 是 | 上一次上传响应返回的后续上传接收地址。 +Content-Type | 是 | 固定为text/plain。 +Content-Length | 是 | 所有块的``及分隔符的总长度,单位:字节(Byte)。 +Authorization | 是 | 该参数应严格按照[上传凭证][uploadTokenHref]格式进行填充,否则会返回401错误码
一个合法的Authorization值应类似于:`UpToken QNJi_bYJlmO5LeY08FfoNj9w_r7...`。 + + +### 请求内容 + +该请求的内容为每个数据块最后一个数据片上传后得到的``的列表,以“,”分隔,按其在源文件中的位置排序。 +注意:列表最后一项后面不需要添加“,”。 + +``` +,,,..., +``` + + +### 访问权限 + +[上传凭证][uploadTokenHref]方式。 + + +## 响应 + + +### 头部信息 + +头部名称 | 必填 | 说明 +:------------ | :--- | :-------------------------------------------------------------------- +Content-Type | 是 | 正常情况下该值将被设为`application/json`,表示返回JSON格式的文本信息。 + +其它可能返回的头部信息,请参考[HTTP响应扩展字段][commonHttpResponseHeaderHref]。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "hash": "", + "key": "" +} +``` + +字段名称 | 必填 | 说明 +:------------- | :--- | :------------------------------ +hash | 是 | 资源内容的SHA1值 +key | 是 | 实际资源名 + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "code": , + "error": "" +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`code` | 是 | HTTP状态码,请参考[响应状态码](#mkfile-response-status)。 +`error` | 是 | 与HTTP状态码对应的消息文本。 + + +### 响应状态码 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 创建文件成功。 +400 | 请求报文格式错误。 +401 | 上传凭证无效。 +579 | 回调业务服务器失败。 +599 | 服务端操作失败。
如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。 +614 | 目标资源已存在。 + + +## 附注 + +- 可以复用创建块时使用的上传凭证。 +- 上传凭证将被重新验证,若已过期,可以使用重新生成的凭证。 +- 若参数中指定了资源名,而所用上传策略的[scope字段](http://developer.qiniu.com/docs/v6/api/reference/security/put-policy.html#put-policy-scope)中也指定了资源名,且两者不一致,操作将失败且返回401状态码。 + + +## 内部参考资源 + +- [上传凭证][uploadTokenHref] +- [创建块](mkblk.html) +- [上传片](mkfile.html) +- [URL安全的Base64编码][urlsafeBase64Href] + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" +[uploadTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/upload-token.html "上传凭证" +[commonHttpResponseHeaderHref]: http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html "常见响应头部信息" +[urlsafeBase64Href]: http://developer.qiniu.com/docs/v6/api/overview/appendix.html#urlsafe-base64 "URL安全的Base64编码" diff --git a/docs/v6/api/reference/glb-up/upload.md b/docs/v6/api/reference/glb-up/upload.md new file mode 100644 index 00000000..8891db8d --- /dev/null +++ b/docs/v6/api/reference/glb-up/upload.md @@ -0,0 +1,234 @@ +--- +layout: docs +title: 直传文件 +order: 200 +--- + + +# 多区域直传文件 + +- [描述](#upload-description) +- [使用方法](#method) +- [请求报文](#upload-request) + - [请求报文格式](#upload-request-syntax) + - [请求头部](#upload-request-header) + - [请求报文参数](#upload-request-params) +- [响应报文](#upload-response) + - [响应报文格式](#upload-response-syntax) + - [响应头部](#upload-response-header) + - [响应内容](#upload-response-content) + - [响应状态](#upload-response-status) +- [附注](#upload-remarks) +- [在线示例](#upload-example) +- [内部参考资源](#upload-internal-resources) +- [外部参考资源](#upload-external-resources) + + +## 描述 + +`upload`是七牛云存储提供的最基础的接口,用于在一次HTTP会话中上传单一的一个文件。 + + + +## 使用方法 + +我们可以用如下的HTML表单来描述表单上传的基本用法: + +``` +

+ + + + + + +
+``` + + +## 请求报文 + + +### 请求报文格式 + +请求报文的内容以`multipart/form-data`格式组织,具体细节请参考[Multipart格式][multipartFrontierHref]。 + +``` +POST /glb HTTP/1.1 +Host: up-glb.qiniu.com +Content-Type: multipart/form-data; boundary= +Content-Length: + +-- +Content-Disposition: form-data; name="token" + + +-- +Content-Disposition: form-data; name="key" + + +-- +Content-Disposition: form-data; name="" + + +-- +Content-Disposition: form-data; name="crc32" + + +-- +Content-Disposition: form-data; name="accept" + + +-- +Content-Disposition: form-data; name="file"; filename="" +Content-Type: application/octet-stream +Content-Transfer-Encoding: binary + + +---- +``` + + +### 请求头部 + +头部名称 | 必填 | 说明 +:------------- | :--- | :------------------------------------------ +Host | 是 | 上传服务器域名,固定为`up-glb.qiniu.com`。 +Content-Type | 是 | 固定为multipart/form-data。``为[Multipart分隔符][multipartFrontierHref],必须是任何Multipart消息都不包含的字符串。 +Content-Length | 是 | 整个Multipart内容的总长度,单位:字节(Byte)。 + + +### 请求报文参数 + +请求报文的每一个参数(以“<>”标记)的具体说明如下表所示(按出现位置顺序排列): + +参数名称 | 必填 | 说明 +:---------------------------- | :--- | :----------------------------------------- +`` | 是 | [上传凭证][uploadTokenHref],位于`token`消息中。 +`` | | [自定义变量][xVariablesHref]的名字。 +`` | | [自定义变量][xVariablesHref]的值。 +`` | 是 | 原文件名。
对于没有文件名的情况,建议填入随机生成的纯文本字符串。
本参数的值将作为[魔法变量$(fname)](/docs/v6/api/overview/up/response/vars.html#magicvar-fname)的值使用。 +`` | 是 | 上传文件的完整内容。 +`` | | 资源的名称,位于`key`消息中,**这个不是最终的名称,上传完毕后会根据最终区域,修改``,带上`/`的前缀**。如不指定则使用[上传策略][putPolicyHref]saveKey字段所指定模板生成Key,如无模板则使用`/`值作为Key。 +`` | | 上传内容的 CRC32 校验码。
如填入,则七牛服务器会使用此值进行内容检验。 +`` | | 当 HTTP 请求指定 `Accept` 头部时,七牛会返回的 `Content-Type` 头部的值。
该值用于兼容低版本 IE 浏览器行为。低版本 IE 浏览器在 multiform 返回 `application/json` 的时候会表现为下载,返回 `text/plain` 才会显示返回内容。 + +注意:用户自定义变量可以有多对。 + + + +## 响应报文 + + +### 响应报文格式 + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "hash": "", + "key": "" +} +``` + + +### 响应头部 + +头部名称 | 必填 | 说明 +:------------- | :--- | :------------------------------------------ +Content-Type | 是 | MIME类型,固定为application/json。 +Cache-Control | 是 | 缓存控制,固定为no-store,不缓存。 + + +### 响应内容 + +■ 如果请求成功,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "hash": "", + "key": "" +} +``` + +字段名称 | 必填 | 说明 +:------- | :--- | :-------------------------------------------------------------------- +`hash` | 是 | 目标资源的[hash值](/docs/v6/api/overview/appendix.html#qiniu-etag),可用于ETag头部。 +`key` | 是 | 目标资源的最终名字,可由七牛云存储自动命名。**上传完毕后会根据最终区域,修改``,带上`/`的前缀** + +■ 如果请求失败,返回包含如下内容的JSON字符串(已格式化,便于阅读): + +``` +{ + "code": , + "error": "", +} +``` + +字段名称 | 必填 | 说明 +:----------- | :--- | :-------------------------------------------------------------------- +`code` | 是 | HTTP状态码,请参考[响应状态](#upload-response-status)。 +`error` | 是 | 与HTTP状态码对应的消息文本。 + + +### 响应状态 + +HTTP状态码 | 含义 +:--------- | :-------------------------- +200 | 上传成功。 +400 | 请求报文格式错误,报文构造不正确或者没有完整发送。 +401 | 上传凭证无效。 +413 | 上传内容长度大于 [fsizeLimit](/docs/v6/api/reference/security/put-policy.html#put-policy-fsize-limit) 中指定的长度限制。 +579 | 回调业务服务器失败。 +599 | 服务端操作失败。

如遇此错误,请将完整错误信息(包括所有HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。 +614 | 目标资源已存在。 + + + + +## 附注 + +无。 + + + + + + +## 内部参考资源 + +- [EncodedEntryURI格式][encodedEntryURIHref] +- [上传策略][putPolicyHref] +- [上传凭证][uploadTokenHref] +- [自定义变量][xVariablesHref] +- [URL安全的Base64编码][urlsafeBase64Href] + + +## 外部参考资源 + +- [Multipart分隔符][multipartFrontierHref] +- [MIME类型][mimeTypeHref] +- [MIME清单][mimeTypeListHref] + +[encodedEntryURIHref]: /docs/v6/api/reference/data-formats.html#data-format-encoded-entry-uri "EncodedEntryURI格式" + +[uploadTokenHref]: /docs/v6/api/reference/security/upload-token.html "上传凭证" +[putPolicyHref]: /docs/v6/api/reference/security/put-policy.html "上传策略" +[xVariablesHref]: /docs/v6/api/overview/up/response/vars.html#xvar "自定义变量" + +[multipartFrontierHref]: http://en.wikipedia.org/wiki/MIME#Multipart_messages "Multipart分隔符" +[mimeTypeHref]: http://en.wikipedia.org/wiki/MIME "MIME类型" +[mimeTypeListHref]: http://www.iana.org/assignments/media-types/media-types.xhtml "MIME清单" +[urlsafeBase64Href]: /docs/v6/api/overview/appendix.html#urlsafe-base64 "URL安全的Base64编码" + +[sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" diff --git a/docs/v6/api/reference/index.md b/docs/v6/api/reference/index.md index dfb184ea..38137b74 100644 --- a/docs/v6/api/reference/index.md +++ b/docs/v6/api/reference/index.md @@ -8,7 +8,11 @@ title: 七牛云存储API参考手册 * [资源上传][upHref] * [资源管理][rsHref] * [资源处理][fopHref] +* [多区域资源上传][glb-upHref] +* [多区域资源管理][glb-rsHref] [upHref]: http://developer.qiniu.com/docs/v6/api/reference/up/index.html "资源上传" [rsHref]: http://developer.qiniu.com/docs/v6/api/reference/rs/index.html "资源管理" [fopHref]: http://developer.qiniu.com/docs/v6/api/reference/fop/index.html "资源处理" +[glb-upHref]: http://developer.qiniu.com/docs/v6/api/reference/glb-up/index.html "多区域资源上传" +[glb-rsHref]: http://developer.qiniu.com/docs/v6/api/reference/glb-rs/index.html "多区域资源管理" diff --git a/docs/v6/api/reference/rs/batch.md b/docs/v6/api/reference/rs/batch.md index 9adcbca2..f549aab0 100644 --- a/docs/v6/api/reference/rs/batch.md +++ b/docs/v6/api/reference/rs/batch.md @@ -3,7 +3,7 @@ title: 批量操作(batch) order: 500 --- - + # 批量操作(batch) - [描述](#batch-description) @@ -76,7 +76,7 @@ op=/stat/&op=/stat/&... #### 批量复制资源 ``` -op=/batch//&op=/batch//&... +op=/copy//&op=/copy//&... ``` #### 批量移动资源 @@ -95,7 +95,7 @@ op=/delete/&op=/delete/&... ``` op=/stat/ -&op=/batch// +&op=/copy// &op=/move//&... &op=/delete/&... ``` diff --git a/docs/v6/api/reference/up/bput.md b/docs/v6/api/reference/up/bput.md index 989efa6a..5dc064ee 100644 --- a/docs/v6/api/reference/up/bput.md +++ b/docs/v6/api/reference/up/bput.md @@ -141,8 +141,8 @@ HTTP状态码 | 含义 ## 内部参考资源 - [上传凭证][uploadTokenHref] -- [上传片](http://developer.qiniu.com/docs/v6/api/reference/up/bput.html) -- [创建文件](http://developer.qiniu.com/docs/v6/api/reference/up/mkfile.html) +- [上传片](bput.html) +- [创建文件](mkfile.html) [sendBugReportHref]: mailto:support@qiniu.com?subject=599错误日志 "发送错误报告" [uploadTokenHref]: http://developer.qiniu.com/docs/v6/api/reference/security/upload-token.html "上传凭证"