如果说Etcd数据存储服务是CoreOS分布式架构的基石，那么Etcd的RESTful API就是架在这基石上的顶梁立柱。由于CoreOS中的许多分布式应用都会使用Etcd作为其存储配置的地方，对于一个普通的运维人员，熟练的使用etcdctl工具已经可以完成很多系统配置的任务。为什么还要单独的一篇来介绍Etcd的API体系呢？一方面来说，ectdctl实现功能的只是Etcd API的一个子集（例如不支持指定监控事件的起始时间），因此Etcd API的内容可以看做是前一篇的锦上添花。另一方面，etcdctl是Etcd API的CLI（Command Line Interface）实现，比较适合通过脚本和配置管理工具运行，却不适合在一般的编程语言当中直接使用。相比ZooKeeper提供特定语言Library扩展支持，Etcd API采用的是通用的HTTP协议和Json数据格式，几乎没有编程语言的限制，也使得基于Etcd的二次开发应用更加容易调试，甚至只需简单的curl命令行工具便能测试这些API的返回结果。

额外说明：正所谓计划赶不上变化，正在写作这篇文章的同时，Etcd官方的Github版本库恰好也已经将v2.0的文档合并到了 ，距离Etcd的V2.0版本发布又近了一步。但截止目前，即便在Alpha发布通道上Etcd V2.0尚不可用，出于示例的真实性考虑，本篇的内容将依然采用V0.4的API为例。Etcd V2.0（原V0.5）API与此前的V0.4 API基本兼容，其中最大的却别在于其规范了端口号码的使用（已经写入 ，感谢百度段兵指出这个出处）。提供给外部客户端的端口变为2379，而用于Etcd服务间通信的端口变为2380（在V0.4版本中分别为4001和7001）。以下例子中API与V2.0版本不兼容的地方将单独指出。

初识Etcd RESTful API

RESTful API是基于HTTP协议和Json格式的无状态应用程序接口，比如在一个运行了CoreOS的节点上，使用curl（或浏览器）访问地址http://127.0.0.1:4001/version，就能得到当前节点运行的Etcd服务版本。

core@core-01 ~ $ curl -L  etcd 0.4.6

这个curl命令中的 -L 参数表示如果遇到重定向，应该跟随到重定向后的地址访问。需要指出的是，Etcd的文档中所有curl访问的例子都没有使用 -L 参数，但在实际的测试中发现，有些API（特别是PUT和POST操作的那些）如果不使用 -L 时是不能生效的，这一点可能是Etcd文档的错误。

• 增删改查

注意到没有？刚刚获得Etcd版本的调用返回值是版本号的字符串，没有使用Json格式，因此它是一个特殊的API。一般来说，Etcd API路径的一部分始终是API的版本号，对于V0.1以后的Etcd版本，包括V0.4和V2.0使用的都是第2版的API，因此这个根路径是 /v2/。第二级路径是API的分类，对于键值和目录的API，这个分类路径是 /keys/，即完整的路径为 /v2/keys/。而对数据的增、删、改、查操作是通过 HTTP 的访问方式和参数区别。

例如通过 HTTP GET 方式访问 /v2/keys/ 路径将返回Etcd数据存储结构中根路径上的所有键和目录。

core@core-01 ~ $ curl -L  { 

"action":"get", 

"node":{ 

  "key":"/", 

  "dir":true, 

  "nodes":[{ 

  "key":"/coreos.com", 

  "dir":true, 

  "modifiedIndex":6, 

  "createdIndex":6 

  }] 

} 

}

我们访问的路径 /v2/keys/ 表示的是Etcd根目录，相应的 /v2/keys/coreos.com/则表示Etcd中的/coreos.com目录。输出结果中的node.nodes是一个目录中所有键和子目录的列表。

上面的Json结果使用了缩进格式排版，实际的输出格式是压缩过的Json文本。关于控制台Json输出的格式化会在篇末的部分介绍。

