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 は、すべての要求で変化する乱数であるためです。