Commits

Yoshito Komatsu committed de61f5a

Updated chapter 4

  • Participants
  • Parent commits 137d4fc

Comments (0)

Files changed (1)

File src/04_core_api.rst

 
 このセクションではHTTPについて膝の深さまで行き、コアCouchDB APIの残りを議論するための足場を組みました。次の停留所は、ドキュメントです。
 
-Documents
-~~~~~~~~~
+.. Documents
+   ~~~~~~~~~
 
-Documents are CouchDB’s central data structure. The idea behind a document is, unsurprisingly, that of a real-world document—a sheet of paper such as an invoice, a recipe, or a business card. We already learned that CouchDB uses the JSON format to store documents. Let’s see how this storing works at the lowest level.
+ドキュメント
+~~~~~~~~~~~~
 
-Each document in CouchDB has an ID. This ID is unique per database. You are free to choose any string to be the ID, but for best results we recommend a UUID (or GUID), i.e., a Universally (or Globally) Unique IDentifier. UUIDs are random numbers that have such a low collision probability that everybody can make thousands of UUIDs a minute for millions of years without ever creating a duplicate. This is a great way to ensure two independent people cannot create two different documents with the same ID. Why should you care what somebody else is doing? For one, that somebody else could be you at a later time or on a different computer; secondly, CouchDB replication lets you share documents with others and using UUIDs ensures that it all works. But more on that later; let’s make some documents:::
+.. Documents are CouchDB’s central data structure. The idea behind a document is, unsurprisingly, that of a real-world document—a sheet of paper such as an invoice, a recipe, or a business card. We already learned that CouchDB uses the JSON format to store documents. Let’s see how this storing works at the lowest level.
+
+ドキュメントはCouchDBの中心をなすデータ構造です。ドキュメントの背後にある考え方は、当然、現実世界の文書、つまり請求書、レシピや名刺などの紙1枚です。私たちはすでにCouchDBがドキュメントを保存するためにJSON形式を使っていることを学びました。この保存が最も下のレベルではどのように動作しているのかを見てみましょう。
+
+.. Each document in CouchDB has an ID. This ID is unique per database. You are free to choose any string to be the ID, but for best results we recommend a UUID (or GUID), i.e., a Universally (or Globally) Unique IDentifier. UUIDs are random numbers that have such a low collision probability that everybody can make thousands of UUIDs a minute for millions of years without ever creating a duplicate. This is a great way to ensure two independent people cannot create two different documents with the same ID. Why should you care what somebody else is doing? For one, that somebody else could be you at a later time or on a different computer; secondly, CouchDB replication lets you share documents with others and using UUIDs ensures that it all works. But more on that later; let’s make some documents::
+
+CouchDBの各ドキュメントはIDを持ちます。このIDはデータベースごとに一意です。IDには任意の文字列を自由に選ぶことができますが、最良の結果を得るために、私たちはUUID(またはGUID)、すなわちUniversal(またはGlobally) Unique IDentifierを推奨します。UUIDは、衝突する確率の非常に低いランダムな数字です。その確率は、100万年間すべての人が1分間に1000個のUUIDを重複することなく生成し続けることができるほどです。これは2つの独立した人が2つの異なったドキュメントを同じIDでつくることができないということを確実にするために最適な方法です。何故他の誰かが行うことを気にしなければならないのでしょうか。第1に、その他の誰かというのが後のあなた自身、または違うコンピューターを使うあなたであるかも知れないからです。第2に、CouchDBのレプリケーションを使うと他の人とドキュメントを共有することになり、UUIDを使うとそれが完全に動作することを確実にできるからです。しかし詳細は後にしましょう。いくつかドキュメントを作成してみましょう。
+
+::
 
   curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
 
-CouchDB replies:::
+.. CouchDB replies::
+
+CouchDBは次のように返答します。
+
+::
 
   {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"1-2902191555"}
 
-The curl command appears complex, but let’s break it down. First, -X PUT tells curl to make a PUT request. It is followed by the URL that specifies your CouchDB IP address and port. The resource part of the URL /albums/6e1295ed6c29495e54cc05947f18c8af specifies the location of a document inside our albums database. The wild collection of numbers and characters is a UUID. This UUID is your document’s ID. Finally, the -d flag tells curl to use the following string as the body for the PUT request. The string is a simple JSON structure including title and artist attributes with their respective values.
+.. The curl command appears complex, but let’s break it down. First, -X PUT tells curl to make a PUT request. It is followed by the URL that specifies your CouchDB IP address and port. The resource part of the URL /albums/6e1295ed6c29495e54cc05947f18c8af specifies the location of a document inside our albums database. The wild collection of numbers and characters is a UUID. This UUID is your document’s ID. Finally, the -d flag tells curl to use the following string as the body for the PUT request. The string is a simple JSON structure including title and artist attributes with their respective values.
 
