IBM Cloud Docs
HTTP 如何使用 IBM Cloudant

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 是在每个请求上更改的随机数。