Commits

Yoshito Komatsu committed 137d4fc

Updated chapter 4

  • Participants
  • Parent commits a561617

Comments (0)

Files changed (1)

File src/04_core_api.rst

 データベース
 ~~~~~~~~~~~~~
 
-Now let’s do something a little more useful: create databases. For the strict, CouchDB is a database management system (DMS). That means it can hold multiple databases. A database is a bucket that holds “related data.” We’ll explore later what that means exactly. In practice, the terminology is overlapping—often people refer to a DMS as “a database” and also a database within the DMS as “a database.” We might follow that slight oddity, so don’t get confused by it. In general, it should be clear from the context if we are talking about the whole of CouchDB or a single database within CouchDB.
+.. Now let’s do something a little more useful: create databases. For the strict, CouchDB is a database management system (DMS). That means it can hold multiple databases. A database is a bucket that holds “related data.” We’ll explore later what that means exactly. In practice, the terminology is overlapping—often people refer to a DMS as “a database” and also a database within the DMS as “a database.” We might follow that slight oddity, so don’t get confused by it. In general, it should be clear from the context if we are talking about the whole of CouchDB or a single database within CouchDB.
 
-Now let’s make one! We want to store our favorite music albums, and we creatively give our database the name albums. Note that we’re now using the -X option again to tell curl to send a PUT request instead of the default GET request:::
+さて、もう少し実用的なことをしてみましょう。データベースを作成します。厳密には、CouchDBはデータベース管理システム(DMS)です。これは、CouchDBはデータベースを複数保持することができるということを意味します。データベースは「関連するデータ」を保持するバケツです。これが正確には何を意味するのか、ということについては後で見ていきます。実際には、この専門用語は重なりあっています。人々はしばしばDMSのことを「データベース」と言いますし、DMSの中のデータベースを「データベース」とも言います。私たちがこのような少し奇妙な言い回しに従うことがあるかも知れませんが、それによって混乱しないようにしてください。一般的には、CouchDB全体について話をしている場合や、CouchDBの中のひとつのデータベースについて話をしている場合には文脈から明らかでしょう。
+
+.. Now let’s make one! We want to store our favorite music albums, and we creatively give our database the name albums. Note that we’re now using the -X option again to tell curl to send a PUT request instead of the default GET request::
+
+さて、ひとつ作ってみましょう!私たちはお気に入りの音楽アルバムを保存したいと思います。独創的に、データベースの名前はalbumsとします。今、curlがデフォルトのGETリクエストの代わりにPUTリクエストを送信するように、-Xオプションをまた使っていることに注意してください。
+
+::
 
   curl -X PUT http://127.0.0.1:5984/albums
 
-CouchDB replies:::
+.. CouchDB replies::
+
+CouchDBは次のように返答します。
+
+::
 
   {"ok":true}
 
-That’s it. You created a database and CouchDB told you that all went well. What happens if you try to create a database that already exists? Let’s try to create that database again:::
+.. That’s it. You created a database and CouchDB told you that all went well. What happens if you try to create a database that already exists? Let’s try to create that database again::
+
+これだけです。あなたはデータベースを作成し、CouchDBはすべてがうまくいったことを知らせます。もし、既に存在するデータベースを作成しようとしたら、何が起きるでしょうか。もう一度このデータベースを作ってみましょう。
+
+::
 
   curl -X PUT http://127.0.0.1:5984/albums
 
-CouchDB replies:::
+.. CouchDB replies::
+
+CouchDBは次のように返答します。
+
+::
 
   {"error":"file_exists","reason":"The database could not be created, the file already exists."}
 
-We get back an error. This is pretty convenient. We also learn a little bit about how CouchDB works. CouchDB stores each database in a single file. Very simple. This has some consequences down the road, but we’ll skip the details for now and explore the underlying storage system in Appendix F, The Power of B-trees.
+.. We get back an error. This is pretty convenient. We also learn a little bit about how CouchDB works. CouchDB stores each database in a single file. Very simple. This has some consequences down the road, but we’ll skip the details for now and explore the underlying storage system in Appendix F, The Power of B-trees.
 