-If you don’t have a UUID handy, you can ask CouchDB to give you one (in fact, that is what we did just now without showing you). Simply send a GET request to /_uuids:::
+curlコマンドは複雑に見えますが、分解してみましょう。まず、-X PUTはcurlにPUTリクエストを作るよう指示します。その後にあなたのCouchDBのIPアドレスとポートを指定するURLが続きます。/albums/6e1295ed6c29495e54cc05947f18c8afというURLのリソース部分は、私たちのalbumsデータベースの中でのドキュメントの場所を指定します。数字と文字の羅列はUUIDです。このUUIDはあなたのドキュメントのIDです。最後に、-dフラグはcurlに、続く文字列をPUTリクエストの本文として使うよう指示します。この文字列は単純なJSONの構造で、title属性とartist属性をそれぞれの値として含んでいます。
+
+.. If you don’t have a UUID handy, you can ask CouchDB to give you one (in fact, that is what we did just now without showing you). Simply send a GET request to /_uuids::
+
+もしUUIDを簡単に用意することができなければ、CouchDBにUUIDを要求することができます(実際、これが先程私たちがあなたに見せずに行ったことです)。単純にGETリクエストを/_uuidsに送ります。
+
+::
 
   curl -X GET http://127.0.0.1:5984/_uuids
 