这里API路径最后的那个反斜杠号表示访问Etcd的根目录，不能省略，否则会出现404 Not Found错误。对于访问的是非根目录的时候，最后的反斜杠则可有可无。可以通过参数来获得不一样的结果，下面的例子可以递归打印所有目录和子目录内容。

core@core-01 ~ $ curl -L  { 

  "action": "get", 

  "node": { 

  "key": "/coreos.com", 

  "dir": true, 

  "nodes": [{ 

  "key": "/coreos.com/updateengine", 

  "dir": true, 

   "nodes": [{ 

  "key": "/coreos.com/updateengine/rebootlock", 

  "dir": true, 

  "nodes": [{ 

  "key": "/coreos.com/updateengine/rebootlock/semaphore", 

  "value": "{\"semaphore\":0,\"max\":1,\"holders\":[\"0acdd9bf38194ea5ad1611ff9a4236f1\"]}", 

  "modifiedIndex": 6, 

  "createdIndex": 6  }], 

  "modifiedIndex": 6, 

  "createdIndex": 6  }], 

  "modifiedIndex": 6, 

  "createdIndex": 6  }] 

  } 

}

对于API调用需要传递附加的参数，需要根据当前使用的HTTP操作类型选择传参的方法。对于GET和DELETE操作可以通过HTTP参数的方式传递，例如上面在GET获取列表时通过参数 recursive=true 来递归列出指定节点下包括子孙节点在内的所有目录和键。对于PUT和POST操作则需要将参数通过HTTP正文发送，在使用curl的时候就是通过 -d或--data来附加参数内容，在后面会使用到具体例子的时候再来说明。

如果通过HTTP GET访问的是一个键而不是目录，就会获得这个键的内容。

core@core-01 ~ $ curl -L { 

  "action": "get", 

  "node": { 

   "key": "/coreos.com/updateengine/rebootlock/semaphore", 

  "value": "{\"semaphore\":0,\"max\":1,\"holders\":[\"0acdd9bf38194ea5ad1611ff9a4236f1\"]}", 

  "modifiedIndex": 6, 

  "createdIndex": 6 

  } 

}

可以看到node.value部分的输出就是这个键存储的内容。

如果使用了PUT或POST方法操作目录所对应的API路径，则可以创建和更新目录或键。但两者有很大的区别。对于大多数的情况，我们应该使用PUT方法，例如新建一个Etcd的键。

core@core-01 ~ $ curl -L  -XPUT -d value="Hey" 

{ 

  "action": "set", 

  "node": { 

  "key": "/path/demo1", 

  "value": "Hey", 

  "modifiedIndex": 248530, 

  "createdIndex": 248530 

  } 

}

注意键的内容是通过HTTP正文的方式传入的（curl的-d或 --data参数），这种参数传递方法适用于所有PUT和POST的操作。创建目录同样通过参数的方法指定，所使用的参数是 dir=true。

core@core-01 ~ $ curl -L  -XPUT -d dir=true 

{ 

  "action": "set", 

  "node": { 

  "key": "/path/demo2", 

  "dir": true, 

  "modifiedIndex": 248955, 

  "createdIndex": 248955 

  } 

}

其实一直到这里，我们有意的回避未提在输出结果中两个反复出现的数据单元modifiedIndex和createdIndex。这两个数据分别表示键或目录的最后修改时间和创建时间。但它们的变化规律可能和许多人直观感觉的不太一样（并且文档中对于这部分内容阐述得并不十分清晰），下面是关于这两个值的一些特点。

• 首先，Etcd记录的每一个目录或键都有这两个属性，它们都是只增不减的整型数字；
• 其次，其值与目录或键的创建时间和修改时间正相关，同时被创建的目录或键可能会有相同的modifiedIndex和createdIndex（只会在父子目录出现这种相同的情况）；
• 细心的用户也许还会发现，这两个值并不是在集群全局一致的，在同一个集群的不同节点上查看同一个键或目录获得的值并不相同；
• 同样两个键或目录的Index值之间相减的差始终是一样的，也就是说，顺序和相对位置始终是一致的；
• 最后，对同一个键进行多次PUT操作，它的modifiedIndex和createdIndex值会同时增加，并保持相等，而不仅仅是想直觉认为的只增加modifiedIndex的数值。

