← Cloudflare Durable Objects / durable-objects

Začínáme

Tento návod vás provede:

• Napsání třídy v JavaScriptu, která definuje Durable Object.
• Použití SQL API Durable Objects k dotazování na soukromou vestavěnou databázi SQLite daného Durable Object.
• Vytvoření instance Durable Object a komunikace s ní z jiného Workeru.
• Nasazení Durable Object a Workeru, který s Durable Object komunikuje.

Pokud se chcete o Durable Objects dozvědět více, přečtěte si Co jsou Durable Objects?.

Pokud chcete kroky přeskočit a rychle začít, klikněte na tlačítko níže.

Tím se vytvoří repozitář ve vašem účtu GitHub a aplikace se nasadí na Cloudflare Workers. Tuto možnost použijte, pokud Cloudflare Workers dobře znáte a chcete přeskočit podrobné pokyny krok za krokem.

Pokud s Cloudflare Workers teprve začínáte, můžete kroky projít ručně.

1. Zaregistrujte si účet Cloudflare ↗.
2. Nainstalujte Node.js ↗.

K Durable Object budete přistupovat z Worker. Vaše aplikace Worker je rozhraním pro interakci s vaším Durable Object.

Chcete-li vytvořit projekt Workeru, spusťte:

npm create cloudflare@latest -- durable-object-starter

Spouštění create cloudflare@latest nainstaluje Wrangler, CLI nástroj pro Workers. K testování a nasazení projektu použijete Wrangler.

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 + Durable Objects.
• 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ý adresář, který bude obsahovat buď src/index.js nebo src/index.ts soubor pro zápis kódu a wrangler.jsonc konfigurační soubor.

Přejděte do nového adresáře:

cd durable-object-starter

Než Durable Object vytvoříte a začnete k němu přistupovat, musí být jeho chování definováno běžnou exportovanou třídou JavaScriptu.

Váš MyDurableObject třída bude mít konstruktor se dvěma parametry. Prvním parametrem, ctx, předávaným konstruktoru třídy, je stav specifický pro daný Durable Object, včetně metod pro přístup k úložišti. Druhým parametrem, env, obsahuje veškeré vazby, které jste s Workerem přidružili při jeho nahrání.

export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		// Required, as we're extending the base class.
		super(ctx, env);
	}
}

export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we're extending the base class.
		super(ctx, env)
	}
}

from workers import DurableObject

class MyDurableObject(DurableObject):
    def __init__(self, ctx, env):
        super().__init__(ctx, env)

Workers komunikují s Durable Object pomocí vzdálené volání procedury. Veřejné metody třídy Durable Object jsou dostupné jako Metody RPC pro volání jiným Workerem.

Váš soubor by nyní měl vypadat takto:

export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		// Required, as we're extending the base class.
		super(ctx, env);
	}

	async sayHello() {
		let result = this.ctx.storage.sql
			.exec("SELECT 'Hello, World!' as greeting")
			.one();
		return result.greeting;
	}
}

export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we're extending the base class.
		super(ctx, env)
	}

    async sayHello(): Promise<string> {
    	let result = this.ctx.storage.sql
    		.exec("SELECT 'Hello, World!' as greeting")
    		.one();
    	return result.greeting;
    }

}

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def say_hello(self):
        result = self.ctx.storage.sql.exec(
            "SELECT 'Hello, World!' as greeting"
        ).one()

        return result.greeting

Ve výše uvedeném kódu máte:

1. Definoval metodu RPC, sayHello(), kterou může Worker volat ke komunikaci s Durable Objectem.
2. Přistoupili jste k připojenému úložišti Durable Object, tedy k soukromé databázi SQLite dostupné pouze tomuto objektu, pomocí SQL API metody (sql.exec()) dostupné na ctx.storage .
3. Vrátil objekt reprezentující výsledek dotazu s jedním řádkem pomocí one(), která ověří, že výsledek dotazu obsahuje přesně jeden řádek.
4. Vrátit greeting sloupec z výsledného objektu řádku.

Worker se používá k přístup k Durable Objects.

Aby mohl Worker komunikovat s Durable Object, měl by jeho fetch handler vypadat následovně:

export default {
	async fetch(request, env, ctx) {
		const stub = env.MY_DURABLE_OBJECT.getByName(new URL(request.url).pathname);

		const greeting = await stub.sayHello();

		return new Response(greeting);
	},
};

export default {
	async fetch(request, env, ctx): Promise<Response> {
    	const stub = env.MY_DURABLE_OBJECT.getByName(new URL(request.url).pathname);

    	const greeting = await stub.sayHello();

    	return new Response(greeting);
    },

} satisfies ExportedHandler<Env>;