-CouchDB replies:::
+.. CouchDB replies::
+
+CouchDBは次のように返答します。
+
+::
 
   {"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
 
-Voilá, a UUID. If you need more than one, you can pass in the ?count=10 HTTP parameter to request 10 UUIDs, or really, any number you need.
+.. Voilá, a UUID. If you need more than one, you can pass in the ?count=10 HTTP parameter to request 10 UUIDs, or really, any number you need.
 
-To double-check that CouchDB isn’t lying about having saved your document (it usually doesn’t), try to retrieve it by sending a GET request:::
+はい、これがUUIDです。もしあなたが1個より多く欲しいのであれば、10個のUUIDを要求するためにHTTPパラメータとして?count=10を渡すことができ、実際には必要な任意の数を使うことができます。
+
+.. To double-check that CouchDB isn’t lying about having saved your document (it usually doesn’t), try to retrieve it by sending a GET request:::
+
+CouchDBがドキュメントを保存したということについて嘘をついていないかをダブルチェックするために、GETリクエストを送ってドキュメントを取得してみましょう。
+
+::
 
   curl -X GET http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
 
-We hope you see a pattern here. Everything in CouchDB has an address, a URI, and you use the different HTTP methods to operate on these URIs.
+.. We hope you see a pattern here. Everything in CouchDB has an address, a URI, and you use the different HTTP methods to operate on these URIs.
 
-CouchDB replies:::
+私たちは、あなたがここにパターンを見付けることを期待しています。CouchDBの中のすべてのものはアドレス、URIを持っていて、これらのURIを操作するために異なったHTTPメソッドを使います。
+
+.. CouchDB replies:::
+
+CouchDBは次のように返答します。
+
+::
 
   {"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}
 
-This looks a lot like the document you asked CouchDB to save, which is good. But you should notice that CouchDB added two fields to your JSON structure. The first is _id, which holds the UUID we asked CouchDB to save our document under. We always know the ID of a document if it is included, which is very convenient.
+.. This looks a lot like the document you asked CouchDB to save, which is good. But you should notice that CouchDB added two fields to your JSON structure. The first is _id, which holds the UUID we asked CouchDB to save our document under. We always know the ID of a document if it is included, which is very convenient.
 
-The second field is _rev. It stands for revision.
+これはあなたがCouchDBに保存するよう指示したドキュメントに良く似ていて、問題ありません。しかし、CouchDBが2つのフィールドをJSONの構造に追加していることに気付いたでしょう。1つは、_idで、これは私たちがCouchDBにドキュメントをここに保存するようにと指示したUUIDを保持するものです。私たちはIDが含まれている限り、いつもドキュメントのIDを知っています。これはとても便利です。
 
-Revisions
-~~~~~~~~~
+.. The second field is _rev. It stands for revision.
 
-If you want to change a document in CouchDB, you don’t tell it to go and find a field in a specific document and insert a new value. Instead, you load the full document out of CouchDB, make your changes in the JSON structure (or object, when you are doing actual programming), and save the entire new revision (or version) of that document back into CouchDB. Each revision is identified by a new _rev value.
+2つ目のフィールドは、_revです。これはrevisionの略です。
 
-If you want to update or delete a document, CouchDB expects you to include the _rev field of the revision you wish to change. When CouchDB accepts the change, it will generate a new revision number. This mechanism ensures that, in case somebody else made a change unbeknownst to you before you got to request the document update, CouchDB will not accept your update because you are likely to overwrite data you didn’t know existed. Or simplified: whoever saves a change to a document first, wins. Let’s see what happens if we don’t provide a _rev field (which is equivalent to providing a outdated value):::
+.. Revisions
+   ~~~~~~~~~
+
+リビジョン
+~~~~~~~~~~
+
+.. If you want to change a document in CouchDB, you don’t tell it to go and find a field in a specific document and insert a new value. Instead, you load the full document out of CouchDB, make your changes in the JSON structure (or object, when you are doing actual programming), and save the entire new revision (or version) of that document back into CouchDB. Each revision is identified by a new _rev value.
+
+もしあなたがCouchDBのドキュメントを変更したいと思ったなら、そこに行って特定のドキュメントからフィールドを探し、新しい値を挿入するよう指示することはできません。代わりに、CouchDBからドキュメント全体を読み込んで、JSONの構造(あなたが実際のプログラミングを行っているのであれば、オブジェクト)に変更を加えて、全体をそのドキュメントの新しいリビジョン(またはバージョン)をCouchDBに保存します。各リビジョンは、新しい_revの値で識別されます。
+
+.. If you want to update or delete a document, CouchDB expects you to include the _rev field of the revision you wish to change. When CouchDB accepts the change, it will generate a new revision number. This mechanism ensures that, in case somebody else made a change unbeknownst to you before you got to request the document update, CouchDB will not accept your update because you are likely to overwrite data you didn’t know existed. Or simplified: whoever saves a change to a document first, wins. Let’s see what happens if we don’t provide a _rev field (which is equivalent to providing a outdated value)::
+
+もしドキュメントを更新したり削除したいのであれば、CouchDBは変更したいリビジョンの_revフィールドが含まれていることを期待します。CouchDBが変更を受け入れると、新しいリビジョン番号が生成されます。このメカニズムは、あなたがドキュメントの更新のリクエストを行う前に、他の誰かがあなたにとって未知の変更を行った場合に、CouchDBがあなたの更新を受け入れないことを確実にします。これは、あなたが存在を知らないデータを上書きしてしまう可能性があるためです。単純に言えば、先にドキュメントへの変更を保存した人が勝つということです。_revフィールドを与えなかった場合(これは期限切れの値を与えた場合と同じです)に、何が起きるかを見てみましょう。
+
+::
 
   curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
 
-CouchDB replies:::
+.. CouchDB replies::
+
+CouchDBは次のように返答します。
+
+::
 
   {"error":"conflict","reason":"Document update conflict."}
 
-If you see this, add the latest revision number of your document to the JSON structure:::
+.. If you see this, add the latest revision number of your document to the JSON structure::
+
+これを見たら、あなたのドキュメントの最新のリビジョン番号をJSONの構造に追加してください。
+
+::
 
   curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"_rev":"1-2902191555","title":"There is Nothing Left to Lose", "artist":"Foo Fighters","year":"1997"}'
 
-Now you see why it was handy that CouchDB returned that _rev when we made the initial request. CouchDB replies:::
+.. Now you see why it was handy that CouchDB returned that _rev when we made the initial request. CouchDB replies::
+
+これで何故最初のリクエストを作成したときにCouchDBがその_revを返すことが役に立つのかが分かりました。CouchDBは次のように返答します。
+
+::
 
   {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"2-2739352689"}
 
-CouchDB accepted your write and also generated a new revision number. The revision number is the md5 hash of the transport representation of a document with an N- prefix denoting the number of times a document got updated. This is useful for replication. See Chapter 17, Conflict Management for more information.
+.. CouchDB accepted your write and also generated a new revision number. The revision number is the md5 hash of the transport representation of a document with an N- prefix denoting the number of times a document got updated. This is useful for replication. See Chapter 17, Conflict Management for more information.
 
-There are multiple reasons why CouchDB uses this revision system, which is also called Multi-Version Concurrency Control (MVCC). They all work hand-in-hand, and this is a good opportunity to explain some of them.
+CouchDBはあなたの書き込みを受け入れ、新しいリビジョン番号を生成しました。リビジョン番号は、先頭にドキュメントが更新された回数を示すN-を付けた、ドキュメントの移動用の表現のmd5ハッシュです。これはレプリケーションに便利です。詳細については「17章 衝突の管理」を参照してください。
 
-One of the aspects of the HTTP protocol that CouchDB uses is that it is stateless. What does that mean? When talking to CouchDB you need to make requests. Making a request includes opening a network connection to CouchDB, exchanging bytes, and closing the connection. This is done every time you make a request. Other protocols allow you to open a connection, exchange bytes, keep the connection open, exchange more bytes later—maybe depending on the bytes you exchanged at the beginning—and eventually close the connection. Holding a connection open for later use requires the server to do extra work. One common pattern is that for the lifetime of a connection, the client has a consistent and static view of the data on the server. Managing huge amounts of parallel connections is a significant amount of work. HTTP connections are usually short-lived, and making the same guarantees is a lot easier. As a result, CouchDB can handle many more concurrent connections.
+.. There are multiple reasons why CouchDB uses this revision system, which is also called Multi-Version Concurrency Control (MVCC). They all work hand-in-hand, and this is a good opportunity to explain some of them.
 
-Another reason CouchDB uses MVCC is that this model is simpler conceptually and, as a consequence, easier to program. CouchDB uses less code to make this work, and less code is always good because the ratio of defects per lines of code is static.
+何故CouchDBがMulti-Version Concurrency Control(MVCC)とも呼ばれるこのリビジョンシステムを使っているのかには、複数の理由があります。これらはすべて協力して動作するのですが、これらのいくつかについてはこれが説明する良い機会です。
 
-The revision system also has positive effects on replication and storage mechanisms, but we’ll explore these later in the book.
+.. One of the aspects of the HTTP protocol that CouchDB uses is that it is stateless. What does that mean? When talking to CouchDB you need to make requests. Making a request includes opening a network connection to CouchDB, exchanging bytes, and closing the connection. This is done every time you make a request. Other protocols allow you to open a connection, exchange bytes, keep the connection open, exchange more bytes later—maybe depending on the bytes you exchanged at the beginning—and eventually close the connection. Holding a connection open for later use requires the server to do extra work. One common pattern is that for the lifetime of a connection, the client has a consistent and static view of the data on the server. Managing huge amounts of parallel connections is a significant amount of work. HTTP connections are usually short-lived, and making the same guarantees is a lot easier. As a result, CouchDB can handle many more concurrent connections.
+
+CouchDBが使用しているHTTPプロトコルの一面として、ステートレスであるということが挙げられます。それはどういう意味でしょうか。CouchDBと通信するときに、あなたはリクエストを生成する必要があります。リクエストの生成はCouchDBへのネットワーク接続を開き、バイト列を交換し、接続を閉じることが含まれます。あなたがリクエストを生成する度に、これが毎回行われます。他のプロトコルには、接続を開いて、バイト列を交換して、接続を開いたままで、後で更にバイト列(それは最初に交換したバイト列に依存しているかも知れません)を交換し、最後に接続を閉じることのできるものもあります。後で使うために接続を開いたままにしておくには、サーバーに余分な作業を行わせなければなりません。ひとつの一般的なパターンは、接続の存続期間中、クライアントがデータの一貫性のある静的なビューをサーバーに持っている場合です。膨大な量の並行した接続を管理することは、かなりの量の作業です。HTTP接続は通常、存続期間が短く、同じ保証をするのもずっと簡単です。結果として、CouchDBはより多くの同時接続を処理することができます。
+
+.. Another reason CouchDB uses MVCC is that this model is simpler conceptually and, as a consequence, easier to program. CouchDB uses less code to make this work, and less code is always good because the ratio of defects per lines of code is static.
+
+CouchDBがMVCCを使用するもうひとつの理由は、このモデルが概念的に単純であり、結果としてプログラミングが簡単になるということです。CouchDBのこの作業を行うためのコードは少なく、コード1行当たりの欠陥の比率はほとんど変化しないことから、コードが少ないということはいつも良いことです。
+
+.. The revision system also has positive effects on replication and storage mechanisms, but we’ll explore these later in the book.
+
+また、このリビジョンシステムは、レプリケーションやストレージメカニズムにプラスの効果をもたらしますが、それについてはこの本の後半で見ていきます。
 
 The terms version and revision might sound familiar (if you are programming without version control, drop this book right now and start learning one of the popular systems). Using new versions for document changes works a lot like version control, but there’s an important difference: CouchDB does not guarantee that older versions are kept around.