-Let’s create another database, this time with curl’s -v (for “verbose”) option. The verbose option tells curl to show us not only the essentials—the HTTP response body—but all the underlying request and response details:::
+エラーが返ってきました。これはかなり便利です。CouchDBがどのように動作しているのかについて、少し学習します。CouchDBは各データベースをひとつのファイルに保存します。非常に単純です。このことは、将来的にいくつかの結果をもたらしますが、今のところ詳細は飛ばして、基礎となるストレージシステムは「付録F 強力なB木」で探索します。
+
+.. Let’s create another database, this time with curl’s -v (for “verbose”) option. The verbose option tells curl to show us not only the essentials—the HTTP response body—but all the underlying request and response details::
+
+もうひとつ、データベースを作りましょう。今度はcurlの-vオプション(「verbose」の意)を使います。この冗長オプションを使うと、curlはHTTPレスポンスの本文のような重要な情報以外の、基礎となるすべてのリクエストとレスポンスの詳細を表示します。
+
+::
 
   curl -vX PUT http://127.0.0.1:5984/albums-backup
 
-curl elaborates:::
+.. curl elaborates::
+
+curlは詳しく説明します。
+
+::
 
   * About to connect() to 127.0.0.1 port 5984 (#0)
   *   Trying 127.0.0.1... connected
   * Connection #0 to host 127.0.0.1 left intact
   * Closing connection #0
 
-What a mouthful. Let’s step through this line by line to understand what’s going on and find out what’s important. Once you’ve seen this output a few times, you’ll be able to spot the important bits more easily.::
+.. What a mouthful. Let’s step through this line by line to understand what’s going on and find out what’s important. Once you’ve seen this output a few times, you’ll be able to spot the important bits more easily.::
+
+何て長い言葉でしょう。何が起きているかを理解し、重要なことを見付けるために、一行づつ追ってみましょう。この出力を何度か見れば、あなたはより簡単に重要な部分を見付けることができるようになるでしょう。
+
+::
 
   * About to connect() to 127.0.0.1 port 5984 (#0)
 
+.. This is curl telling us that it is going to establish a TCP connection to the CouchDB server we specified in our request URI. Not at all important, except when debugging networking issues.::
 
-This is curl telling us that it is going to establish a TCP connection to the CouchDB server we specified in our request URI. Not at all important, except when debugging networking issues.::
+これは、curlがリクエストURIで指定したCouchDBサーバーへのTCP接続を確立しようとしていることを示しています。まったく重要ではありませんが、ネットワークの問題をデバッグしているときは別です。
+
+::
 
   *   Trying 127.0.0.1... connected
   * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
 
-curl tells us it successfully connected to CouchDB. Again, not important if you aren’t trying to find problems with your network.t
+.. curl tells us it successfully connected to CouchDB. Again, not important if you aren’t trying to find problems with your network.
 
-The following lines are prefixed with > and < characters. > means the line was sent to CouchDB verbatim (without the actual >). < means the line was sent back to curl by CouchDB.::
+curlがCouchDBに正常に接続したことを示しています。繰り返しますが、あなたがネットワークについての問題を見付けようとしているのでなければ、重要ではありません。
+
+.. The following lines are prefixed with > and < characters. > means the line was sent to CouchDB verbatim (without the actual >). < means the line was sent back to curl by CouchDB.::
+
+次の行は、>と<という文字で始まります。>は、その行が(実際の>を除いて)そのままの形でCouchDBに送信されたということを意味します。<はその行がCouchDBからcurlに送り返されたということを意味します。
+
+::
 
   > PUT /albums-backup HTTP/1.1
 
-This initiates an HTTP request. Its method is PUT, the URI is /albums-backup, and the HTTP version is HTTP/1.1. There is also HTTP/1.0, which is simpler in some cases, but for all practical reasons you should be using HTTP/1.1.
+.. This initiates an HTTP request. Its method is PUT, the URI is /albums-backup, and the HTTP version is HTTP/1.1. There is also HTTP/1.0, which is simpler in some cases, but for all practical reasons you should be using HTTP/1.1.
 
-Next, we see a number of request headers. These are used to provide additional details about the request to CouchDB.::
+これは、HTTPリクエストを開始しています。そのメソッドはPUTで、URIは/albums-backup、そしてHTTPバージョンはHTTP/1.1です。場合によってはより単純になるHTTP/1.0もありますが、すべての実用的な理由からは、HTTP/1.1を使うべきです。
+
+.. Next, we see a number of request headers. These are used to provide additional details about the request to CouchDB.::
+
+次に、いくつかのリクエストヘッダーを見ます。これらは、CouchDBへのリクエストについての追加の詳細を提供するために使われます。
+
+::
 
   > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
 
-The User-Agent header tell CouchDB which piece of client software is doing the HTTP request. We don’t learn anything new: it’s curl. This header is often useful in web development when there are known errors in client implementations that a server might want to prepare the response for. It also helps to determine which platform a user is on. This information can be used for technical and statistical reasons. For CouchDB, the User-Agent header is irrelevant.::
+.. The User-Agent header tell CouchDB which piece of client software is doing the HTTP request. We don’t learn anything new: it’s curl. This header is often useful in web development when there are known errors in client implementations that a server might want to prepare the response for. It also helps to determine which platform a user is on. This information can be used for technical and statistical reasons. For CouchDB, the User-Agent header is irrelevant.::
+
+User-Agentヘッダーは、CouchDBに、どのようなクライアントソフトウェアがHTTPリクエストを送信してきたのかを知らせます。新しく学習することは何もありません。curlです。このヘッダーは、ウェブ開発で、サーバーがそのためにレスポンスを準備する必要のあるようなクライアントの実装における既知のエラーが存在するときにしばしば便利です。また、これはユーザーがどのプラットフォームを使用しているのかを明らかにするために役立ちます。この情報は技術的、統計的な理由で使用することができます。CouchDBにとっては、User-Agentヘッダーは関係がありません。
+
+::
 
   > Host: 127.0.0.1:5984
 
-The Host header is required by HTTP 1.1. It tells the server the hostname that came with the request.::
+.. The Host header is required by HTTP 1.1. It tells the server the hostname that came with the request.::
+
+HostヘッダーはHTTP 1.1のために必要です。これは、リクエストとともに来たホスト名をサーバーに知らせます。
+
+::
 
   > Accept: */*
 
-The Accept header tells CouchDB that curl accepts any media type. We’ll look into why this is useful a little later.::
+.. The Accept header tells CouchDB that curl accepts any media type. We’ll look into why this is useful a little later.::
+
+AcceptヘッダーはCouchDBに、curlがどんなメディアタイプでも受け取ることを知らせます。少し後に、何故これが便利なのかを見ていきます。
+
+::
 
   >
 
-An empty line denotes that the request headers are now finished and the rest of the request contains data we’re sending to the server. In this case, we’re not sending any data, so the rest of the curl output is dedicated to the HTTP response.::
+.. An empty line denotes that the request headers are now finished and the rest of the request contains data we’re sending to the server. In this case, we’re not sending any data, so the rest of the curl output is dedicated to the HTTP response.::
+
+空の行は、リクエストヘッダーがここで終わりであり、残りのリクエストがサーバーに送信されたデータを含んでいることを表します。このケースでは、私たちは何もデータを送っていないので、残りのcurlの出力にはHTTPレスポンスだけが含まれています。
+
+::
 
   < HTTP/1.1 201 Created
 
-The first line of CouchDB’s HTTP response includes the HTTP version information (again, to acknowledge that the requested version could be processed), an HTTP status code, and a status code message. Different requests trigger different response codes. There’s a whole range of them telling the client (curl in our case) what effect the request had on the server. Or, if an error occurred, what kind of error. RFC 2616 (the HTTP 1.1 specification) defines clear behavior for response codes. CouchDB fully follows the RFC.
+.. The first line of CouchDB’s HTTP response includes the HTTP version information (again, to acknowledge that the requested version could be processed), an HTTP status code, and a status code message. Different requests trigger different response codes. There’s a whole range of them telling the client (curl in our case) what effect the request had on the server. Or, if an error occurred, what kind of error. RFC 2616 (the HTTP 1.1 specification) defines clear behavior for response codes. CouchDB fully follows the RFC.
 
-The 201 Created status code tells the client that the resource the request was made against was successfully created. No surprise here, but if you remember that we got an error message when we tried to create this database twice, you now know that this response could include a different response code. Acting upon responses based on response codes is a common practice. For example, all response codes of 400 or larger tell you that some error occurred. If you want to shortcut your logic and immediately deal with the error, you could just check a >= 400 response code.::
+CouchDBのHTTPレスポンスの最初の行はHTTPバージョンの情報(繰り返しになりますが、リクエストされたバージョンが処理できたことを知らせます)、HTTPステータスコード、そしてステータスコードメッセージです。異なったリクエストには異なったレスポンスコードが返されます。これらのすべてが、リクエストがサーバーにどのような影響を与えるのかをクライアント(私たちのケースではcurlです)に知らせます。また、エラーが起きた場合には、どのような種類のエラーかを知らせます。RFC 2616(HTTP 1.1の仕様)はレスポンスコードの振る舞いについて明確に定義します。CouchDBはRFCに完全に従います。
+
+.. The 201 Created status code tells the client that the resource the request was made against was successfully created. No surprise here, but if you remember that we got an error message when we tried to create this database twice, you now know that this response could include a different response code. Acting upon responses based on response codes is a common practice. For example, all response codes of 400 or larger tell you that some error occurred. If you want to shortcut your logic and immediately deal with the error, you could just check a >= 400 response code.::
+
+201 Createdステータスコードはクライアントに、リクエストが作成されたリソースが正常に作成されたことを知らせます。何も驚くことはありませんが、このデータベースを2回作成しようとしたとき、エラーメッセージを見たことを思い出せば、そのレスポンスは異なったレスポンスコードを含んでいたことが今は分かります。レスポンスコードに基づいたレスポンスに従うことは、一般的な慣習です。例えば、400以上のすべてのレスポンスコードは、何らかのエラーが起こったことを知らせます。もし、ロジックをショートカットし、すぐにエラーに対処したいのであれば、単に>= 400レスポンスコードをチェックすることができます。
+
+::
 
   < Server: CouchDB/0.10.1 (Erlang OTP/R13B)
 
-The Server header is good for diagnostics. It tells us which CouchDB version and which underlying Erlang version we are talking to. In general, you can ignore this header, but it is good to know it’s there if you need it.::
+.. The Server header is good for diagnostics. It tells us which CouchDB version and which underlying Erlang version we are talking to. In general, you can ignore this header, but it is good to know it’s there if you need it.::
+
+Serverヘッダーは診断に有用です。これは、通信しているCouchDBのバージョンとその基礎となるErlangのバージョンを知らせます。一般的に、あなたはこのヘッダーを無視することができますが、必要なときにここにあるということを知っておくのは良いことです。
+
+::
 
   < Date: Sun, 05 Jul 2009 22:48:28 GMT
 
-The Date header tells you the time of the server. Since client and server time are not necessary synchronized, this header is purely informational. You shouldn’t build any critical application logic on top of this!::
+.. The Date header tells you the time of the server. Since client and server time are not necessary synchronized, this header is purely informational. You shouldn’t build any critical application logic on top of this!::
+
+Dateヘッダーはサーバーの時間を知らせます。クライアントの時間とサーバーの時間とは同期している必要はないので、このヘッダーは純粋に情報提供です。これを基に重要なアプリケーションロジックを構築すべきではありません!
+
+::
 
   < Content-Type: text/plain;charset=utf-8
 
-The Content-Type header tells you which MIME type the HTTP response body is and its encoding. We already know CouchDB returns JSON strings. The appropriate Content-Type header is application/json. Why do we see text/plain? This is where pragmatism wins over purity. Sending an application/json Content-Type header will make a browser offer you the returned JSON for download instead of just displaying it. Since it is extremely useful to be able to test CouchDB from a browser, CouchDB sends a text/plain content type, so all browsers will display the JSON as text.
+.. The Content-Type header tells you which MIME type the HTTP response body is and its encoding. We already know CouchDB returns JSON strings. The appropriate Content-Type header is application/json. Why do we see text/plain? This is where pragmatism wins over purity. Sending an application/json Content-Type header will make a browser offer you the returned JSON for download instead of just displaying it. Since it is extremely useful to be able to test CouchDB from a browser, CouchDB sends a text/plain content type, so all browsers will display the JSON as text.
 
-There are some browser extensions that make your browser JSON-aware, but they are not installed by default.
+Content-TypeヘッダーはHTTPレスポンスの本文がどのMIMEタイプなのか、とそのエンコーディングを知らせます。私たちはすでにCouchDBがJSON文字列を返すことを知っています。適切なContent-Typeヘッダーはapplication/jsonです。何故text/plainになっているのでしょう?ここは現実主義が純粋性に勝利するところです。application/json Content-Typeヘッダーを送ると、ブラウザーはそれを単純に表示する代わりに返されたJSONをダウンロードさせようとするでしょう。CouchDBをブラウザーからテストするためには非常に便利なので、すべてのブラウザーがJSONをテキストとして表示するように、CouchDBはtext/plainコンテンツタイプを送信します。
 
-Do you remember the Accept request header and how it is set to \*/\* -> */* to express interest in any MIME type? If you send Accept: application/json in your request, CouchDB knows that you can deal with a pure JSON response with the proper Content-Type header and will use it instead of text/plain.::
+.. There are some browser extensions that make your browser JSON-aware, but they are not installed by default.
+
+ブラウザーのJSON対応にするためのブラウザー拡張もありますが、それらは標準でインストールされてはいません。
+
+.. Do you remember the Accept request header and how it is set to \*/\* -> */* to express interest in any MIME type? If you send Accept: application/json in your request, CouchDB knows that you can deal with a pure JSON response with the proper Content-Type header and will use it instead of text/plain.::
+
+Acceptリクエストヘッダーと、任意のMIMEタイプへの関心を表現するためにそれを\\\*/\\\* -> \*/\*に設定する方法を覚えているでしょうか。リクエストをAccept: application/jsonとして送信した場合、CouchDBはあなたが適切なContent-Typeの付いた純粋なJSONレスポンスを扱うことができると理解し、text/plainの代わりにそれを使うでしょう。
+
+::
 
   < Content-Length: 12
 
-The Content-Length header simply tells us how many bytes the response body has.::
+.. The Content-Length header simply tells us how many bytes the response body has.::
+
+Content-Lengthヘッダーは単にレスポンスの本文が何バイトであるかを知らせます。
+
+::
 
   < Cache-Control: must-revalidate
 
-This Cache-Control header tells you, or any proxy server between CouchDB and you, not to cache this response.::
+.. This Cache-Control header tells you, or any proxy server between CouchDB and you, not to cache this response.::
+
+このCache-Controlヘッダーは、あなたやCouchDBとあなたとの間にあるプロキシーサーバーにこのレスポンスをキャッシュしないよう指示します。
+
+::
 
   <
 
-This empty line tells us we’re done with the response headers and what follows now is the response body.::
+.. This empty line tells us we’re done with the response headers and what follows now is the response body.::
+
+この空の行はレスポンスヘッダーが終了したことと、この後にレスポンスの本文が続くことを知らせます。
+
+::
 
   {"ok":true}
 
-We’ve seen this before.::
+.. We’ve seen this before.::
+
+これは前に見ました。
+
+::
 
   * Connection #0 to host 127.0.0.1 left intact
   * Closing connection #0
 
-The last two lines are curl telling us that it kept the TCP connection it opened in the beginning open for a moment, but then closed it after it received the entire response.
+.. The last two lines are curl telling us that it kept the TCP connection it opened in the beginning open for a moment, but then closed it after it received the entire response.
 
-Throughout the book, we’ll show more requests with the -v option, but we’ll omit some of the headers we’ve seen here and include only those that are important for the particular request.
+最後の2行はcurlに、最初に開いたTCP接続をしばらく維持していたが、すべてのレスポンスを受け取った後でこれを閉じたということを知らせます。
 
-Creating databases is all fine, but how do we get rid of one? Easy—just change the HTTP method:::
+.. Throughout the book, we’ll show more requests with the -v option, but we’ll omit some of the headers we’ve seen here and include only those that are important for the particular request.
+
+この本を通して、私たちはより多くのリクエストを-vオプション付きで示しますが、ここで見たヘッダーのいくつかは省略し、特定のリクエストについて重要なもののみを含みます。
+
+.. Creating databases is all fine, but how do we get rid of one? Easy—just change the HTTP method:::
+
+データベースの作成はすべて成功しましたが、削除はどのようにするのでしょうか。簡単です。単にHTTPメソッドを次のように変更します。
+
+::
 
   > curl -vX DELETE http://127.0.0.1:5984/albums-backup
 
-This deletes a CouchDB database. The request will remove the file that the database contents are stored in. There is no “Are you sure?” safety net or any “Empty the trash” magic you’ve got to do to delete a database. Use this command with care. Your data will be deleted without a chance to bring it back easily if you don’t have a backup copy.
+.. This deletes a CouchDB database. The request will remove the file that the database contents are stored in. There is no “Are you sure?” safety net or any “Empty the trash” magic you’ve got to do to delete a database. Use this command with care. Your data will be deleted without a chance to bring it back easily if you don’t have a backup copy.
 
-This section went knee-deep into HTTP and set the stage for discussing the rest of the core CouchDB API. Next stop: documents.
+これはCouchDBのデータベースを削除します。このリクエストはデータベースの内容が保存されているファイルを削除します。データベースを削除するとき、「本当に削除しますか」というセーフティーネットや、「ゴミ箱を空にする」のような魔法はありません。このコマンドは注意して使用してください。バックアップコピーを持っていなければ、あなたのデータは簡単に元に戻すチャンスなしに削除されるでしょう。
+
+.. This section went knee-deep into HTTP and set the stage for discussing the rest of the core CouchDB API. Next stop: documents.
+
+このセクションではHTTPについて膝の深さまで行き、コアCouchDB APIの残りを議論するための足場を組みました。次の停留所は、ドキュメントです。
 
 Documents
 ~~~~~~~~~