场景

获取key

> curl http://127.0.0.1:2379/v2/keys/message
{
    "action": "get",
    "node": {
        "createdIndex": 2,
        "key": "/message",
        "modifiedIndex": 2,
        "value": "Hello world"
    }
}

获取dir

> curl http://127.0.0.1:2379/v2/keys/
{
    "action": "get",
    "node": {
        "dir": true,
        "key": "/",
        "nodes": [
            {
                "createdIndex": 2,
                "dir": true,
                "key": "/foo_dir",
                "modifiedIndex": 2
            },
            {
                "createdIndex": 4,
                "key": "/message",
                "modifiedIndex": 4,
                "value": "Hello world"
            }
        ]
    }
}

watch key

# 同时变更 curl http://127.0.0.1:2379/v2/keys/foo -XPUT -d value=bar
> curl 'http://127.0.0.1:2379/v2/keys/foo?wait=true&waitIndex=7'
{
    "action": "set",
    "node": {
        "createdIndex": 7,
        "key": "/foo",
        "modifiedIndex": 7,
        "value": "bar"
    },
    "prevNode": {
        "createdIndex": 6,
        "key": "/foo",
        "modifiedIndex": 6,
        "value": "bar"
    }
}

键值操作

The primary API of etcd is a hierarchical key space. The key space consists of directories and keys which are generically referred to as “nodes”.

The response object contains several attributes:

1. action: the action of the request that was just made. The request attempted to modify node.value via a PUT HTTP request, thus the value of action is set.
2. node.key: the HTTP path to which the request was made. We set /message to Hello world, so the key field is /message. etcd uses a file-system-like structure to represent the key-value pairs, therefore all keys start with /.
3. node.value: the value of the key after resolving the request. In this case, a successful request was made that attempted to change the node’s value to Hello world.
4. node.createdIndex: an index is a unique, monotonically-incrementing integer created for each change to etcd. This specific index reflects the point in the etcd state member at which a given key was created. You may notice that in this example the index is 2 even though it is the first request you sent to the server. This is because there are internal commands that also change the state behind the scenes, like adding and syncing servers.
5. node.modifiedIndex: like node.createdIndex, this attribute is also an etcd index. Actions that cause the value to change include set, delete, update, create, compareAndSwap and compareAndDelete. Since the get and watch commands do not change state in the store, they do not change the value of node.modifiedIndex.

Response Headers

X-Etcd-Index: 35
X-Raft-Index: 5398
X-Raft-Term: 1

• X-Etcd-Index is the current etcd index as explained above. When request is a watch on key space, X-Etcd-Index is the current etcd index when the watch starts, which means that the watched event may happen after X-Etcd-Index.
• X-Raft-Index is similar to the etcd index but is for the underlying raft protocol.
• X-Raft-Term is an integer that will increase whenever an etcd master election happens in the cluster. If this number is increasing rapidly, you may need to tune the election timeout. See the tuning section for details.

Unlike watches we use the X-Etcd-Index + 1 of the response as a waitIndex instead of the node’s modifiedIndex + 1 for two reasons:

1. The X-Etcd-Index is always greater than or equal to the modifiedIndex when getting a key because X-Etcd-Index is the current etcd index, and the modifiedIndex is the index of an event already stored in etcd.
2. None of the events represented by indexes between modifiedIndex and X-Etcd-Index will be related to the key being fetched.

Using the modifiedIndex + 1 is functionally equivalent for subsequent watches, but since it is smaller than the X-Etcd-Index + 1, we may receive a 401 EventIndexCleared error immediately.