KV · cloudflareWorker中文文档

# KV * [总览](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#overview) * [入门](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#getting-started) * [概念](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#concepts) * [`kv:namespace`](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-namespace) * [`kv:key`](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-key) * [`kv:bulk`](https://developers.cloudflare.com/workers/tooling/wrangler/kv_commands/#kv-bulk) ## 总览该`kv`命令允许您将应用程序数据存储的CloudFlare网络中从工人访问，使用[工KV](https://www.cloudflare.com/products/workers-kv/)。KV操作仅限于您的帐户，因此，要使用这些命令中的任何一个，您需要： * 在您的`account_id`配置中设置了Wrangler项目`wrangler.toml` * 在Wrangler项目目录中调用命令。 ## 入门要将Workers KV与您的Worker一起使用，您必须做的第一件事就是创建一个KV名称空间。这是通过`kv:namespace`子命令完成的。该`kv:namespace`子命令将作为一个新的绑定名作为参数。它将创建一个Worker KV名称空间，其标题是您的Worker名称（来自`wrangler.toml`）和您提供的绑定名称的串联： ~~~console $ wrangler kv:namespace create "MY_KV" 🌀 Creating namespace with title "worker-MY_KV" ✨ Success: WorkersKvNamespace { id: "e29b263ab50e42ce9b637fa8370175e8", title: "worker-MY_KV", } ✨ Add the following to your wrangler.toml: kv-namespaces = [ { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" } ] ~~~ 确保将`kv-namespaces`以上输出添加到您的中`wrangler.toml`。现在，您可以使用以下代码从Worker中访问它： ~~~js let value = await MY_KV.get("my-key"); ~~~ 完整的KV API for Workers可以在[这里](https://developers.cloudflare.com/workers/reference/storage/)找到。要通过Wrangler为您的KV名称空间添加值，请使用`kv:key put`子命令。 ~~~console $ wrangler kv:key put --binding=MY_KV "key" "value" ✨ Success ~~~ 您还可以指定使用键/值对使用的名称空间，`--namespace-id`而不是`--binding`： ~~~console $ wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "key" "value" ✨ Success ~~~ 此外，KV名称空间可与[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)一起使用！当您具有引用诸如KV的KV绑定的代码`MY_KV`并且希望能够使这些绑定指向不同的命名空间（例如，一个用于暂存和一个用于生产）时，这很有用。因此，如果您有`wrangler.toml`两个环境： ~~~toml [env.staging] kv-namespaces = [ { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" } ] [env.production] kv-namespaces = [ { binding = "MY_KV", id = "a825455ce00f4f7282403da85269f8ea" } ] ~~~ 要将值插入特定的KV命名空间，可以使用 ~~~console $ wrangler kv:key put --env=staging --binding=MY_MV "key" "value" ✨ Success ~~~ 由于`--namespace-id`始终是唯一的（与绑定名称不同），因此您不需要为其传递环境变量（它们将不被使用）。有更多有用的Wrangler子命令可与Workers KV进行交互，例如用于批量上传和删除的子命令-请在下面查看它们！ ## 概念大多数`kv`命令都要求您指定一个名称空间。可以通过两种方式指定名称空间： 1. 带有`--binding`： ~~~sh wrangler kv:key get --binding=MY_KV "my key" ~~~ 2. 带有`--namespace_id`： ~~~sh wrangler kv:key get --namespace-id=06779da6940b431db6e566b4846d64db "my key" ~~~ 大多数`kv`子命令还允许您使用可选`--env`标志指定环境。这使您可以发布运行相同代码但具有不同名称空间的工作程序。例如，您可以在KV数据中使用单独的暂存和生产名称空间`wrangler.toml`： ~~~toml type = "webpack" name = "my-worker" account_id = "<account id here>" route = "staging.example.com/*" workers_dev = false kv-namespaces = [ { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" } ] [env.production] route = "example.com/*" kv-namespaces = [ { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" } ] ~~~ 通过上面的wrangler.toml，您可以在下指定`--env production`要对名称空间执行KV操作的时间。例如，使用上面的wrangler.toml，您可以使用以下方法从生产KV实例中获取值：`MY_KV``env.production` ~~~console wrangler kv:key get --binding "MY_KV" --env=production "my key" ~~~ 要了解有关环境的更多信息，请查阅[环境文档](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)。 ## `Kv:namespace` ### `create` 创建一个新的名称空间。采用可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:namespace create "MY_KV" 🌀 Creating namespace with title "worker-MY_KV" ✨ Success: WorkersKvNamespace { id: "e29b263ab50e42ce9b637fa8370175e8", title: "worker-MY_KV", } ✨ Add the following to your wrangler.toml: kv-namespaces = [ { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" } ] ~~~ ### `list` 输出与您的帐户ID关联的所有KV名称空间的列表。 #### 用法下面的示例使用`jq`命令行工具漂亮地打印输出。 ~~~console $ wrangler kv:namespace list | jq '.' [ { "id": "06779da6940b431db6e566b4846d64db", "title": "TEST_NAMESPACE" }, { "id": "32ac1b3c2ed34ed3b397268817dea9ea", "title": "STATIC_CONTENT" } ] ~~~ ### `delete` 删除给定的名称空间。需要`--binding`或`--namespace-id`争论。采用可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:namespace delete --binding=MY_KV Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n] yes 🌀 Deleting namespace f7b02e7fc70443149ac906dd81ec1791 ✨ Success ~~~ ## `Kv:key` ### `put` 将单个键/值对写入给定的名称空间。需要`--binding`或`--namespace-id`争论。可选参数包括： 1. `--env`：[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 2. `--ttl`：条目过期之前应该可见的秒数。至少60。优先于“过期”选项。 3. `--expiration`：自UNIX时代以来的秒数，指示键值对何时到期。 4. `--path`：从文件中的给定路径读取值。*这对安全敏感的操作很有用，例如将密钥上传到KV；从文件上传会阻止键值保存在终端历史记录等区域。* #### 用法 ~~~console $ wrangler kv:key put --binding=MY_KV "key" "value" --ttl=10000 ✨ Success ~~~ ~~~console $ wrangler kv:key put --binding=MY_KV "key" value.txt --path ✨ Success ~~~ ### `list` 输出给定名称空间中所有键的列表。需要`--binding`或`--namespace-id`争论。可选参数包括： 1. `--env`：[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 2. `--prefix`：前缀，用于过滤列出的键。 #### 用法下面的示例使用`jq`命令行工具漂亮地打印输出。 ~~~console $ wrangler kv:key list --binding=MY_KV --prefix="public" | jq '.' [ { "name": "public_key" }, { "name": "public_key_with_expiration", "expiration": "2019-09-10T23:18:58Z" } ] ~~~ ### `get` 通过键从给定的名称空间中读取单个值。需要`--binding`或`--namespace-id`争论。采用可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:key get --binding=MY_KV "key" value ~~~ ### `delete` 从给定的名称空间中删除一个键值对。需要`--binding`或`--namespace-id`争论。采用可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:key delete --binding=MY_KV "key" Are you sure you want to delete key "key"? [y/n] yes 🌀 Deleting key "key" ✨ Success ~~~ ## `Kv:bulk` ### `put` 需要`--binding`或`--namespace-id`争论。将充满键/值对的文件写入给定名称空间。将带有要上传的键值对列表的JSON文件作为参数（请参见上面的JSON规范）。JSON输入的示例： ~~~json [ { "key": "test_key", "value": "test_value", "expiration_ttl": 3600 } ] ~~~ 以下架构是通过批量API上传的键值条目的完整架构： | **名称** | **描述** | 可选的 | | --- | --- | --- | | `key` （串） | 密钥名称。名称最多为512个字节。所有可打印的非空白字符均有效。 | 没有 | | `value` （串） | 要存储的UTF-8编码字符串，最大长度为10 MB。 | 没有 | | `expiration` （数） | 自UNIX时代以来以秒为单位的时间，密钥应在该时间到期。 | 是 | | `expiration_ttl` （数） | 密钥过期之前应该可见的秒数。至少60。 | 是 | | `base64` （布尔值） | 服务器在存储值之前是否应该对base64进行解码。对于编写原本不是有效JSON字符串的值（例如图像）很有用。默认为`false` | 是 | 如果为给定密钥同时指定`expiration`和和`expiration_ttl`，则API将首选`expiration_ttl`。该`put`命令还带有可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:bulk put --binding=MY_KV allthethingsupload.json ✨ Success ~~~ ### `delete` 需要`--binding`或`--namespace-id`争论。删除给定名称空间中的所有指定键。将带有要删除的键/值对列表的JSON文件作为参数（请参阅上面的JSON规范）。JSON输入的示例： ~~~json [ { "key": "test_key", "value": "test_value", "expiration_ttl": 3600 } ] ~~~ 该`delete`命令还带有可选的`--env`[环境](https://developers.cloudflare.com/workers/tooling/wrangler/configuration/environments)参数。 #### 用法 ~~~console $ wrangler kv:bulk delete --binding=MY_KV allthethingsdelete.json Are you sure you want to delete all keys in allthethingsdelete.json? [y/n] yes ✨ Success ~~~