← Cloudflare Durable Objects / durable-objects / api

Durable Object Namespace

Namespace Durable Object je množina Durable Objects, které jsou podpořeny stejnou Třída Durable Object. Na jednu třídu připadá pouze jeden namespace Durable Object. Namespace Durable Object může obsahovat libovolný počet Durable Objects.

DurableObjectNamespace rozhraní slouží k získání odkazu na nový nebo existující Durable Object. Toto rozhraní je z fetch handleru Cloudflare Workeru dostupné přes env parametr, což je standardní rozhraní pro odkazování na vazby deklarované v Konfigurační soubor Wrangler.

Toto rozhraní definuje několik metody kterou lze použít k vytvoření ID pro Durable Object. Vytvoření ID pro Durable Object přitom samotný Durable Object nevytváří. Durable Object se vytvoří líně (lazily) až po zavolání DurableObjectNamespace::get pro vytvoření DurableObjectStub z DurableObjectId. Tím se zajistí, že se objekty nevytvoří, dokud k nim skutečně nedojde k přístupu.

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 vytvoří jedinečný DurableObjectId která odkazuje na jednotlivou instanci třídy Durable Object. Pojmenované Durable Objects jsou nejběžnějším způsobem, jak na Durable Objects odkazovat.

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

• Povinný řetězec použitý ke generování DurableObjectId odpovídající názvu Durable Object.

• A DurableObjectId odkazující na instanci třídy Durable Object.

newUniqueId vytvoří náhodně vygenerovaný a jedinečný DurableObjectId která odkazuje na jednotlivou instanci třídy Durable Object. ID vytvořená pomocí newUniqueId, je nutné uložit jako řetězec, abyste se v budoucnu mohli znovu odkázat na stejný Durable Object. ID lze uložit například do Workers KV, do jiného Durable Objectu nebo do cookie v prohlížeči uživatele.

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

• Volitelný objekt s klíčem jurisdiction a hodnota jurisdikce řetězec.

• A DurableObjectId odkazující na instanci dané třídy Durable Object.

idFromString vytvoří DurableObjectId z dříve vygenerovaného ID, které bylo převedeno na řetězec. Tato metoda vyvolá výjimku, pokud je ID neplatné, například pokud nebylo vytvořeno ze stejného 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);

• Povinný řetězec odpovídající DurableObjectId dříve vygenerovaný buď pomocí newUniqueId nebo idFromName.

• A DurableObjectId odkazující na instanci třídy Durable Object.

get získá DurableObjectStub z DurableObjectId kterou lze použít k volání metod na Durable Object.

Tato metoda vrací stub okamžitě, často ještě dříve, než se podaří navázat spojení s Durable Object. Díky tomu lze požadavky odeslat instanci ihned, bez čekání na síťovou odezvu.

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

• Povinný DurableObjectId
• Volitelný objekt s klíčem locationHint a hodnota locationHint řetězec.

• A DurableObjectStub odkazující na instanci třídy Durable Object.

getByName získá DurableObjectStub ze zadaného názvu, které lze použít k volání metod na Durable Object.

Tato metoda vrací stub okamžitě, často ještě dříve, než se podaří navázat spojení s Durable Object. Díky tomu lze požadavky odeslat instanci ihned, bez čekání na síťovou odezvu.

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

• Povinný řetězec použitý ke generování DurableObjectStub odpovídající instanci třídy Durable Object se zadaným názvem.
• Volitelný objekt s klíčem locationHint a hodnota locationHint řetězec.

• A DurableObjectStub odkazující na instanci třídy Durable Object.

jurisdiction vytvoří subnamespace z namespace, ve kterém budou všechna ID a reference Durable Object vytvořené z tohoto subnamespace omezeny na zadaný jurisdikce.

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

• Povinný jurisdikce řetězec.

• A DurableObjectNamespace omezený na konkrétní regulační nebo geografickou jurisdikci. Další geografické jurisdikce jsou průběžně vyhodnocovány, proto požadavky sdílejte v Kanál Durable Objects na Discordu ↗.

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