← Cloudflare Durable Objects / durable-objects / api

Durable Object Namespace

Пространство имён Durable Object представляет собой набор Durable Objects, использующих один и тот же Durable Object class. На каждый класс приходится ровно одно пространство имён Durable Object. Пространство имён Durable Object может содержать любое количество Durable Objects.

DurableObjectNamespace интерфейс используется для получения ссылки на новые или существующие Durable Objects. Этот интерфейс доступен из обработчика fetch в Cloudflare Worker через env параметр, представляющий собой стандартный интерфейс при обращении к привязкам, объявленным в конфигурационный файл Wrangler.

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

import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
    ...
  }
}

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
    ...
  }
} satisfies ExportedHandler<Env>;

from workers import DurableObject, WorkerEntrypoint

# Durable Object
class MyDurableObject(DurableObject):
  pass

# Worker
class Default(WorkerEntrypoint):
  async def fetch(self, request):
    # A stub is a client Object used to invoke methods defined by the Durable Object
    stub = self.env.MY_DURABLE_OBJECT.getByName("foo")
    # ...

idFromName создаёт уникальный DurableObjectId который указывает на отдельный экземпляр класса Durable Object. Именованные Durable Objects являются самым распространенным способом обращения к Durable Objects.

const fooId = env.MY_DURABLE_OBJECT.idFromName("foo");
const barId = env.MY_DURABLE_OBJECT.idFromName("bar");

• Обязательная строка, используемая для генерации DurableObjectId соответствующий имени Durable Object.

• A DurableObjectId указывающий на экземпляр класса Durable Object.

newUniqueId создаёт случайно сгенерированный уникальный DurableObjectId который указывает на отдельный экземпляр класса Durable Object. Идентификаторы, созданные с помощью newUniqueId, нужно будет сохранить в виде строки, чтобы в дальнейшем можно было снова обратиться к тому же Durable Object. Например, ID можно сохранить в Workers KV, в другом Durable Object или в cookie в браузере пользователя.

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });

• Необязательный объект с ключом jurisdiction и значение юрисдикция строка.

• A DurableObjectId указывающий на экземпляр этого класса Durable Object.

idFromString создаёт DurableObjectId из ранее сгенерированного ID, преобразованного в строку. Этот метод выбрасывает исключение, если ID недействителен, например если он не был создан на основе того же самого DurableObjectNamespace.

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

• Обязательная строка, соответствующая DurableObjectId ранее сгенерированный либо newUniqueId или idFromName.

• A DurableObjectId указывающий на экземпляр класса Durable Object.

get получает DurableObjectStub из DurableObjectId который можно использовать для вызова методов Durable Object.

Этот метод возвращает заглушку сразу же, часто ещё до того, как соединение с Durable Object будет установлено. Это позволяет немедленно отправлять запросы к экземпляру, не дожидаясь полного цикла обмена данными по сети.

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const stub = env.MY_DURABLE_OBJECT.get(id);

• Обязательный DurableObjectId
• Необязательный объект с ключом locationHint и значение locationHint строка.

• A DurableObjectStub указывающий на экземпляр класса Durable Object.

getByName получает DurableObjectStub из переданного имени, который можно использовать для вызова методов Durable Object.

Этот метод возвращает заглушку сразу же, часто ещё до того, как соединение с Durable Object будет установлено. Это позволяет немедленно отправлять запросы к экземпляру, не дожидаясь полного цикла обмена данными по сети.

const fooStub = env.MY_DURABLE_OBJECT.getByName("foo");
const barStub = env.MY_DURABLE_OBJECT.getByName("bar");

• Обязательная строка, используемая для генерации DurableObjectStub соответствующий экземпляру класса Durable Object с указанным именем.
• Необязательный объект с ключом locationHint и значение locationHint строка.

• A DurableObjectStub указывающий на экземпляр класса Durable Object.

jurisdiction создаёт подпространство имён из пространства имён, в котором все идентификаторы и ссылки Durable Object, созданные из этого подпространства, будут ограничены указанным юрисдикция.

const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
const euStub = subnamespace.getByName("foo");

• Обязательный юрисдикция строка.

• A DurableObjectNamespace привязанный к определённой нормативной или географической юрисдикции. Список географических юрисдикций постоянно расширяется, поэтому делитесь пожеланиями по нему на Discord-канал Durable Objects ↗.

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