# 千伏
* [编写键值对](https://developers.cloudflare.com/workers/reference/apis/kv/#writing-key-value-pairs)
* [批量写入数据](https://developers.cloudflare.com/workers/reference/apis/kv/#writing-data-in-bulk)
* [密钥过期](https://developers.cloudflare.com/workers/reference/apis/kv/#expiring-keys)
* [创建过期密钥](https://developers.cloudflare.com/workers/reference/apis/kv/#creating-expiring-keys)
* [读取键值对](https://developers.cloudflare.com/workers/reference/apis/kv/#reading-key-value-pairs)
* [种类](https://developers.cloudflare.com/workers/reference/apis/kv/#types)
* [删除键值对](https://developers.cloudflare.com/workers/reference/apis/kv/#deleting-key-value-pairs)
* [上市钥匙](https://developers.cloudflare.com/workers/reference/apis/kv/#listing-keys)
* [更多详情](https://developers.cloudflare.com/workers/reference/apis/kv/#more-detail)
* [按前缀列出](https://developers.cloudflare.com/workers/reference/apis/kv/#listing-by-prefix)
* [订购方式](https://developers.cloudflare.com/workers/reference/apis/kv/#ordering)
* [分页](https://developers.cloudflare.com/workers/reference/apis/kv/#pagination)
# 编写键值对
要创建新的键值对或更新特定键的值，可以`put`在绑定到脚本的任何名称空间上调用该方法。此方法的基本形式如下所示：
`await NAMESPACE.put(key, value)`
该类型是从值自动推断的，可以是以下任意一种：
* `string`
* `ReadableStream`
* `ArrayBuffer`
此方法返回一个诺言，您应`await`启用该诺言以验证更新是否成功。
您还可以[使用Wrangler从命令行编写键/值对](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)。
最后，您可以[通过API写入数据](https://api.cloudflare.com/#workers-kv-namespace-write-key-value-pair)。
由于Workers KV的最终一致性，通过Wrangler或API写入数据是一种常见的模式，但需要在worker内部读取数据。
## 批量写入数据
您可以[使用wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-bulk)或[通过API](https://api.cloudflare.com/#workers-kv-namespace-write-multiple-key-value-pairs)[一次编写多个键/值对](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-bulk)，最多10,000 KV对。每个KV对都需要A`key`和`value`。整个请求大小必须小于100兆字节。目前，我们不支持在Worker脚本中使用此功能。
## 密钥过期
Workers KV的许多常见用法包括编写仅在一定时间内有效的密钥。不需要要求应用程序记住在适当的时间删除此类数据，Workers KV可以创建自动失效的密钥，该密钥可以在特定时间点或自从上次修改密钥以来经过一定时间后自动失效。
到期密钥的核心行为是，一旦达到其到期时间，尝试读取它的行为就好像该密钥不存在一样。尝试获取密钥的值将返回一个承诺，该承诺会通过API在Worker或404 HTTP响应中解析为null，并且使用API列出密钥会忽略响应中所有过期的密钥。
您可以选择以下两种方式之一来指定密钥何时到期：
* 使用[自UNIX纪元以来以秒](https://en.wikipedia.org/wiki/Unix_time)为[单位](https://en.wikipedia.org/wiki/Unix_time)指定的绝对时间来设置其“到期”。例如，如果您希望密钥在2019年4月1日UTC AM 12:00到期，则可以将密钥的到期时间设置为1554076800。
* 使用距当前时间的相对秒数来设置其“到期TTL”（生存时间）。例如，如果您希望密钥在创建后10分钟到期，则可以将其到期TTL设置为600。
当在Worker内编写密钥或使用API编写密钥时，这两个选项均可用。
请注意，目前不支持将来的失效时间少于60秒或失效TTL少于60秒。
### 创建过期密钥
我们讨论了`put`上面方法的基本形式，但是此调用还有一个可选的第三个参数。它接受带有可选字段的对象，该字段允许您自定义的行为`put`。特别是，您可以根据希望如何指定密钥的到期时间来设置`expiration`或`expirationTtl`。换句话说，当您从Worker内部写入密钥时，您将运行以下两个命令之一来设置到期时间：
`NAMESPACE.put(key, value, {expiration: secondsSinceEpoch})`
`NAMESPACE.put(key, value, {expirationTtl: secondsFromNow})`
这些假设`secondsSinceEpoch`和`secondsFromNow`是在您的工作者代码中其他位置定义的变量。
您也可以[通过Wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)或[API](https://api.cloudflare.com/#workers-kv-namespace-write-key-value-pair)[在命令行上写满到期时间](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)。
# 读取键值对
要获取给定键的值，可以`get`在绑定到脚本的任何名称空间上调用该方法：
`NAMESPACE.get(key)`
该方法返回一个可以`await`获取值的承诺。如果未找到密钥，则promise将使用文字值解析`null`。
这是从Worker内部读取密钥的示例：
~~~js
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const value = await FIRST_KV_NAMESPACE.get("first-key")
if (value === null) {
return new Response("Value not found", {status: 404})
}
return new Response(value)
}
~~~
您还可以[使用wrangler从命令行读取键值对](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)。
最后，您还可以[阅读API](https://api.cloudflare.com/#workers-kv-namespace-read-key-value-pair)。
## 种类
您也可以将可选`type`参数传递给`get`方法：
`NAMESPACE.get(key, type)`
该`type`参数可以是以下任意一个：
* `"text"`：（默认）一个字符串
* `"json"`：从JSON字符串解码的对象
* `"arrayBuffer"`：一个[ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)实例。
* `"stream"`：一个[ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)。
对于简单的值，使用默认`"text"`类型通常是有意义的，该默认类型为您提供作为字符串的值。为了方便起见，`"json"`还指定了一种类型，该类型会将JSON值转换为对象，然后再将其返回给您。对于大值，您可以请求`ReadableStream`，对于二进制值，则可以请求`ArrayBuffer`。
对于较大的值，选择`type`可以对延迟和CPU使用率产生明显影响。作为参考，`type`S可从最快的，责令最慢作为`"stream"`，`"arrayBuffer"`，`"text"`，和`"json"`。
# 删除键值对
要删除键值对，您可以`delete`在绑定到脚本的任何命名空间上调用方法：
`await NAMESPACE.delete(key)`
这将从您的名称空间中删除键和值。与任何操作一样，可能需要一些时间才能看到它们的密钥已从边缘的各个点删除。
此方法返回一个诺言，您应`await`启用该诺言以验证删除是否成功。
您还可以[使用Wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)或[通过API](https://api.cloudflare.com/#workers-kv-namespace-delete-key-value-pair)[从命令行删除键/值对](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)。
# 上市钥匙
您可以使用列表操作来查看给定名称空间中的所有键。这是一个基本示例：
~~~js
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const value = await NAMESPACE.list()
return new Response(value.keys)
}
~~~
您还可以[使用Wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)或[通过API](https://api.cloudflare.com/#workers-kv-namespace-list-a-namespace-s-keys)[在命令行上列出键](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key)。
## 更多详情
该`list`方法具有以下签名（在TypeScript中）：
`NAMESPACE.list({prefix?: string, limit?: number, cursor?: string})`
所有参数都是可选的：
* `prefix`是代表前缀的字符串，可用于过滤所有键。
* `limit`是返回的最大键数。默认值为1000，这是最大值。您不太可能希望更改此默认设置，但是为了完整起见，将其包括在内。
* `cursor`是用于分页响应的字符串。有关更多信息，请参见下文。
该`.list`方法返回一个promise，该promise将通过如下所示的对象进行解析：
~~~json
{
keys: [{ name: "foo", expiration: 1234}],
list_complete: false,
cursor: "6Ck1la0VxJ0djhidm1MdX2FyD"
}
~~~
该`keys`属性将包含描述每个键的对象数组。该对象将具有其自己的两个密钥：密钥的a`name`及其过期值。名称是一个字符串，到期值是一个数字。仅当密钥具有到期时间时才返回该到期值，并且该到期值将采用绝对值形式，即使它是以TTL形式设置的也是如此。
此外，如果`list_complete`为`false`，则还有更多要提取的密钥。您将使用该`cursor`属性来获取更多密钥。参见[分页部分](https://developers.cloudflare.com/workers/reference/apis/kv/#pagination)
下面的更多详细信息。
## 按前缀列出
您还可以列出所有以特定前缀开头的键。例如，假设您已经用用户，用户ID和一些键名（用冒号（例如`user:1:<key>`）分隔）来构造键。您可以通过执行以下操作获得第一用户的密钥：
~~~js
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const value = await NAMESPACE.list({"prefix": "user:1:"})
return new Response(value.keys)
}
~~~
这将返回以开头的所有键`"user:1:"`。
## 订购方式
密钥始终根据其UTF-8字节以字典顺序返回。
## 分页
如果键的数量多于`limit`值，则仅返回那么多键。此外，`list_complete`密钥将设置为`false`，并且`cursor`还将返回a。在这种情况下，您可以`list`使用`cursor`值再次调用以获得下一组键：
~~~js
const value = await NAMESPACE.list()
const cursor = value.cursor
const next_value = await NAMESPACE.list({"cursor": cursor})
~~~
- 关于本翻译文档
- 快速开始
- 模版库
- 讲解
- Workers页面
- 从0开始
- 从已有页面开始
- 从已有Worder开始
- 工具
- Cli工具 wrangler
- 安装
- 指令
- 配置
- 环境
- Webpack
- 密钥
- KV
- 网站
- Playground
- ServerLess插件
- Terraform
- REST API
- Making Requests
- Scripts
- Bindings
- Routes
- Integrations
- 相关
- 工作原理
- 安全
- 使用缓存
- 价格
- Routes
- Limits
- 提示
- 调试技巧
- 调试header
- FetchEvent生命周期
- 请求上下文
- 请求sign
- 参考
- runtime API
- Web Standards
- fetch
- fetchEvent
- Response
- Request
- KV
- Environment Variables
- Streams
- Encoding
- Web Crypto
- Cache API
- HTMLRewriter
- Workers KV
- Use cases
- Namespaces