← Cloudflare Durable Objects / durable-objects / api

Durable Object ID

Durable Object ID представляет собой 64-значное шестнадцатеричное число, используемое для идентификации Durable Object. Не любое 64-значное шестнадцатеричное число является допустимым ID. ID Durable Object формируются не напрямую, а через DurableObjectNamespace интерфейс.

DurableObjectId интерфейс указывает на новый или существующий Durable Object. Чаще всего этот интерфейс используется DurableObjectNamespace::get чтобы получить DurableObjectStub для отправки запросов к Durable Object. Обратите внимание, что создание ID для Durable Object не создаёт сам Durable Object. Durable Object создаётся лениво после того, как заглушка (stub) создаётся на основе DurableObjectId. Это гарантирует, что объекты не создаются до тех пор, пока к ним действительно не обратятся.

toString преобразует DurableObjectId в 64-значную шестнадцатеричную строку. Эта строка полезна для журналирования или для хранения DurableObjectId в другом месте, например в cookie сессии. Эта строка может использоваться для восстановления DurableObjectId через 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);

• Нет.

• Шестнадцатеричная строка из 64 цифр.

equals используется для сравнения на равенство двух экземпляров 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."

• Обязательный DurableObjectId для сравнения.

• Логическое значение. True, если объекты равны, и false в противном случае.

name является необязательным свойством DurableObjectId, который возвращает имя, использованное при создании DurableObjectId через DurableObjectNamespace::idFromName. Это значение не определено, если DurableObjectId был создан с использованием DurableObjectNamespace::newUniqueId.

name свойство также доступно в ctx.id внутри Durable Object, когда вызывающая сторона использует idFromName() или getByName(). ctx.id.name будет undefined в следующих случаях:

• Вызывающая сторона обращается к Durable Object с помощью idFromString(), даже если ID изначально был создан с помощью idFromName().
• Имена длиннее 1,024 байт не передаются в ctx.id.
• Durable Object был создан с 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"

Тот же name доступен внутри Durable Object через 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 является необязательным свойством DurableObjectId, который возвращает юрисдикция к которой привязан данный ID, например "eu" или "fedramp". То же значение доступно внутри Durable Object через ctx.id.jurisdiction, в том числе в обработчики alarm и объектам, доступ к которым осуществляется через idFromString(), поэтому вы можете принимать решения с учётом региона, не передавая юрисдикцию в качестве аргумента и не сохраняя её в хранилище.

jurisdiction сохраняется при любом способе построения идентификатора, включая:

• Идентификаторы, созданные в подпространстве имён с ограничением по юрисдикции, например env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo") или .newUniqueId().
• Идентификаторы, созданные с помощью env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }).
• Идентификаторы, восстановленные из строки с помощью idFromString() : юрисдикция закодирована в самой строке, поэтому это работает с любой привязкой пространства имён.

ctx.id.jurisdiction это undefined в двух случаях:

• Durable Object не был создан в пространстве имён с ограничением по юрисдикции.
• Alarm этого Durable Object был запланирован до 2026-03-15. Чтобы заполнить значение задним числом, перепланируйте alarm из fetch() или обработчика RPC.

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 ↗.