IBM Cloud Docs
HTTP と IBM Cloudant の連動の仕組み

HTTP と IBM Cloudant の連動の仕組み

IBM® Cloudant® for IBM Cloud® を使用する場合に理解しておかなければならない HTTP ヘッダーについて詳しく説明します。

HTTP ヘッダー

IBM Cloudant はすべての外部通信に HTTP を使用するので、正しい HTTP 要求ヘッダーを渡して、取得時に処理する必要があります。 この操作の過程で、正しい形式とエンコードを確実に使用できるようになります。 環境やクライアントによって、これらの HTTP ヘッダーの作用が厳密に適用されるものもあれば、適用されないものもあります。 HTTP ヘッダーがない場合の作用には特に違いがあります。 問題や予期しない動作が発生する可能性を小さくするために、 できる限り具体的に指定する必要があります。

要求ヘッダー

サポートされる HTTP 要求ヘッダーを以下にリストします。

  • Accept
  • Content-Type
  • Content-Encoding
  • If-None-Match

Accept

Accept ヘッダーは、サーバーから返される可能性があるデータ・タイプのうち、クライアントが受け入れて認識できるもののリストを指定します。 形式は、1 つ以上の MIME タイプをコロン区切りにしたリストです。

ほとんどの要求では、 この受け入れリストに JSON データを含める必要があります (application/json)。

添付ファイルについては、MIME タイプを明示的に指定することも、 */* を使用してすべてのファイル・タイプがサポートされることを指定することもできます。

Accept ヘッダーが渡されなかった場合、 サーバーは */* MIME タイプと見なします。 つまり、クライアントがすべての形式を受け入れるものと見なします。

明示的な Accept ヘッダーを指定せずに、または */* を指定して、要求を送信する例を以下に示します。

GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: */*

クライアントがすべてのフォーマットを受け入れることを想定している場合は、返されるヘッダーの以下の例を参照してください。

この要求で返される情報は JSON 形式ですが、返されるコンテンツ・タイプは text/plain になります。

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ヘッダー・フィールドに指定されたタイプを受け入れます。 例えば、 要求の application/json で明示的に Accept を要求した場合は、 返される 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

Content-Type ヘッダーは、要求に入れて渡す情報のコンテンツ・タイプを指定します。 この指定では、MIME のタイプ仕様を使用します。 ほとんどの要求では、 コンテンツ・タイプは JSON (application/json) です。

一部の設定では、MIME タイプはプレーン・テキストです。

特に、添付ファイルをアップロードする場合は、その添付ファイルまたはバイナリーに対応する MIME タイプ (application/octet-stream) をタイプとして指定する必要があります。

要求で Content-Type を使用することを強くお勧めします。

Content-Encoding

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 ヘッダーはオプションです。 送信すると、最後の読み取りまたは更新の後に文書が変更されていないかどうかを判別できます。 If-None-Match ヘッダーの値は、最後に受け取った Etag の値と一致する必要があります。 値が文書の現在のリビジョンと一致する場合、サーバーは 304 Not Modified 状況コードを送信し、応答自体に本文はありません。

文書が変更された場合、文書がまだ存在し、他のエラーが発生していなければ、通常の 200 応答を受け取ります。

応答ヘッダー

応答ヘッダーは、コンテンツを返す場合にサーバーから返されるものです。 さまざまなフィールドが含まれます。 フィールドの多くは標準的な HTTP 応答ヘッダーであり、IBM Cloudant の動作に影響しません。 サポートされている HTTP 応答ヘッダーのうち、IBM Cloudant にとって重要なものを以下にリストします。

  • Cache-Control
  • Content-Length
  • Content-Type
  • Etag

Cache-Control

HTTP 応答ヘッダー Cache-Control は、返される情報の処理方法についての提案をクライアント・キャッシュ・メカニズムに提供します。 通常、IBM Cloudant は must-revalidate 値を返します。 この値は、可能であれば情報を再検証すべきであることを示しています。 再検証すると、動的な性質のコンテンツが正しく更新されることが保証されます。

Content-Length

Content-Length ヘッダーは、返されるコンテンツの長さ (バイト単位) を報告します。

応答ヘッダーの Content-Type

Content-Type ヘッダーは、返されるデータの MIME タイプを示します。 ほとんどの要求では、 返される MIME タイプは text/plain です。 すべてのテキストは Unicode (UTF-8) でエンコードされます。 それが、返される Content-Type に text/plain;charset=utf-8 として明示的に示されます。

Etag

Etag ヘッダーは、文書のリビジョンを表示するために使用されます。 文書については、 この値は文書のリビジョンと同じです。 この値を If-None-Match 要求ヘッダーとともに使用すると、リビジョンがまだ最新の場合に 304 Not Modified 応答を取得できます。

ETag は現在、ビューでは使用できません。これらの要求から返される ETag は、すべての要求で変化する乱数であるためです。