HTTP 如何使用 IBM Cloudant
了解有关使用 IBM® Cloudant® for IBM Cloud®时需要了解的 HTTP 头的详细信息。
HTTP 头
由于 IBM Cloudant 将 HTTP 用于所有外部通信,因此需要确保在检索时提供并处理正确的 HTTP 请求头。 此操作过程可确保您获得正确的格式和编码。 不同环境和客户机对这些 HTTP 头的影响或多或少都很严格,尤其是当它们不存在时。 要降低发生问题或意外行为的可能性,您必须尽可能具体。
请求头
以下列表中显示了受支持的 HTTP 请求头:
Accept
Content-Type
Content-Encoding
If-None-Match
Accept
Accept
头指定服务器返回的可供客户机接受和理解的潜在数据类型的列表。 格式是用冒号分隔的一个或多个 MIME 类型的列表。
对于最多的请求,接受的列表必须包含 JSON 数据 (application/json
)。
对于附件,可以显式指定 MIME 类型,也可以使用 */*
来指定支持所有文件类型。
如果未提供 Accept
头,那么服务器将采用 */*
MIME 类型,这意味着客户机接受所有格式。
请参阅以下不带显式 Accept
头发送请求的示例,或者当您指定 */*
时:
GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: */*
当假定客户机接受所有格式时,请参阅返回的头的以下示例。
返回的内容类型为 text/plain
,尽管请求返回的信息为 JSON 格式。
Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:39:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: #7
Cache-Control: must-revalidate
不需要在对 IBM Cloudant 的查询中使用 Accept
,但强烈建议使用此方法,因为这有助于确保客户机可以处理返回的数据。
如果指定使用 Accept
头的数据类型, IBM Cloudant 采用响应的 Content-type
头字段中的指定类型。 例如,如果在请求的 Accept
中显式请求 application/json
,那么返回的 HTTP 头将在返回的 Content-type
字段中使用此值。
请参阅以下显式指定 Accept
头的示例请求:
GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: application/json
请参阅响应中返回的头的以下示例,包括 application/json
内容类型:
Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:40:11 GMT
Content-Type: application/json
Content-Length: #7
Cache-Control: must-revalidate
请求头的内容类型
Content-Type
头指定请求中提供的信息的内容类型。 该规范使用 MIME 类型规范。 对于大多数请求,内容类型为 JSON (application/json
)。
对于某些设置, MIME 类型为纯文本。
特别是,上载附件时,类型必须是附件或二进制文件 (application/octet-stream
) 的相应 MIME 类型。
强烈建议对请求使用 Content-Type
。
内容编码
Content-Encoding
头指定请求主体的编码。 受支持的值为 gzip
。 如果使用了头,那么必须使用相应的格式对请求主体进行编码。
请参阅以下创建压缩 (gzipped
) 请求主体的示例:
# create gzipped document
echo '{"foo":"bar"}' | gzip > doc.gzip
请参阅以下发送 gzip 编码请求主体的示例,以使用 HTTP 创建文档:
PUT /db/doc HTTP/1.1
HOST: example.cloudant.com
Content-Encoding: gzip
请参阅以下发送 gzip 编码的请求主体的示例,以使用命令行来创建文档:
curl "https://example.cloudant.com/db/doc" \
-X PUT \
-T doc.gzip \
-H "Content-Encoding: gzip"
缺省情况下, SDK 会压缩请求主体。
如果-无-匹配
If-None-Match
头是可选的。 您可以将其发送以确定文档自上次读取或更新以来是否已修改。
If-None-Match
头的值必须与接收的最后一个 Etag
值匹配。 如果该值与文档的当前修订版相匹配,那么服务器将发送 304 Not Modified
状态码,并且响应本身没有主体。
如果文档已修改,那么您将获得正常的 200
响应,前提是该文档仍然存在并且未发生其他错误。
响应头
当您发送回内容时,服务器将返回响应头。 它们包含多个不同的字段。 许多字段是标准 HTTP 响应头,对于 IBM Cloudant 的操作方式没有任何意义。 对于 IBM Cloudant 很重要的受支持 HTTP 响应头如以下列表中所示。
Cache-Control
Content-Length
Content-Type
Etag
Cache-Control
Cache-Control
HTTP 响应头为客户机高速缓存机制提供有关如何处理返回的信息的建议。 IBM Cloudant 通常返回 must-revalidate
值,指示必须重新验证信息 (如果可能)。 重新验证可确保正确更新内容的动态性质。
内容长度
Content-Length
头报告返回内容的长度 (以字节计)。
响应头的内容类型
Content-Type
头指定所返回数据的 MIME 类型。 对于大多数请求,返回的 MIME 类型为 text/plain
。 所有文本都以 Unicode (UTF-8) 编码,在返回的 Content-Type
中显式声明为 text/plain;charset=utf-8
。
Etag
Etag
头用于显示文档的修订版。 对于文档,该值与文档的修订版相同。 该值可与 If-None-Match
请求头配合使用,以获取 304 Not Modified
响应 (如果修订版仍为最新)。
ETags 当前不能用于视图,因为从这些请求返回的 ETags 是在每个请求上更改的随机数。