attachment`¶

HEAD /{db}/{docid}/{attname}¶

返回包含有关指定附件的少量信息的 HTTP 标头。该方法支持与 GET /{db}/{docid}/{attname} 方法相同的查询参数，但只返回标头信息（包括附件大小、编码和作为 ETag 的 MD5 哈希）。

参数：

db – 数据库名称
docid – 文档 ID
attname – 附件名称

请求标头：

If-Match – 文档的修订版本。作为 rev 查询参数的替代方案
If-None-Match – 附件的 base64 编码的 MD5 二进制摘要。可选

查询参数：

rev (字符串) – 文档的修订版本。可选

响应标头：

Accept-Ranges – 支持范围请求。用于具有 application/octet-stream 内容类型的附件
Content-Encoding – 使用的压缩编解码器。如果附件的 content_type 在 list of compressible types 中，则可用
Content-Length – 附件大小。如果使用了压缩编解码器，则此值约为压缩大小，而不是实际大小
ETag – 用双引号引起来的 base64 编码的 MD5 二进制摘要

状态代码：

200 OK – 附件存在
401 Unauthorized – 需要读取权限
404 Not Found – 未找到指定的数据库、文档或附件

请求:

HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 100
Content-Type: text/plain
Date: Thu, 15 Aug 2013 12:42:42 GMT
ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
Server: CouchDB (Erlang/OTP)

GET /{db}/{docid}/{attname}¶

返回与文档关联的文件附件。返回关联附件的原始数据（就像访问静态文件一样。返回的 Content-Type 将与在将文档附件提交到数据库时设置的内容类型相同。

参数：

db – 数据库名称
docid – 文档 ID
attname – 附件名称

请求标头：

If-Match – 文档的修订版本。作为 rev 查询参数的替代方案
If-None-Match – 附件的 base64 编码的 MD5 二进制摘要。可选

查询参数：

rev (字符串) – 文档的修订版本。可选

响应标头：

Accept-Ranges – 支持范围请求。用于具有 application/octet-stream 的附件
Content-Encoding – 使用的压缩编解码器。如果附件的 content_type 在 list of compressible types 中，则可用
Content-Length – 附件大小。如果使用了压缩编解码器，则此值约为压缩大小，而不是实际大小
ETag – 用双引号引起来的 base64 编码的 MD5 二进制摘要

响应：

存储的内容

状态代码：

200 OK – 附件存在
401 Unauthorized – 需要读取权限
404 Not Found – 未找到指定的数据库、文档或附件

PUT /{db}/{docid}/{attname}¶

将提供的内容作为附件上传到指定的文档。提供的附件名称必须是 URL 编码的字符串。您必须提供 Content-Type 标头，并且对于现有文档，您还必须提供 rev 查询参数或 If-Match HTTP 标头。如果省略修订版本，则将使用提供的附件创建新的（否则为空的）文档，或者会发生冲突。

如果在使用现有附件名称上传附件时，CouchDB 将更新数据库中相应的存储内容。由于您必须提供修订版本信息才能将附件添加到文档中，因此这将作为验证来更新现有附件。

注意

上传附件会更新相应的文档修订版本。修订版本是针对父文档跟踪的，而不是针对单个附件跟踪的。

参数：

db – 数据库名称
docid – 文档 ID
attname – 附件名称

请求标头：

Content-Type – 附件 MIME 类型。默认值：application/octet-stream 可选
If-Match – 文档修订版本。作为 rev 查询参数的替代方案

查询参数：

rev (字符串) – 文档修订版本。可选

响应 JSON 对象：

id (字符串) – 文档 ID
ok (布尔值) – 操作状态
rev (字符串) – 修订版本 MVCC 令牌

状态代码：

201 Created – 附件已创建并存储在磁盘上
202 Accepted – 请求已接受，但更改尚未存储在磁盘上
400 Bad Request – 无效的请求正文或参数
401 Unauthorized – 需要写入权限
404 Not Found – 未找到指定的数据库、文档或附件
409 Conflict – 未指定文档的修订版本，或者它不是最新的

请求:

PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
Accept: application/json
Content-Length: 86
Content-Type: text/plain
Host: localhost:5984
If-Match: 1-917fa2381192822767f010b95b45325b

1. Cook spaghetti
2. Cook meatballs
3. Mix them
4. Add tomato sauce
5. ...
6. PROFIT!

响应:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 85
Content-Type: application/json
Date: Thu, 15 Aug 2013 12:38:04 GMT
ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
Location: https://127.0.0.1:5984/recipes/SpaghettiWithMeatballs/recipe.txt
Server: CouchDB (Erlang/OTP)

{
    "id": "SpaghettiWithMeatballs",
    "ok": true,
    "rev": "2-ce91aed0129be8f9b0f650a2edcfd0a4"
}

DELETE /{db}/{docid}/{attname}¶

删除指定 doc 的文件名 {attname} 的附件。您必须提供 rev 查询参数或 If-Match 以及当前修订版本才能删除附件。

注意

删除附件会更新相应的文档修订版本。修订版本是针对父文档跟踪的，而不是针对单个附件跟踪的。

参数：

db – 数据库名称
docid – 文档 ID

请求标头：

Accept –
- application/json
- text/plain
If-Match – 文档修订版本。作为 rev 查询参数的替代方案

查询参数：

rev (字符串) – 文档修订版本。必需
batch (字符串) – 将更改存储在批处理模式中。可能的值：ok。可选

响应标头：

Content-Type –
- application/json
- text/plain; charset=utf-8
ETag – 用双引号引起来的文档的新修订版本

响应 JSON 对象：

id (字符串) – 文档 ID
ok (布尔值) – 操作状态
rev (字符串) – 修订版本 MVCC 令牌

状态代码：

200 OK – 附件已成功删除
202 Accepted – 请求已接受，但更改尚未存储在磁盘上
400 Bad Request – 无效的请求正文或参数
401 Unauthorized – 需要写入权限
404 Not Found – 未找到指定的数据库、文档或附件
409 Conflict – 未指定文档的修订版本，或者它不是最新的

请求:

DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1
Accept: application/json
Host: localhost:5984

或者，您可以使用 If-Match 标头，而不是 rev 查询参数

DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
If-Match: 6-440b2dd39c20413045748b42c6aba6e2
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 85
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:13 GMT
ETag: "7-05185cf5fcdf4b6da360af939431d466"
Server: CouchDB (Erlang/OTP)

{
    "id": "SpaghettiWithMeatballs",
    "ok": true,
    "rev": "7-05185cf5fcdf4b6da360af939431d466"
}

1.4.2.1. HTTP 范围请求¶

HTTP 允许您为请求指定字节范围。这允许实现可恢复的下载以及可跳过的音频和视频流。这适用于 CouchDB 中的所有附件。

这只是快速了解一下它的内部工作原理。通常，您将从 CouchDB 提供更大的二进制文件，例如 MP3 和视频，但为了使事情更清晰，我在这里使用文本文件（请注意，我使用 application/octet-stream :header`Content-Type` 而不是 text/plain）。

shell> cat file.txt
My hovercraft is full of eels!

现在，我们将此文本文件作为附件存储在 CouchDB 中。首先，我们创建一个数据库

shell> curl -X PUT http://127.0.0.1:5984/test
{"ok":true}

然后，我们一次性创建一个新文档和文件附件

shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
            -H "Content-Type: application/octet-stream" [email protected]
{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}

现在，我们可以轻松地请求整个文件

shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
My hovercraft is full of eels!

但假设我们只想要前 13 个字节

shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
            -H "Range: bytes=0-12"
My hovercraft

HTTP 支持多种方法来指定单个甚至多个字节范围。在 RFC 2616#section-14.27 中了解所有这些内容。

注意

使用 CouchDB 1.0.2 或更早版本创建的数据库将在 3.3 中支持范围请求，但它们使用的是效率较低的算法。如果您计划大量使用此功能，请确保使用 CouchDB 3.3 压缩您的数据库，以利用更好的算法来查找字节范围。

1.4.2. /db/doc/attachment¶

1.4.2.1. HTTP 范围请求¶

1.4.2. `/db/doc/attachment`¶