关于上面的最后一点，实际的原因是，直接PUT一个已经存在的键，默认的操作是覆写（而不是更新）原本的键。也就是说Etcd会新建一个键放到指定的位置上替代原来的那个，因此代表创建时间的createdIndex值也相应的变化了。在大多数情况下，使用者不会去关心这点差别，但任然要指出的是，如果用户确实希望原地更新这个键的内容，需要在PUT时加上 prevExist=true参数。

core@core-01 ~ $ curl -L  -XPUT -d value="New" -d prevExist=true 

{ 

  "action": "update", 

  "node": { 

  "key": "/path/demo1", 

  "value": "New", 

"modifiedIndex": 248675, 

"createdIndex": 248530 

  }, 

  "prevNode": { 

  "key": "/path/demo1", 

  "value": "Hey", 

  "modifiedIndex": 248530, 

  "createdIndex": 248530 

  } 

}

POST操作的作用是创建一组以有序数值为键的序列，说起来比较抽象，举个例子。

curl -L  -XPOST -d value="Val1" 

curl -L  -XPOST -d value="Val2" 

curl -L  -XPOST -d value="Val3" 

curl -L  { 

  "action": "get", 

  "node": { 

  "key": "/path/demo", 

  "dir": true, 

  "nodes": [{ 

  "key": "/path/demo/206981", 

  "value": "Val3", 

  "modifiedIndex": 206981, 

  "createdIndex": 206981 

  }, { 

  "key": "/path/demo/206975", 

  "value": "Val1", 

  "modifiedIndex": 206975, 

  "createdIndex": 206975 

  }, { 

  "key": "/path/demo/206978", 

  "value": "Val2", 

  "modifiedIndex": 206978, 

  "createdIndex": 206978 

  }], 

  "modifiedIndex": 206975, 

  "createdIndex": 206975 

  } 

}

可以看到在指定的 /path/demo 目录下创建了三个以相应的 createdIndex 同名的键，而键的值是POST操作时设置的内容。这样做的好处是确保了生成存放内容的键依照创建顺序命名，只有在一些对内容顺序敏感的应用场景，这个功能才能够发挥实际的价值。

删除Etcd键和目录的方法是使用HTTP DELETE操作访问相应的URL。对于目录的删除需要加上dir=true 参数，而删除非空的目录还需要再加上 recursive=true参数。

core@core-01 ~ $ curl -L  -XDELETE 

{ 

  "action": "delete", 

  "node": { 

  "key": "/path/demo", 

  "dir": true, 

  "modifiedIndex": 207070, 

  "createdIndex": 206975 

  }, 

  "prevNode": { 

  "key": "/path/demo", 

  "dir": true, 

  "modifiedIndex": 206975, 

  "createdIndex": 206975 

  } 

}

注意，在 Shell 中输入GET或DELETE操作的多个参数时，连接参数的 & 符号需要转义，即写成 \&，见上面命令的例子。 

• 拥抱变化

Etcd API对数据节点操作的其他高级功能上在etcdctl工具中的大部分都有对应的命令，比如监视数据节点变化、设置TTL、原子读写等，没有特别新鲜的新货，大家可直接查询Etcd文档，不在这里枉添篇幅。然而其中有一点依然值得提出与君共赏，那就是Etcd API中的监控变化功能中，提供了个etcdctl里没有的东西：指定监控的时间起点。

