Consul K/V Store Endpoints

这个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>"
    }
  },
  ...
]

KV是唯一可用的操作类型,但是可以在未来版本的Consul中添加其他类型的操作以与K/V操作混合。以下字段可用:

  • Verb 是要执行的操作的类型。请参阅下表中的可用动词。
  • Key 是简单的条目的完整路径。
  • Value 是一个Base64编码的数据块。值不能大于512kB。
  • Flags 是一个不透明的无符号整数,可以附加到每个条目。它可以用来被客户添加有意义的元数据到任何键值。
  • Index and Session 用于锁定,解锁和check-and-set操作。有关如何使用它们的详细信息,请参阅下表。

下表总结了可用的动词和适用于该操作的字段(“X”表示字段是必需的,“O”表示它是可选的):
https://www.consul.io/docs/agent/http/kv.html#Value

展开阅读全文

没有更多推荐了,返回首页