from workers import handler, Response, WorkerEntrypoint
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
    async def fetch(request):
        url = urlparse(request.url)
        stub = self.env.MY_DURABLE_OBJECT.getByName(url.path)
        greeting = await stub.say_hello()
        return Response(greeting)

Ve výše uvedeném kódu máte:

1. Exportovali jste hlavní obslužné rutiny událostí svého Workeru, například fetch() pro příjem HTTP požadavků.
2. Předáno env do fetch() handler. Vazby se předávají jako vlastnost objektu prostředí, který se předá jako druhý parametr při volání obslužné funkce události nebo konstruktoru třídy.
3. Vytvořil stub pro instanci Durable Object na základě zadaného názvu. Stub je klientský objekt, který slouží k odesílání zpráv Durable Object.
4. Zavolali jste Durable Object vyvoláním metody RPC, sayHello(), na Durable Objectu, která vrací Hello, World! řetězcový pozdrav.
5. Klientovi vrátil HTTP odpověď sestavenou pomocí return new Response().

Viz Přístup k Durable Object z Workeru a zjistěte více o komunikaci s Durable Object.

Bindings umožňují vašim Workers interagovat se zdroji na vývojářské platformě Cloudflare. Vazby Durable Object v konfiguraci projektu Workers Konfigurační soubor Wrangler bude obsahovat název vazby (pro tohoto průvodce použijte MY_DURABLE_OBJECT) a název třídy (MyDurableObject).

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				"class_name": "MyDurableObject"
			}
		]
	}
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"

bindings sekce obsahuje následující pole:

• name - Povinné. Název vazby použitý ve vašem Workeru.
• class_name - Povinné. Název třídy, ke které chcete vytvořit vazbu.
• script_name - Volitelné. Výchozí hodnotou je aktuální prostředí kód Workeru.

Každou třídu Durable Object, kterou váš Worker exportuje, deklarujete v exports pole konfiguračního souboru Wrangler. Cloudflare tuto deklaraci použije k vytvoření namespace pro danou třídu při prvním nasazení a ke správě jeho životního cyklu při dalších nasazeních (přejmenování, smazání, přenos).

Minimální exports blok pro registraci nové třídy Durable Object s úložištěm SQLite vypadá takto:

{
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite"
		}
	}
}

[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

Viz Exporty tříd Durable Object a zjistěte více o deklarování a správě tříd Durable Object. Pokud máte existující Worker na starším migrations pole naleznete v Migrace tříd Durable Object (zastaralé).

Chcete-li svůj Durable Object otestovat lokálně, spusťte wrangler dev:

npx wrangler dev

V konzoli byste měli vidětHello world řetězec vrácený Durable Objectem.

Chcete-li nasadit svůj Worker s Durable Object:

npx wrangler deploy

Po nasazení by se měl nově vytvořený Durable Object Worker zobrazit na Cloudflare dashboardu.

Náhled Workeru s Durable Object zobrazíte na <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

Váš výsledný kód by měl vypadat takto:

import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		// Required, as we are extending the base class.
		super(ctx, env);
	}

	async sayHello() {
		let result = this.ctx.storage.sql
			.exec("SELECT 'Hello, World!' as greeting")
			.one();
		return result.greeting;
	}
}
export default {
	async fetch(request, env, ctx) {
		const stub = env.MY_DURABLE_OBJECT.getByName(new URL(request.url).pathname);

		const greeting = await stub.sayHello();

		return new Response(greeting);
	},
};

import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we are extending the base class.
		super(ctx, env)
	}

    async sayHello():Promise<string> {
    	let result = this.ctx.storage.sql
    		.exec("SELECT 'Hello, World!' as greeting")
    		.one();
    	return result.greeting;
    }

}
export default {
async fetch(request, env, ctx): Promise<Response> {
const stub = env.MY_DURABLE_OBJECT.getByName(new URL(request.url).pathname);

    	const greeting = await stub.sayHello();

    	return new Response(greeting);
    },

} satisfies ExportedHandler<Env>;

from workers import DurableObject, handler, Response
from urllib.parse import urlparse

class MyDurableObject(DurableObject):
    async def say_hello(self):
        result = self.ctx.storage.sql.exec(
            "SELECT 'Hello, World!' as greeting"
        ).one()

        return result.greeting

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        url = urlparse(request.url)
        stub = self.env.MY_DURABLE_OBJECT.getByName(url.path)
        greeting = await stub.say_hello()
        return Response(greeting)

Po dokončení tohoto tutoriálu jste:

• Durable Object byl úspěšně vytvořen
• Zavolali jste Durable Object vyvoláním Metoda RPC
• Nasadil Durable Object globálně

• Vytváření stubů Durable Object
• Přístup k úložišti Durable Objects
• Miniflare ↗ - Užitečné nástroje pro mockování a testování vašich Durable Objects.