Consul K/V Store Endpoints

最新推荐文章于 2024-08-15 16:36:10 发布

xiaojia1100

最新推荐文章于 2024-08-15 16:36:10 发布

阅读量2.1k

点赞数 1

分类专栏： Consul 文章标签： consul kv

Consul 专栏收录该内容

3 篇文章 0 订阅

订阅专栏

这个KV端点可以用于访问Consul简单的K/V存储, 对于存储服务配置或其他元数据非常有用。

他支持下面两种端点：
- /v1/kv/:
管理单个键的更新，删除单个键或键前缀，以及提取单个键或键前缀。
- /v1/txn:
管理单个原子事务中多个键的更新或提取。

/v1/kv/

管理单个键的更新，删除单个键或键前缀，以及提取单个键或键前缀。支持GET、PUT和DELETE方法。

默认情况下，查询代理的数据中心;然而，可以使用？dc=查询参数指定数据中心。需要注意的是，每个数据中心都有自己的KV存储，并且在数据中心之间没有内置复制。
如果您对数据中心之间的复制感兴趣，请查看Consul Replicate项目。

KV端点支持用？token = query参数使用ACL令牌。

GET

当使用GET方法时，Consul将返回指定的键。如果提供了？recurse查询参数，它将返回具有给定前缀的所有键。

此端点支持阻塞查询和所有一致性模式。

每个对象将如下所示：

[
  {
    "CreateIndex": 100,
    "ModifyIndex": 200,
    "LockIndex": 200,
    "Key": "zip",
    "Flags": 0,
    "Value": "dGVzdA==",
    "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
  }
]

CreateIndex是表示创建条目时的内部索引值。
ModifyIndex是修改此键的最后一个索引。此索引对应于响应中返回的X-Consul-Index头，并且可以通过设置？index查询参数来用于建立阻塞查询。您甚至可以对KV存储的整个子树执行阻塞查询：如果提供了?recurse，则返回的X-Consul-Index对应于前缀中的最新ModifyIndex，使用“？index”的阻塞查询将等待，直到任何
该前缀中的键被更新完成。
LockIndex是在锁中成功获取此键的次数。如果持有锁，Session键标示拥有锁的会话。
Key是简单的条目的完整路径。
Flags是一个不透明的无符号整数，可以附加到每个条目。它可以用来被客户添加有意义的元数据到任何键值。
Value是一个Base64编码的数据块。

注意：值不能大于512kB。

可以使用？keys查询参数列出没有其值的键。这将返回给定前缀下的键的列表。可选的？separator=可用于仅列出给定的分隔符。
例如，列出/web/路径下以/为分隔符的条目：

[
  "/web/bar",
  "/web/foo",
  "/web/subdir/"
]

当不需要值或标志或想要实现键空间浏览器时，使用键列表方法可能是合适的。

如果？raw查询参数与非递归GET一起使用，则响应只是键的原始值，不带任何编码。
如果没有找到条目，则返回404代码。

PUT

当使用PUT方法时，Consul期望请求体是与键相对应的值。有一些查询参数可以与PUT请求一起使用：

？flags = ：这可以用于指定0和（2 ^ 64）-1之间的无符号值。客户可以选择使用这个，但它们的应用程序有意义。
？cas = ：此标志用于将PUT转换为Check-And-Set操作。这对于更复杂的同步原语非常有用。
如果索引为0，则Consul将只有在键不存在时才设置。
如果索引非零，则只有在索引和该键的ModifyIndex相匹配时才设置键。
- ？acquire = ：此标志用于将PUT转换为锁定获取操作。
这是有用的，因为它允许领导者选举建立在Consul之上。
如果未持有锁并且会话有效，则除了更新键内容之外，还增加LockIndex并设置键的会话值。
如果锁已经由给定会话持有，则LockIndex不递增，但是键内容被更新。这使得当前锁持有者更新键内容，而不必放弃锁并且重新获取该锁。
？release = ：此标志用于将PUT转换为锁定释放操作。
当与“？acquire =”配对时，这是有用的，因为它允许客户端放弃锁。这将使LockIndex保持不变，但将清除关联的Session。会话持有的key将被解锁。

PUT操作返回值为true或false。如果返回false，则更新未发生。

DELETE

DELETE方法可用于删除单个键或有同一前缀的所有键。
有一些查询参数可以与DELETE请求一起使用：

？recurse：这用于删除具有指定前缀的所有键。否则，只有完全匹配的键将被删除。
？cas = ：此标志用于将DELETE转换为Check-And-Set操作。这对于更复杂的同步原语非常有用。
与PUT不同，索引必须大于0，以便Consul采取行动：0索引不会删除键。如果索引非零，则只有在索引匹配该键的ModifyIndex时，才会删除该键。

/v1/txn

在Consul 0.7和更高版本中可用，此端点在单个原子事务中管理多个键的更新或提取。仅支持PUT方法。

默认情况下，代理的数据中心接收事务;然而，可以使用？dc=查询参数指定数据中心。需要注意的是，每个数据中心都有自己的KV存储，并且在数据中心之间没有内置复制。
如果您对数据中心之间的复制感兴趣，请查看Consul Replicate项目。

事务端点支持用？token = query参数使用ACL令牌。

PUT

PUT方法允许您提交要应用事务的K/V存储的操作列表。如果任何操作失败，事务将被回滚，并且不会应用任何更改。

如果事务不包含任何写操作，那么它将在内部快速路由到像其他读取一样工作的端点，除非当前不支持阻塞查询。在此模式下，您可以向请求提供？stale或？consistent查询参数以控制一致性。
为了限制数据的有限过期时间，只读事务响应X-Consul-LastContact头标示服务器上次与领导节点联系的时间（毫秒）。X-Consul-KnownLeader头还指示是否存在已知的leader。
如果事务包含任何写操作，这些都将不存在，并且任何一致性查询参数将被忽略，因为写入总是由领导者通过Raft协议管理。

请求的主体应该是在原子事务内执行的操作的列表。在单个事务中可以存在多达64个操作。
操作如下所示：

[
  {
    "KV": {
      "Verb": "<verb>",
      "Key": "<key>",
      "Value": "<Base64-encoded blob of data>",
      "Flags": <flags>,
      "Index": <index>,
      "Session": "<session id>"
    }
  },
  ...
]