Couchdb 简明教程

CouchDB - Curl & Futon

cURL Utility

cURL 实用程序是一种与 CouchDB 通信的方法。

cURL utility is a way to communicate with CouchDB.

它是一种使用支持协议（HTTP、HTTPS、FTP、FTPS、TFTP、DICT、TELNET、LDAP 或 FILE）之一，从服务器或向服务器传输数据的工具。这个命令设计为无需用户互动即可工作。cURL 提供了一系列的实用技巧，如代理支持、用户认证、ftp 上传、HTTP Post、SSL (https:) 连接、cookie、文件传输恢复等。

It is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, FTP, FTPS, TFTP, DICT, TELNET, LDAP or FILE). The command is designed to work without user interaction. cURL offers a busload of useful tricks like proxy support, user authentication, ftp upload, HTTP post, SSL (https:) connections, cookies, file transfer resume and more.

cURL 实用程序在 UNIX、Linux、Mac OS X 和 Windows 等操作系统中可用。它是一个命令行实用程序，用户可以用它直接从命令行访问 HTTP 协议。本章将指导你如何使用 cURL 实用程序。

The cURL utility is available in operating systems such as UNIX, Linux, Mac OS X and Windows. It is a command line utility using which user can access HTTP protocol straight away from the command line. This chapter teaches you how to use cURL utility.

Using cURL Utility

你可以通过简单地输入 cURL 及其后跟网站地址来使用 cURL 实用程序访问任何网站，如下所示：−

You can access any website using cURL utility by simply typing cURL followed by the website address as shown below −

curl www.tutorialspoint.com/

默认情况下，cURL 实用程序返回请求页面源代码。它在终端窗口中显示此代码。

By default, the cURL utility returns the source code of the requested page. It displays this code on the terminal window.

cURL Utility Options

cURL 实用程序提供多种选项供使用，你可以在 cURL 使用帮助中查看它们。

cURL utility provides various options to work with, and you can see them in cURL utility help.

以下代码展示了 cURL 帮助的其中一部分。

The following code shows some portion of cURL help.

$ curl --help
Usage: curl [options...] <url>
Options: (H) means HTTP/HTTPS only, (F) means FTP only
      --anyauth Pick "any" authentication method (H)
   -a/--append Append to target file when uploading (F/SFTP)
      --basic Use HTTP Basic Authentication (H)
      --cacert <file> CA certificate to verify peer against (SSL)
-d/--data <data> HTTP POST data (H)
      --data-ascii <data> HTTP POST ASCII data (H)
      --data-binary <data> HTTP POST binary data (H)
      --data-urlencode <name=data/name@filename> HTTP POST data
urlencoded (H)
      --delegation STRING GSS-API delegation permission
      --digest Use HTTP Digest Authentication (H)
      --disable-eprt Inhibit using EPRT or LPRT (F)
      --disable-epsv Inhibit using EPSV (F)

   -F/--form <name=content> Specify HTTP multipart POST data (H)
      --form-string <name=string> Specify HTTP multipart POST data (H)
      --ftp-account <data> Account data to send when requested by server
(F)
      --ftp-alternative-to-user <cmd> String to replace "USER [name]" (F)
      --ftp-create-dirs Create the remote dirs if not present (F)
      --ftp-method [multi cwd/no cwd/single cwd] Control CWD usage (F)
      --ftp-pasv Use PASV/EPSV instead of PORT (F)

   -G/--get Send the -d data with a HTTP GET (H)

   -H/--header <line> Custom header to pass to server (H)
   -I/--head Show document info only
   -h/--help This help text
      --hostpubmd5 <md5> Hex encoded MD5 string of the host public key.
(SSH)
   -0/--http1.0 Use HTTP 1.0 (H)
      --ignore-content-length Ignore the HTTP Content-Length header
   -i/--include Include protocol headers in the output (H/F)

   -M/--manual Display the full manual

   -o/--output <file> Write output to <file> instead of stdout
      --pass <pass> Pass phrase for the private key (SSL/SSH)
      --post301 Do not switch to GET after following a 301
redirect (H)
      --post302 Do not switch to GET after following a 302
redirect (H)
   -O/--remote-name Write output to a file named as the remote file
      --remote-name-all Use the remote file name for all URLs
   -R/--remote-time Set the remote file's time on the local output
   -X/--request <command> Specify request command to use
      --retry <num> Retry request <num> times if transient problems
occur
      --retry-delay <seconds> When retrying, wait this many seconds
between each
      --retry-max-time <seconds> Retry only within this period
   -T/--upload-file <file> Transfer <file> to remote site
      --url <URL> Set URL to work with
   -B/--use-ascii Use ASCII/text transfer

在与 CouchDB 通信时，我们大量地使用了 cURL 实用程序的某些选项。以下是 cURL 实用程序部分重要选项的简要说明，包括 CouchDB 使用的选项。

