Resource Storage API

惯例

时间单位

所有涉及时间的参数(如 editTime),统一以 int64 类型,100ns 为单位,从 the Unix epoch, January 1, 1970 00:00:00 UTC 开始算起。

协议

init (初始化:为用户创建空间)

请求包:

POST /init

返回包(JSON):

200 OK

stat (获取Entry信息)

请求包:

POST /stat/<EncodedEntryURI>

返回包(JSON):

200 OK {
    hash: <FileETag>
    fsize: <FileSize>
    editTime: <EditTime>
    mimeType: <MimeType>
}

get (获取文件内容)

请求包:

POST /get/<EncodedEntryURI>/base/<BaseHash>/attName/<AttName>
  • attName=<AttachmentName> 是下载时的名称,可选。如果未指定,直接是文件名。
  • base=<BaseHash> 是文件内容的基版本,可选。如果指定了base,那么当服务器端文件已经发生变化时,返回失败。

返回包(JSON):

200 OK {
    url: <DownloadURL>
    hash: <FileETag>
    fsize: <FileSize>
    mimeType: <MimeType>
}

put (创建/修改文件)

该API属于内部接口,可能限定只有特定的 client(比如限定ip之类)调用。

请求包:

POST /put/<EncodedEntryURI>/fsize/<FileSize>/mimeType/<MimeType>/editTime/<EditTime>
Content-Type: application/octet-stream
Body: <FileHandle>
  • mimeType=<MimeType> 是文件的 mime 类型。这个用于下载(get api)时设置 http 头。
  • editTime=<EditTime> 是文件最后修改时间。可选,没有指定则取服务器当前时间。
  • <FileHandle> 是该文件的句柄,通过它可以获得文件的内容。FileHandle 的组织方式属于 RS 与 IO 两个子系统的内部协议,此处不做规定。

返回包(JSON):

200 OK {
    hash: <FileETag>
}

delete (删除)

请求包:

POST /delete/<EncodedEntryURI>

返回包(JSON):

200 OK

move/copy (移动/复制)

请求包:

POST /move/<EncodedSrcEntryURI>/<EncodedDestEntryURI>
POST /copy/<EncodedSrcEntryURI>/<EncodedDestEntryURI>

返回包(JSON):

200 OK

batch (批处理)

请求包:

POST /batch
Content-Type: application/x-www-form-urlencoded
Body: op=<Operation>&op=<Operation>&...
  • 其中 op=<Operation> 是一个操作。例如 /delete/<EntryURI>, /move/<EncodedSrcEntryURI>/<EncodedDestEntryURI>。

返回包(JSON):

200 OK [
    <Result1>, <Result2>, ...
]
298 Partial OK [
    <Result1>, <Result2>, ...
]
<Result> 是 {
    code: <HttpCode>
    data: <Data> 或 error: <ErrorMessage>
}
  • 当部分 op 执行失败时,返回 298(PartialOK)。

样例

假定我们 Resource Storage 服务部署在 http://rs.qbox.us,以下以 curl 命令操作我们的 Resource Storage 服务。要安装 curl ,请使用:

sudo apt-get install curl

注意我们关于协议描述中,都有意忽略了关于 Auth 的内容。如果我们采用 http 简单授权协议,那么除外链访问不需要 Auth 外,其他 API 均要带上 user, passwd 参数:

curl ... -u <User>:<Password>

如果使用 OAuth 授权协议,那就复杂很多,这里不详细讨论。以下例子采用 http 简单授权协议。

删除Entry

curl http://rs.qbox.us/delete/<Path> -d "" -u <User>:<Password>

删除多个Entry

curl http://rs.qbox.us/batch -d "op=/delete/<Path1>&op=/delete/<Path2>&..." -u <User>:<Password>
Add a New Comment
or Sign in as Wikidot user
(will not be published)
- +
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License