分布式学习（6）etcd@3@ API v3 gRPC_range,put,deleterange

1 gRPC Services 

发送到etcd服务器的每个API请求都是一个gRPC。

在etcd3中的RPCs会根据功能分类到不同的service中。

1.1 Services important for dealing with etcd’s key space include（处理etcd键值空间比较重要的service有以下三点）:

• KV - Creates, updates, fetches, and deletes key-value pairs.（键值的增删改查）
• Watch - Monitors changes to keys.（监查-watch操作）
• Lease - Primitives for consuming client keep-alive messages.（租约）

1.2 Services which manage the cluster itself include（管理集群的service）

• Auth - Role based authentication mechanism for authenticating users.（身份验证机制，用于验证用户）
• Cluster - Provides membership information and configuration facilities. （提供成员资格信息和配置工具）
• Maintenance - Takes recovery snapshots, defragments the store, and returns per-member status information.（维护）

2 Requests and Responses，请求与响应

service KV {
  Range(RangeRequest) returns (RangeResponse)
  ...
}

# 在etcd中的所有的rpc都遵循相同的格式，如上所示，并且所有的响应都需要一个响应头，如下所示：

message ResponseHeader {
  uint64 cluster_id = 1;
  uint64 member_id = 2;
  int64 revision = 3;
  uint64 raft_term = 4;
}

# Cluster_ID  - 应用程序可以读取Cluster_ID或Member_ID字段，以确保它与预期的群集（成员）进行通信；集群id.
# Member_ID   - 应用程序可以读取Cluster_ID或Member_ID字段，以确保它与预期的群集（成员）进行通信；成员id.
# Revision    - 应用程序可以使用该Revision字段来了解键值存储的最新版本；
# Raft_Term   - 应用程序可以Raft_Term用来检测集群何时完成新的领导者选举；

3 Key-Value API，KV_V3_API

3.1 键值对

# 在etcd中都是以键值对的形式存储的，所以最小的操作单位就是key-value的形式，在grpc的表现方式如下所示，下面的message代表一个键值对

message KeyValue {
  bytes key = 1;
  int64 create_revision = 2;
  int64 mod_revision = 3;
  int64 version = 4;
  bytes value = 5;
  int64 lease = 6;
}

# Key             - byte 数据类型不允许空
# Value           - byte 数据类型不允许空
# Version         - 操作时的版本
# Create_Revision - revision of the last creation on the key.
# Mod_Revision    - revision of the last modification on the key.
# Lease           - 租约ID，如果为0，则不存在租约

3.2 增，注意是range的概念，由key和range_end组成

#通过range 来获取KV的值，message如下所示：

message RangeRequest {
  enum SortOrder {
	NONE = 0; // default, no sorting
	ASCEND = 1; // lowest target value first
	DESCEND = 2; // highest target value first
  }
  enum SortTarget {
	KEY = 0;
	VERSION = 1;
	CREATE = 2;
	MOD = 3;
	VALUE = 4;
  }

  bytes key = 1;
  bytes range_end = 2;
  int64 limit = 3;
  int64 revision = 4;
  SortOrder sort_order = 5;
  SortTarget sort_target = 6;
  bool serializable = 7;
  bool keys_only = 8;
  bool count_only = 9;
  int64 min_mod_revision = 10;
  int64 max_mod_revision = 11;
  int64 min_create_revision = 12;
  int64 max_create_revision = 13;
}

#收到的response message如下所示：

message RangeResponse {
  ResponseHeader header = 1;
  repeated mvccpb.KeyValue kvs = 2;
  bool more = 3;
  int64 count = 4;
}

3.3 改：

#request
message PutRequest {
  bytes key = 1;
  bytes value = 2;
  int64 lease = 3;
  bool prev_kv = 4;
  bool ignore_value = 5;
  bool ignore_lease = 6;
}

# response
message PutResponse {
  ResponseHeader header = 1;
  mvccpb.KeyValue prev_kv = 2;
}

3.4 删：

#request
message DeleteRangeRequest {
  bytes key = 1;
  bytes range_end = 2;
  bool prev_kv = 3;
}

#response
message DeleteRangeResponse {
  ResponseHeader header = 1;
  int64 deleted = 2;
  repeated mvccpb.KeyValue prev_kvs = 3;
}

4 gRPC gateway

# put
url = 'http://127.0.0.1:12379/v3/kv/put'
data = '{"key": "test", "value": "test"}'
response = requests.post(url,data)
text = json.loads(response.text)
print(text)

# range
url = 'http://127.0.0.1:12379/v3/kv/range'
data = '{"key": "test"}'
response = requests.post(url,data)
text = json.loads(response.text)
print(text)

5 gRPC-python（https://etcd3-py.readthedocs.io/en/latest/）

pip install etcd3-py
安装过程中的一个问题：
Package 'aiohttp' requires a different Python: 3.5.2 not in '>=3.5.3'
pip3 install async-timeout==2.0.1
pip3 install aiohttp==2.2.0
then OK.....

from etcd3 import Client
client = Client('127.0.0.1', 12379)
print(client.version())
client.put('foo', 'bar')
print(client.range('foo').kvs)

下一节，事物，租约