While communicating with CouchDB, certain options of cURL utility were extensively used. Following are the brief descriptions of some important options of cURL utility including those used by CouchDB.

-X flag

(HTTP) 指定在与 HTTP 服务器通信时使用的自定义请求方法。已指定请求代替已使用的方法（默认为 GET）。完整信息和解释，请阅读 HTTP 1.1 规范。

(HTTP) Specifies a custom request method used when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET). Read the HTTP 1.1 specification for details and explanations.

(FTP) 与使用 ftp 进行文件列表时指定一个自定义 FTP 命令，以代替 LIST。

(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with ftp.

-H

(HTTP) 获取网页时使用额外的报头。注意，如果你添加了一个自定义报头，该报头与 cURL 将要使用的内部报头具有相同的名称，那么你的外部设置报头将代替内部报头。这使你可以完成 cURL 通常无法完成的即使更加棘手的操作。你不应该在不明白自己所做的事情的情况下替换内部设置报头。用冒号右侧没有内容的报头替换内部报头将防止该报头出现。

(HTTP) Extra header is used when getting a web page. Note that if you add a custom header that has the same name as one of the internal ones cURL would use, your externally set header will be used instead of the internal one. This allows you to make even trickier work than cURL would normally do. You should not replace internally set headers without perfectly knowing what you’re doing. Replacing an internal header with the one without content on the right side of the colon, will prevent that header from appearing.

cURL 确保你添加/替换的每个报头使用适当的行尾标记发送。你也不应该将此作为报头内容的一部分添加，也不应该添加换行符或回车符来弄乱。

cURL assures that each header you add/replace get sent with the proper end of line marker. Neither you should add that as a part of the header content nor add newlines or carriage returns to disorder things.

另请参阅 -A/--user-agent 和 -e/--referer 选项。

See also the -A/--user-agent and -e/--referer options.

此选项可以多次使用，以添加/替换/删除多个报头。

This option can be used multiple times to add/replace/remove multiple headers.

-d flag

使用 cURL 的此标记，你可以将数据与 HTTP POST 请求一起发送到服务器，就好像用户通过表单填写并提交数据一样。

Using this flag of cURL, you can send data along with the HTTP POST request to the server, as if it was filled by the user in the form and submitted.

Example

假设有一个网站，你想使用以下 cURL 实用程序的 –d 标记登录其中或向该网站发送一些数据。

Suppose there is a website and you want to login into it or send some data to the website using –d flag of cURL utility as shown below.

curl -X PUT http://mywebsite.com/login.html -d userid=001 -d password=tutorialspoint

它发送一个看起来像 "userid=001&password=tutorialspoint" 的 post 块。同样地，你也可以使用 -d 标记发送文档 (JSON)。

It sends a post chunk that looks like "userid=001&password=tutorialspoint". Likewise you can also send documents (JSON ) using -d flag.

-o flag

使用此标志，cURL 将请求输出写入文件。

Using this flag, cURL writes the output of the request to a file.

Example

以下示例显示了 cURL 实用工具的 -o 标志的用法。

The following example shows the use of -o flag of cURL utility.

$ curl -o example.html www.tutorialspoint.com/index.htm
% Total % Received % Xferd Average Speed Time Time Time Current
      Dload Upload Total Spent Left Speed
100 81193 0 81193 0 0 48168 0 --:--:-- 0:00:01 --:--:--
58077

它获取 tutorialspoint.com 主页的源代码，创建一个名为 example.com 的文件并将输出保存在名为 example.html 的文件中。

This gets the source code of the homepage of tutorialspoint.com, creates a file named example.com and saves the output in the file named example.html.

以下是 example.html 的快照。

Following is the snapshot of the example.html.

-O

此标志类似于 –o ，唯一的区别是使用此标志，会创建一个与请求的 URL 同名的文件，并将请求的 URL 的源代码复制到其中。

This flag is similar to –o, the only difference is with this flag, a new file with the same name as the requested url was created, and the source code of the requested url will be copied to it.

Example

以下示例显示了 cURL 实用工具的 -O 标志的用法。

The following example shows the use of -O flag of cURL utility.

$ curl -O www.tutorialspoint.com/index.htm
% Total % Received % Xferd Average Speed Time Time Time Current
      Dload Upload Total Spent Left
Speed
100 81285 0 81285 0 0 49794 0 --:--:-- 0:00:01 --:--:--
60077

它创建一个名为 index.htm 的文件，并将 tutorialspoint.com 索引页的源代码保存在其中。

It creates a new file with the name index.htm and saves the source code of the index page of tutorialspoint.com in it.

Hello CouchDB

您可以通过向已安装的 CouchDB 实例发送 GET 请求来访问 CouchDB 主页。首先，确保您已在 Linux 环境中安装 CouchDB 并且它运行成功，然后使用以下语法向 CouchDB 实例发送 get 请求。

You can access the homepage of the CouchDB by sending a GET request to the CouchDB instance installed. First of all make sure you have installed CouchDB in your Linux environment and it is running successfully, and then use the following syntax to send a get request to the CouchDB instance.

curl http://127.0.0.1:5984/

这会向您提供如以下所示的 JSON 文档，其中 CouchDB 指定了详细信息，例如版本号、供应商名称和软件版本。

This gives you a JSON document as shown below where CouchDB specifies the details such as version number, name of the vendor, and version of the software.

$ curl http://127.0.0.1:5984/
{
   "couchdb" : "Welcome",
   "uuid" : "8f0d59acd0e179f5e9f0075fa1f5e804",
   "version" : "1.6.1",
   "vendor" : {
      "name":"The Apache Software Foundation",
      "version":"1.6.1"
   }
}

List of All Databases

您可以发送 get 请求以及字符串 "_all_dbs string " ，以获取所创建的所有数据库的列表。以下是要获取 CouchDB 中所有数据库列表的语法。

You can get the list of all the databases created, by sending a get request along with the string "_all_dbs string ". Following is the syntax to get the list of all databases in CouchDB.

curl -X GET http://127.0.0.1:5984/_all_dbs

它向您提供以下所示的 CouchDB 中所有数据库的列表。

It gives you the list of all databases in CouchDB as shown below.

$ curl -X GET http://127.0.0.1:5984/_all_dbs
[ "_replicator" , "_users" ]

Creating a Database

您可以使用具有以下语法的 PUT 标头的 cURL 在 CouchDB 中创建数据库 −

You can create a database in CouchDB using cURL with PUT header using the following syntax −

$ curl -X PUT http://127.0.0.1:5984/database_name

Example

例如，使用上述给定的语法，创建一个名为 my_database 的数据库，如下所示。

As an example, using the above given syntax create a database with name my_database as shown below.

$ curl -X PUT http://127.0.0.1:5984/my_database
{"ok":true}

Verification

通过列出所有数据库，验证数据库是否已创建，如下所示。在这里，您可以在列表中看到新创建的数据库 "my_database" 的名称。

Verify whether the database is created, by listing out all the databases as shown below. Here you can observe the name of newly created database, "my_database" in the list

$ curl -X GET http://127.0.0.1:5984/_all_dbs

[ "_replicator " , "_users" , "my_database" ]

Getting Database Info

您可以使用 get 请求以及数据库名称来获取数据库的信息。以下是要获取数据库信息的语法。

You can get the information about database using the get request along with the database name. Following is the syntax to get the database information.

Example

例如让我们获取名为 my_database 的数据库的信息，如下所示。在这里，您可以得到您的数据库信息的响应。

As an example let us get the information of the database named my_database as shown below. Here you can get the information about your database as a response.

$ curl -X GET http://127.0.0.1:5984/my_database

{
   "db_name" : "my_database",
   "doc_count" : 0,
   "doc_del_count" : 0,
   "update_seq" : 0,
   "purge_seq" : 0,
   "compact_running" : false,
   "disk_size" : 79,
   "data_size" : 0,
   "instance_start_time" : "1423628520835029",
   "disk_format_version" : 6,
   "committed_update_seq" : 0
 }

Futon

Futon 是 CouchDB 内置的基于 Web 的管理界面。它提供了一个简单的图形界面，可用于与 CouchDB 交互。它是一个朴素的界面，并提供了对所有 CouchDB 功能的完全访问。以下是这些功能的列表 −

Futon is the built-in, web based, administration interface of CouchDB. It provides a simple graphical interface using which you can interact with CouchDB. It is a naive interface and it provides full access to all CouchDB features. Following is the list of those features −

Creates databases.
Destroys databases.
Creates documents.
Updates documents.
Edits documents.
Deletes documents.

Starting Futon

确保 CouchDB 正在运行，然后在浏览器中打开以下 URL −

Make sure CouchDB is running and then open the following url in browser −

http://127.0.0.1:5984/_utils/

如果您打开此 URL，它将显示以下所示的 Futon 主页 −

If you open this url, it displays the Futon home page as shown below −

On the left hand side of this page you can observe the list of all the current databases of CouchDB. In this illustration, we have a database named my_database, along with system defined databases _replicator and _user.
On the right hand side you can see the following − Tools − In this section you can find Configuration to configure CouchDB, Replicator to perform replications, and Status to verify status of CouchDB and recent modifications done on CouchDB. Documentation − This section contains the complete documentation for the recent version of CouchDB. Diagnostics − Under this you can verify the installation of CouchDB. Recent Databases − Under this you can find the names of recently added databases.