Začínáme

Vytvořte nový projekt s názvem kv-tutorial spuštěním:

npm create cloudflare@latest -- kv-tutorial

Při nastavení vyberte následující možnosti:

• Pro S čím byste chtěli začít?, vyberte Hello World example.
• Pro Jakou šablonu chcete použít?, vyberte Worker only.
• Pro Jaký jazyk chcete použít?, vyberte TypeScript.
• Pro Chcete používat git pro správu verzí?, vyberte Yes.
• Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).

Tím se vytvoří nová kv-tutorial adresáři, jak je znázorněno níže.

Váš nový kv-tutorial adresář obsahuje:

• A "Hello World" Worker v index.ts.
• A wrangler.jsonc konfigurační soubor. wrangler.jsonc je způsob, jakým vaše kv-tutorial Worker přistupuje k vaší databázi kv.

Přejděte do adresáře, který jste právě vytvořili pro svůj projekt Worker:

cd kv-tutorial

V dashboardu Cloudflare přejděte na Workers & Pages stránce.

Vyberte Vytvoření aplikace.

Vyberte Začněte s Hello World! > Začínáme.

Pojmenujte svého Workera. Pro účely tohoto tutoriálu pojmenujte svého Workera kv-tutorial.

Vyberte Nasadit.

Otevřete terminál a spusťte následující příkaz:

npx wrangler kv namespace create <BINDING_NAME>

npx wrangler kv namespace create <BINDING_NAME> subpříkaz jako argument přijímá název nové binding. KV namespace se vytvoří spojením názvu vašeho Workeru (ze souboru Wrangler) a názvu binding, který zadáte. <BINDING_ID> se vygeneruje náhodně.

Pro účely tohoto tutoriálu použijte název bindingu 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>"
		}
	]
}

V dashboardu Cloudflare přejděte na Workers KV stránce.

Vyberte Vytvořit instanci.

Zadejte název pro svůj namespace. Pro účely tohoto tutoriálu použijte kv_tutorial_namespace.

Vyberte Vytvořit.

Do souboru Wrangler přidejte následující s hodnotami, které jste v terminálu vygenerovali pomocí krok 2:

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

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

Názvy vazeb (binding) nemusí odpovídat vytvořenému namespace. Slouží pouze jako reference. Konkrétně:

• Hodnota (řetězec), kterou nastavíte pro binding slouží k odkazování na tento KV namespace ve vašem Workeru. Pro účely tohoto tutoriálu by mělo být USERS_NOTIFICATION_CONFIG.
• Binding musí být platný název proměnné v JavaScriptu ↗. Například binding = "MY_KV" nebo binding = "routingConfig" by byly oba platné názvy pro binding.
• Váš binding je ve Workeru dostupný na env.<BINDING_NAME> zevnitř vašeho Workeru. Pro účely tohoto tutoriálu je binding dostupný na env.USERS_NOTIFICATION_CONFIG.

V dashboardu Cloudflare přejděte na Workers & Pages stránce.

Vyberte kv-tutorial Worker, který jste vytvořili v krok 1.

Přejděte do Bindings kartě a poté vyberte Add binding.

Vyberte KV namespace > Add binding.

Pojmenujte binding (BINDING_NAME) v Název proměnné, poté vyberte KV namespace (kv_tutorial_namespace) kterou jste vytvořili v krok 2 z rozbalovací nabídky.

Vyberte Add binding k nasazení vaší vazby.

Spustit wrangler kv key put subpříkaz ve svém terminálu a zadejte postupně klíč a hodnotu. <KEY> a <VALUE> jsou hodnoty podle vašeho výběru.

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

V tomto tutoriálu přidáte klíč user_1 s hodnotou enabled do KV namespace, který jste vytvořili v krok 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>.

V dashboardu Cloudflare přejděte na Workers KV stránce.

Vyberte KV namespace, který jste vytvořili (kv_tutorial_namespace).

Přejděte na Páry KV kartě.

Zadejte <KEY> dle vlastního výběru.

Zadejte <VALUE> dle vlastního výběru.

Vyberte Přidat položku.

Spustit wrangler kv key get subpříkaz ve svém terminálu a zadejte hodnotu klíče:

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

V tomto tutoriálu získáte hodnotu klíče user_1 z KV namespace, který jste vytvořili v krok 2.

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

Podobně jako put příkazu get příkaz lze také použít pro přístup ke KV namespace dvěma způsoby: pomocí --binding nebo --namespace-id:

V dashboardu Cloudflare přejděte na Workers KV stránce.

Přejděte do jmenného prostoru KV, který jste vytvořili (kv_tutorial_namespace).

Přejděte na Páry KV kartě.

Do skriptu Worker přidejte vazbu KV do Env rozhraní. Pokud jste svůj projekt inicializovali pomocí JavaScriptu, tento krok není nutný.

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

Použijte put() metodu na USERS_NOTIFICATION_CONFIG k vytvoření nového páru klíč-hodnota. Přidáte nový klíč user_2 s hodnotou disabled do vašeho KV namespace.

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

Použijte KV get() metodu k načtení dat uložených ve vašem KV namespace. Načtete hodnotu klíče user_2 z vašeho KV namespace.

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

V dashboardu Cloudflare přejděte na Workers & Pages stránce.

Přejděte na kv-tutorial Worker, který jste vytvořili.

Vyberte Edit Code.

Vymažte veškerý obsah workers.js soubor a poté vložte následující kód.

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>;

Výše uvedený kód:

1. Zapíše klíč do BINDING_NAME pomocí put() metoda.
2. Čte stejný klíč pomocí get() metoda a vrátí chybu, pokud je klíč null (respektive pokud klíč není nastaven nebo neexistuje).
3. Využívá JavaScriptovu metodu try...catch ↗ ošetření výjimek pro zachycení případných chyb. Při zápisu do libovolné služby nebo čtení z ní, jako je Workers KV nebo externí API, pomocí fetch() byste měli počítat s tím, že výjimky budete muset ošetřovat explicitně.

Prohlížeč by měl jednoduše vrátit VALUE odpovídající KEY kterou jste zadali pomocí get() metoda.

Vyberte rozbalovací šipku vedle Nasadit a vyberte Save.

Spusťte následující příkaz pro nasazení KV do globální sítě Cloudflare:

npm run deploy

Přejděte na adresu URL vaší nově vytvořené aplikace Workers KV.

Pokud je například URL vašeho nového Workeru kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev, přístupem k https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ odešle na váš Worker požadavek, který zapisuje do Workers KV (a čte z něj).

V dashboardu Cloudflare přejděte na Workers & Pages stránce.

Vyberte svůj kv-tutorial Worker.

Vyberte Deployments.

Z Historie verzí tabulku vyberte Deploy version.

Z Deploy version stránce vyberte Nasadit.

Tím se do produkce nasadí nejnovější verze kódu Workeru.