← Cloudflare Workers KV / kv / concepts

Привязки KV

KV привязки обеспечивают связь между Worker и пространством имён KV.

Настройте привязки KV в конфигурационный файл Wrangler.

A Пространство имён KV это база данных ключ-значение, реплицированная в глобальную сеть Cloudflare.

Чтобы подключиться к пространству имён KV из Worker, необходимо определить привязку, указывающую на идентификатор этого пространства имён.

Имя привязки не обязательно должно совпадать с именем пространства имен KV. Вместо этого оно должно быть допустимым идентификатором JavaScript, так как именно под этим идентификатором привязка станет глобальной переменной в вашем Worker.

Пространству имён KV присваивается имя, которое вы выбираете (например, My tasks), и присвоенный ID (например, 06779da6940b431db6e566b4846d64db).

Чтобы выполнить ваш Worker, определите привязку.

В следующем примере привязка называется TODO. В kv_namespaces раздел файла конфигурации Wrangler добавьте:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker",
	// ...
	"kv_namespaces": [
		{
			"binding": "TODO",
			"id": "06779da6940b431db6e566b4846d64db"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker"

[[kv_namespaces]]
binding = "TODO"
id = "06779da6940b431db6e566b4846d64db"

После этого у развёрнутого Worker будет TODO поле в объекте окружения (второй параметр fetch() обработчике запросов). Любые методы TODO привязка будет сопоставлена с пространством имён KV с идентификатором 06779da6940b431db6e566b4846d64db, которое вы назвали My Tasks ранее.

export default {
  async fetch(request, env, ctx) {
    // Get the value for the "to-do:123" key
    // NOTE: Relies on the `TODO` KV binding that maps to the "My Tasks" namespace.
    let value = await env.TODO.get("to-do:123");

    // Return the value, as is, for the Response
    return new Response(value);
  },
};

Когда вы используете Wrangler для локальной разработки с wrangler dev команды Wrangler по умолчанию использует локальную версию KV, чтобы не затрагивать данные в рабочей (production) версии KV. Это означает, что при чтении ключей, которые вы не записывали локально, будет возвращено null.

Чтобы wrangler dev подключения к пространству имён Workers KV, работающему в глобальной сети Cloudflare, укажите "remote" : true в конфигурации привязки KV. См. документация по remote bindings, где это описано подробнее.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker",
	// ...
	"kv_namespaces": [
		{
			"binding": "TODO",
			"id": "06779da6940b431db6e566b4846d64db"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker"

[[kv_namespaces]]
binding = "TODO"
id = "06779da6940b431db6e566b4846d64db"

Durable Objects используют формат модулей ES. Вместо глобальной переменной привязки доступны как свойства env параметр переданный в конструктор.

Пример может выглядеть так:

import { DurableObject } from "cloudflare:workers";

export class MyDurableObject extends DurableObject {
  constructor(ctx, env) {
    super(ctx, env);
  }

  async fetch(request) {
    const valueFromKV = await this.env.NAMESPACE.get("someKey");
    return new Response(valueFromKV);
  }
}