← Cloudflare Durable Objects / durable-objects / api

Durable Object ID

ID Durable Object je 64místní hexadecimální číslo, které identifikuje Durable Object. Ne všechna 64místná hexadecimální čísla jsou platná ID. ID Durable Object se nevytvářejí přímo, ale nepřímo pomocí DurableObjectNamespace rozhraní.

DurableObjectId rozhraní odkazuje na nový nebo existující Durable Object. Toto rozhraní se nejčastěji používá v DurableObjectNamespace::get pro získání DurableObjectStub pro odesílání požadavků do Durable Object. Vytvoření ID pro Durable Object ještě neznamená, že se Durable Object vytvoří. Durable Object vznikne líně, až po vytvoření stubu z DurableObjectId. Tím se zajistí, že se objekty nevytvoří, dokud k nim skutečně nedojde k přístupu.

toString převádí DurableObjectId na 64místní hexadecimální řetězec. Tento řetězec se hodí pro protokolování nebo pro uložení DurableObjectId jinde, například v session cookie. Tento řetězec lze použít k rekonstrukci DurableObjectId prostřednictvím DurableObjectNamespace::idFromString.

// Create a new unique ID
const id = env.MY_DURABLE_OBJECT.newUniqueId();
// Convert the ID to a string to be saved elsewhere, e.g. a session cookie
const session_id = id.toString();

...
// Recreate the ID from the string
const id = env.MY_DURABLE_OBJECT.idFromString(session_id);

• Žádné.

• 64místní hexadecimální řetězec.

equals se používá k porovnání rovnosti dvou instancí DurableObjectId.

const id1 = env.MY_DURABLE_OBJECT.newUniqueId();
const id2 = env.MY_DURABLE_OBJECT.newUniqueId();
console.assert(!id1.equals(id2), "Different unique ids should never be equal.");

id1 = env.MY_DURABLE_OBJECT.newUniqueId()
id2 = env.MY_DURABLE_OBJECT.newUniqueId()
assert not id1.equals(id2), "Different unique ids should never be equal."

• Povinný DurableObjectId pro porovnání.

• Booleovská hodnota. True, pokud jsou si rovny, jinak false.

name je volitelnou vlastností DurableObjectId, která vrací název použitý k vytvoření DurableObjectId prostřednictvím DurableObjectNamespace::idFromName. Tato hodnota je nedefinovaná, pokud DurableObjectId byl vytvořen pomocí DurableObjectNamespace::newUniqueId.

name vlastnost je dostupná také na ctx.id uvnitř Durable Object, pokud volající použije idFromName() nebo getByName(). ctx.id.name bude undefined v následujících případech:

• Volající přistupuje k Durable Object pomocí idFromString(), i když bylo ID původně vytvořeno pomocí idFromName().
• Názvy delší než 1,024 bajtů se nepředávají do ctx.id.
• Durable Object byl vytvořen s newUniqueId().

const uniqueId = env.MY_DURABLE_OBJECT.newUniqueId();
const fromNameId = env.MY_DURABLE_OBJECT.idFromName("foo");
console.assert(uniqueId.name === undefined, "unique ids have no name");
console.assert(
	fromNameId.name === "foo",
	"name matches parameter to idFromName",
);

const uniqueId: DurableObjectId = env.MY_DURABLE_OBJECT.newUniqueId();
const fromNameId: DurableObjectId = env.MY_DURABLE_OBJECT.idFromName("foo");
console.assert(uniqueId.name === undefined, "unique ids have no name");
console.assert(
	fromNameId.name === "foo",
	"name matches parameter to idFromName",
);

unique_id = env.MY_DURABLE_OBJECT.newUniqueId()
from_name_id = env.MY_DURABLE_OBJECT.idFromName("foo")
assert unique_id.name is None, "unique ids have no name"
assert from_name_id.name == "foo", "name matches parameter to idFromName"

Stejné name je uvnitř Durable Object dostupný přes ctx.id.name:

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject {
	async getRoomName() {
		return this.ctx.id.name; // "foo" when accessed via getByName("foo")
	}
}

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject<Env> {
	async getRoomName(): Promise<string | undefined> {
		return this.ctx.id.name; // "foo" when accessed via getByName("foo")
	}
}

from workers import DurableObject

class ChatRoom(DurableObject):
    async def get_room_name(self):
        return self.ctx.id.name  # "foo" when accessed via get_by_name("foo")

jurisdiction je volitelnou vlastností DurableObjectId, která vrací jurisdikce na kterou je ID omezeno, například "eu" nebo "fedramp". Stejná hodnota je uvnitř Durable Object dostupná přes ctx.id.jurisdiction, a to i v obslužné rutiny alarmů a objekty, ke kterým se přistupuje přes idFromString(), takže můžete činit rozhodnutí s ohledem na region, aniž byste jurisdikci předávali jako argument nebo ji ukládali do úložiště.

jurisdiction se zachová u každého způsobu vytvoření ID, včetně:

• ID vytvořená z podprostoru názvů omezeného na jurisdikci, například env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo") nebo .newUniqueId().
• ID vytvořená pomocí env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }).
• ID obnovená z řetězce pomocí idFromString(), jurisdikce je zakódována přímo v řetězci, takže funguje na jakékoli vazbě jmenného prostoru.

ctx.id.jurisdiction je undefined ve dvou případech:

• Durable Object nebyl vytvořen v jmenném prostoru s omezením jurisdikce.
• Alarm Durable Object byl naplánován před 2026-03-15. Chcete-li hodnotu doplnit zpětně, naplánujte alarm znovu z fetch() nebo RPC handler.

const plainId = env.MY_DURABLE_OBJECT.idFromName("foo");
const euId = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo");
console.assert(plainId.jurisdiction === undefined, "no jurisdiction set");
console.assert(euId.jurisdiction === "eu", "jurisdiction matches namespace");

plain_id = env.MY_DURABLE_OBJECT.idFromName("foo")
eu_id = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo")
assert plain_id.jurisdiction is None, "no jurisdiction set"
assert eu_id.jurisdiction == "eu", "jurisdiction matches namespace"

• Durable Objects: Easy, Fast, Correct, Choose Three ↗.