Начало работы

Создайте новый проект с именем kv-tutorial выполнив:

npm create cloudflare@latest -- kv-tutorial

Для настройки выберите следующие параметры:

• Для С чего вы хотите начать?, выберите Hello World example.
• Для Какой шаблон вы хотите использовать?, выберите Worker only.
• Для Какой язык вы хотите использовать?, выберите TypeScript.
• Для Хотите использовать git для контроля версий?, выберите Yes.
• Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

Это создаёт новый kv-tutorial каталоге, как показано ниже.

Ваш новый kv-tutorial каталог включает:

• A "Hello World" Worker в index.ts.
• A wrangler.jsonc файл конфигурации. wrangler.jsonc показывает, как выглядит ваш kv-tutorial Worker обращается к вашей базе данных kv.

Перейдите в каталог, который вы только что создали для своего проекта Worker:

cd kv-tutorial

На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

Выберите Создать приложение.

Выберите Начните с Hello World! > Начало работы.

Присвойте имя своему Worker. Для этого руководства назовите Worker kv-tutorial.

Выберите Развернуть.

Откройте терминал и выполните следующую команду:

npx wrangler kv namespace create <BINDING_NAME>

npx wrangler kv namespace create <BINDING_NAME> подкоманда принимает в качестве аргумента новое имя привязки. Пространство имен KV создаётся путём объединения имени вашего Worker (из файла Wrangler) и указанного вами имени привязки. <BINDING_ID> генерируется для вас случайным образом.

Для этого руководства используйте имя привязки USERS_NOTIFICATION_CONFIG.

npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG

🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

На панели управления Cloudflare перейдите к разделу Workers KV страницу.

Выберите Создать инстанс.

Введите имя пространства имён. Для этого руководства используйте kv_tutorial_namespace.

Выберите Создание.

В файле Wrangler добавьте следующее со значениями, сгенерированными в терминале при выполнении шаг 2:

{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<BINDING_ID>"

Имена привязок не обязаны совпадать с именем созданного вами пространства имён. Имя привязки служит лишь ссылкой. А именно:

• Значение (строка), которое вы задали для binding используется для обращения к этому пространству имен KV в вашем Worker. Для этого руководства оно должно быть USERS_NOTIFICATION_CONFIG.
• Привязка должна быть допустимое имя переменной JavaScript ↗. Например, binding = "MY_KV" или binding = "routingConfig" оба варианта были бы допустимыми именами для привязки.
• Привязка доступна в Worker по адресу env.<BINDING_NAME> внутри вашего Worker. В этом руководстве привязка доступна по адресу env.USERS_NOTIFICATION_CONFIG.

На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

Выберите kv-tutorial Worker, который вы создали в шаг 1.

Перейдите в Bindings вкладке, а затем выберите Add binding.

Выберите Пространство имён KV > Add binding.

Задайте имя привязки (BINDING_NAME) в Имя переменной, затем выберите пространство имён KV (kv_tutorial_namespace) которое вы создали в шаг 2 в раскрывающемся списке.

Выберите Add binding чтобы развернуть привязку.

Выполните wrangler kv key put подкоманду в терминале и введите ваш ключ и значение соответственно. <KEY> и <VALUE> это значения на ваш выбор.

npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"

В этом руководстве вы добавите ключ user_1 со значением enabled к пространству имён KV, созданному в шаг 2.

npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"

Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.

На панели управления Cloudflare перейдите к разделу Workers KV страницу.

Выберите пространство имен KV, которое вы создали (kv_tutorial_namespace).

Перейдите в KV Pairs на вкладке.

Введите <KEY> по вашему выбору.

Введите <VALUE> по вашему выбору.

Выберите Добавить запись.

Выполните wrangler kv key get подкоманду в терминале и введите значение ключа:

npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"

В этом руководстве вы получите значение ключа user_1 из пространства имён KV, которое вы создали в шаг 2.

npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text

Аналогично put команды, get команду также можно использовать для доступа к пространству имён KV двумя способами: с помощью --binding или --namespace-id:

На панели управления Cloudflare перейдите к разделу Workers KV страницу.

Перейдите в пространство имён KV, которое вы создали (kv_tutorial_namespace).

Перейдите в KV Pairs на вкладке.

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

interface Env {
	USERS_NOTIFICATION_CONFIG: KVNamespace;
	// ... other binding types
}

Используйте put() метод для USERS_NOTIFICATION_CONFIG для создания новой пары ключ-значение. Вы добавите новый ключ user_2 со значением disabled в ваше пространство имён KV.

let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");

Используйте KV get() метод для получения данных, сохранённых в вашем пространстве имен KV. Вы получите значение ключа user_2 из вашего пространства имён KV.

let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");

На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

Перейдите в kv-tutorial Worker, который вы создали.

Выберите Edit Code.

Очистите всё содержимое workers.js файл и вставьте в него следующий код.

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
			if (value === null) {
				return new Response("Value not found", { status: 404 });
			}
			return new Response(value);
		} catch (err) {
			console.error(`KV returned error:`, err);
			const errorMessage =
				err instanceof Error
					? err.message
					: "An unknown error occurred when accessing KV storage";
			return new Response(errorMessage, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

Код выше:

1. Записывает ключ в BINDING_NAME с помощью KV put() метод.
2. Считывает тот же ключ, используя KV get() метод и возвращает ошибку, если ключ равен null (или если ключ не задан либо не существует).
3. Использует JavaScript try...catch ↗ обработку исключений для перехвата возможных ошибок. При записи в любой сервис или чтении из него, например Workers KV или внешние API, с использованием fetch(), следует явно обрабатывать исключения.

Браузер должен просто вернуть VALUE соответствующий KEY указанных с помощью get() метод.

Нажмите на стрелку раскрывающегося списка рядом с Развернуть и выберите Save.

Выполните следующую команду, чтобы развернуть KV в глобальной сети Cloudflare:

npm run deploy

Перейдите по URL-адресу вашего нового приложения Workers KV.

Например, если URL вашего нового Worker равен kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev, обращаясь к https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ отправляет запрос вашему Worker, который записывает данные в Workers KV (и считывает их оттуда).

На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

Выберите свой kv-tutorial Worker.

Выберите Развёртывания.

Из раздела История версий таблицу, выберите Deploy version.

Из раздела Deploy version странице выберите Развернуть.

Это разворачивает последнюю версию кода Worker в продакшене.