Durable Object ID 是用于标识 Durable Object 的 64 位十六进制数字。并非所有 64 位十六进制数字都是有效 ID。Durable Object ID 通过 DurableObjectNamespace 接口间接构造。
DurableObjectId 接口指向新或现有的 Durable Object。此接口最常由 DurableObjectNamespace::get 使用，以获取 DurableObjectStub 来向 Durable Object 提交请求。请注意，为 Durable Object 创建 ID 不会创建 Durable Object。Durable Object 在从 DurableObjectId 创建 stub 后延迟创建。这确保对象在实际访问之前不会被构造。
toString 将 DurableObjectId 转换为 64 位十六进制字符串。此字符串可用于日志记录目的或在其他地方存储 DurableObjectId，例如在会话 cookie 中。此字符串可用于通过 DurableObjectNamespace::idFromString 重建 DurableObjectId。
// 创建一个新的唯一 ID
const id = env.MY_DURABLE_OBJECT.newUniqueId();
// 将 ID 转换为字符串以便保存在其他地方，例如会话 cookie
const session_id = id.toString();
...
// 从该字符串重新创建 ID
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 的可选属性，返回通过 DurableObjectNamespace::idFromName 创建 DurableObjectId 时使用的名称。如果 DurableObjectId 是使用 DurableObjectNamespace::newUniqueId 构造的，则此值为 undefined。
当调用者使用 idFromName() 或 getByName() 时，name 属性也在 Durable Object 内部的 ctx.id 上可用。在以下情况下 ctx.id.name 将为 undefined：
- 调用者使用
idFromString()访问 Durable Object，即使 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 可通过 ctx.id.name 在 Durable Object 内部获取：
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"。相同的值可通过 ctx.id.jurisdiction 在 Durable Object 内部获取，包括在 alarm 处理器 和通过 idFromString() 访问的对象中，因此您可以做出区域感知决策，而无需将司法管辖区作为参数传递或持久化到存储中。
jurisdiction 在所有 ID 构造路径中保留，包括：
- 从限制司法管辖区的子 namespace 创建的 ID，例如
env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo")或.newUniqueId()。 - 通过
env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" })创建的 ID。 - 通过
idFromString()从字符串恢复的 ID——司法管辖区编码在字符串本身中，因此在任何 namespace 绑定上都有效。
ctx.id.jurisdiction 在两种情况下为 undefined：
- Durable Object 未在限制司法管辖区的 namespace 中创建。
- Durable Object 的 alarm 在 2026-03-15 之前调度。要回填该值，请从
fetch()或 RPC 处理器重新调度 alarm。
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"