ETCD:HTTP JSON API通過gRPC網關

原文地址:HTTP JSON API through the gRPC gateway
etcd v3 使用 gRPC 作為消息協議。etcd項目包括一個基於gRPC的Go客戶端和一個命令行工具，etcdctl,通過gRPC與etcd集群進行交互.對於沒有gRPC支持的語言，etcd提供JSON gRPC網關，這個網關提供一個RESTful風格的代理可以將HTTP/JSON請求轉換為gRPC消息。

使用 gRPC網關

這個網關接受一個到etcd's buffer協議消息定義的JSON格式的映射,注意Key和Value字段定義為byte 數組，因此JSON必須使用base64編碼,下面的例子使用curl,但是每個HTTP/JSON客戶端的工作原理都和例子相同。
注意
gRPC網關節點從etcd v3.3發生變化：

• etcd v3.2以及之前版本只使用[CLIENT-URL]/v3alpha/*。
• etcd v3.3使用[CLIENT-URL]/v3beta/*保持[CLIENT-URL]/v3alpha/*使用。
• etcd v3.4使用[CLIENT-URL]/v3/*保持[CLIENT-URL]/v3beta/*使用。
  • [CLIENT-URL]/v3alpha/*被拋棄使用。
• etcd v3.5以及最新版本只使用[CLIENT-URL]/v3/*。
  • [CLIENT-URL]/v3beta/*被拋棄使用。

存儲和獲取Keys

使用/v3/kv/range和/v3/kv/put服務讀和寫Keys:

<<COMMENThttps://www.base64encode.org/foo is 'Zm9v' in Base64bar is 'YmFy'COMMENT

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}}

curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v"}'# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

# get all keys prefixed with "foo"
curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

查看 Keys

使用/v3/watch服務查看Keys:

curl -N http://localhost:2379/v3/watch \
  -X POST -d '{"create_request": {"key":"Zm9v"} }' &# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}}

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}}

交易

使用``/v3/kv/txn`發行一個交易：

# 目標創建
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}

# 目標版本
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"6","raft_term":"3"},"succeeded":true,"responses":[{"response_range":{"header":{"revision":"6"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"6","version":"4","value":"YmF6"}],"count":"1"}}]}

權限

使用/v3/auth設置權限：

# 創建root用戶
curl -L http://localhost:2379/v3/auth/user/add \
  -X POST -d '{"name": "root", "password": "pass"}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# 創建root角色
curl -L http://localhost:2379/v3/auth/role/add \
  -X POST -d '{"name": "root"}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# 授予root角色
curl -L http://localhost:2379/v3/auth/user/grant \
  -X POST -d '{"user": "root", "role": "root"}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# 開啟認證
curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

通過/v3/auth/authenticate服務使用一個認證令牌進行認證:

# 為根用戶獲取認證令牌
curl -L http://localhost:2379/v3/auth/authenticate \
  -X POST -d '{"name": "root", "password": "pass"}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}

使用認證證書設置認證頭部到認證令牌獲取Keys：

curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization : sssvIpwfnLAcWAQH.9' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}