试想这样一种情况，用户编写的一个程序通过etcdctl watch命令的方式在循环中等待指定数据节点的变化，当变化发生之后，这个程序开始执行另一端代码处理这个变化。然而，在这个部分的处理还未完成之前，一个新的变化到来了，等到程序完成处理后继续回到下一次 etcdctl watch时，它完全不知道自己刚刚错过了一次数据变化的时间。而指定监控变化的时间起点就能够解决这个问题。

在GET获取数据的时候，加上参数wait=true就能够等待在特定的值上，直到变化发生才返回监控变化后的内容。例如在core-01节点上监控/path/demo1键的变化。

core@core-01 ~ $ curl -L 

然后在core-02节点上对/path/demo1键进行更新。

core@core-02 ~ $ curl -L  -XPUT -d value=”New”

此时在core-01监视的操作会立即返回，curl会在屏幕上打印出此次变化的内容。

{ 

  "action": "set", 

  "node": { 

  "key": "/path/demo1", 

  "value": "Hey", 

  "modifiedIndex": 248640, 

  "createdIndex": 248640 

  }, 

  "prevNode": { 

  "key": "/path/demo1", 

  "value": "Hey", 

  "modifiedIndex": 248530, 

  "createdIndex": 248530 

  } 

}

用户通过Etcd API获得的内容比etcdctl 工具多了一些内容，其中包含数据节点的modifiedIndex和createdIndex。因此除了简单的监控，直接使用API还可以指定一个监控变化的起始时间。通过waitIndex=<参考时间>参数传入。一般来说会使用前一次获得数据节点的 modifiedIndex 值加1作为参考时间的值，即当这个数据节点的 modifiedIndex 大于或等于其原本多1时（即说明发生了变化），就立即返回。

core@core-01 ~ $ curl -L 

这样即便在两次监听的间隔区发生了数据变化，应用程序任然可以正确的获得通知消息。 

• 集群的统计信息

除了对数据节点进行操作，通过Etcd API还能够获得一些有用的集群信息。这些信息的API都在/v2/stats/ 路径下面。例如访问 /v2/stats/leader路径可以获得集群通过 Raft 选举的Leader节点、Follower节点的ID及网络延时等信息。

core@core-01 ~ $ curl -L  { 

  "leader": "0acdd9bf38194ea5ad1611ff9a4236f1", 

  "followers": { 

  "f2558aaa231044f3abbe01510ac2b1d8": { 

  ... ... 

  }, 

  "f260afd8224c4854bdf8427d8451da23": { 

  ... ... 

  } 

  } 

}

而访问 /v2/stats/self路径将得到一些关于当前所在节点与集群有关的信息。

core@core-01 ~ $ curl -L  { 

  "name": "f2558aaa231044f3abbe01510ac2b1d8", 

  "state": "follower", 

  "startTime": "2015-01-17T16:22:02.814304197Z", 

  "leaderInfo": { 

  "leader": "0acdd9bf38194ea5ad1611ff9a4236f1", 

  "uptime": "69h22m13.913201673s", 

  "startTime": "2015-01-19T16:20:29.297796915Z" 

  }, 

  "recvAppendRequestCnt": 2457288, 

  "recvPkgRate": 20.100779810395967, 

  "recvBandwidthRate": 1410.8737348916932, 

  "sendAppendRequestCnt": 562007 

}

其中的 recvBandwidthRate / recvPkgRate这个节点与 Leader 通信的速度，单位分别是每秒的字节数和每秒的请求数。如果当前节点是Leader节点，则看到的是sendBandwidthRate / sendPkgRate，但含义基本相同。这些数据对于排查集群中的一些问题具有参考作用。

路径 /v2/stats/store 可以获得整个集群的所有Etcd API请求次数的统计数据，这个数据对于普通用户没有太多的价值，而一般是用于评价和分析集群的健康度时提供一些有用的数据。

core@core-01 ~ $ curl -L  { 

  "getsSuccess": 547387, 

  "getsFail": 17829, 

  "setsSuccess": 69650, 

 "setsFail": 6, 

  ... ... 

  "expireCount": 139, 

  "watchers": 0 

}