← Cloudflare Queues / queues

Začínáme

Cloudflare Queues je flexibilní systém frontování zpráv, který umožňuje řadit zprávy pro asynchronní zpracování. Podle tohoto návodu vytvoříte svou první frontu, Worker, který do ní bude zveřejňovat zprávy, a Worker konzumenta, který je z fronty bude zpracovávat.

Chcete-li používat Queues, budete potřebovat:

1. Zaregistrujte si účet Cloudflare ↗.
2. Nainstalujte Node.js ↗.

K frontě budete přistupovat z Workeru, konkrétně z Workeru producenta. Musíte vytvořit alespoň jeden Worker producenta, aby mohl do fronty publikovat zprávy. Pokud používáte R2 Bucket Event Notifications, pak nepotřebujete Worker producenta.

Chcete-li vytvořit producentský Worker, spusťte:

npm create cloudflare@latest -- producer-worker

Při nastavení vyberte následující možnosti:

• Pro S čím byste chtěli začít?, vyberte Hello World example.
• Pro Jakou šablonu chcete použít?, vyberte Worker only.
• Pro Jaký jazyk chcete použít?, vyberte TypeScript.
• Pro Chcete používat git pro správu verzí?, vyberte Yes.
• Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).

Tímto se vytvoří nový adresář, který bude obsahovat jak src/index.ts skript Workeru a wrangler.jsonc konfiguračního souboru. Po vytvoření Workeru vytvoříte frontu, ke které bude přistupovat.

Přejděte do nově vytvořeného adresáře:

cd producer-worker

Chcete-li fronty používat, musíte nejprve vytvořit alespoň jednu frontu, do které budete zprávy publikovat a ze které je budete odebírat.

Chcete-li vytvořit frontu, spusťte:

npx wrangler queues create <MY-QUEUE-NAME>

Zvolte popisný název, který vystihuje typ zpráv, pro které frontu použijete. Popisné názvy front vypadají například takto: debug-logs, user-clickstream-data, nebo password-reset-prod.

Název fronty musí mít délku 1 až 63 znaků. Název fronty nesmí obsahovat speciální znaky kromě spojovníků (-), musí začínat a končit písmenem nebo číslem.

Název fronty po jeho nastavení nelze změnit. Po vytvoření fronty nastavíte Worker producenta, aby k ní měl přístup.

Aby byla fronta dostupná v kódu vašeho Workeru, musíte frontu s Workerem propojit vytvořením bindingu. Bindings umožňují Workeru přistupovat k prostředkům, jako jsou Queues, na vývojářské platformě Cloudflare.

Chcete-li vytvořit binding, otevřete nově vygenerovaný wrangler.jsonc soubor a přidejte následující:

{
	"queues": {
		"producers": [
			{
				"queue": "MY-QUEUE-NAME",
				"binding": "MY_QUEUE"
			}
		]
	}
}

[[queues.producers]]
queue = "MY-QUEUE-NAME"
binding = "MY_QUEUE"

Nahraďte MY-QUEUE-NAME názvem fronty, kterou jste vytvořili v krok 2. Dále nahraďte MY_QUEUE názvem, který chcete použít pro svůj binding. Vazba musí být platný název proměnné JavaScript. Tuto proměnnou použijete k odkazování na tuto frontu ve vašem Workeru.

Nyní nakonfigurujete Worker producenta tak, aby vytvářel zprávy k publikování do fronty. Váš Worker producenta bude:

1. Přijme požadavek, který obdrží z prohlížeče.
2. Transformujte požadavek do formátu JSON.
3. Zapište požadavek přímo do fronty.

V adresáři svého projektu Worker otevřete src složky a přidejte následující do svého index.ts soubor:

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const log = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers),
    };
    await env.<MY_QUEUE>.send(log);
    return new Response("Success!");
  },
} satisfies ExportedHandler<Env>;

Nahraďte MY_QUEUE názvem, který jste nastavili pro vazbu ve svém wrangler.jsonc .

Frontu také přidejte do Env rozhraní v index.ts.

export interface Env {
   <MY_QUEUE>: Queue;
}

Pokud tento zápis selže, váš Worker vrátí chybu (vyvolá výjimku). Pokud zápis proběhne úspěšně, vrátí Success s HTTP 200 stavový kód prohlížeči.

V produkční aplikaci byste pravděpodobně použili try...catch ↗ příkaz, který výjimku zachytí a zpracuje přímo (například vrátí vlastní chybu nebo ji dokonce zopakuje).

S vaším souborem Wrangler a index.ts soubor nakonfigurovaný, jste připraveni publikovat svůj producentský Worker. Pro jeho publikování spusťte:

npx wrangler deploy

Měli byste vidět výstup podobný tomu níže, s *.workers.dev URL adresu ve výchozím nastavení.

Uploaded <YOUR-WORKER-NAME> (0.76 sec)
Published <YOUR-WORKER-NAME> (0.29 sec)
  https://<YOUR-WORKER-NAME>.<YOUR-ACCOUNT>.workers.dev

Zkopírujte své *.workers.dev subdomény a vložte ji do nové karty prohlížeče. Několikrát obnovte stránku, abyste do fronty začali publikovat požadavky. Prohlížeč by měl vrátit Success odpověď po každém zapsání požadavku do fronty.

Vytvořili jste frontu a Worker producenta, který do ní publikuje zprávy. Nyní vytvoříte Worker konzumenta, který bude zveřejněné zprávy z fronty konzumovat. Bez Workeru konzumenta zůstanou zprávy ve frontě, dokud jejich platnost nevyprší, což je ve výchozím nastavení po čtyřech (4) dnech.

Worker konzumenta přijímá zprávy z vaší fronty. Jakmile je přijme, může je zapsat do jiného zdroje, například do logovací konzole nebo úložných objektů.

V tomto průvodci vytvoříte konzumujícího Workera a použijete ho k zaznamenávání a kontrole zpráv pomocí wrangler tail. Worker konzumenta vytvoříte ve stejném projektu Workeru, ve kterém jste vytvořili Worker producenta.

Chcete-li vytvořit konzumentský Worker, otevřete svůj index.ts soubor a přidejte následující queue handler do svého stávajícího fetch handler:

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const log = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers),
    };
    await env.<MY_QUEUE>.send(log);
    return new Response("Success!");
  },
  async queue(batch, env, ctx): Promise<void> {
    for (const message of batch.messages) {
      console.log("consumed from our queue:", JSON.stringify(message.body));
    }
  },
} satisfies ExportedHandler<Env>;

Nahraďte MY_QUEUE názvem, který jste nastavili pro vazbu ve svém wrangler.jsonc .

Pokaždé, když jsou do fronty publikovány zprávy, se u vašeho konzumujícího Workeru spustí queue handleru (async queue) je zavolána a je jí předána jedna nebo více zpráv.

V tomto příkladu váš konzumující Worker převede zprávu fronty ve formátu JSON na řetězec a tento výstup zaznamená do logu. V reálné aplikaci lze konzumujícího Workera nakonfigurovat tak, aby zprávy zapisoval do objektového úložiště (například R2), zapisovat do databáze (například D1), dále zpracovat zprávy před voláním externího API (například e-mailové API) nebo datový sklad u vašeho stávajícího cloudového poskytovatele.

Při provádění asynchronních úloh uvnitř handleru konzumenta použijte waitUntil() aby bylo zajištěno zpracování odpovědi funkce. Jiné asynchronní metody nejsou v rámci této metody podporovány.

Jakmile máte Worker konzumenta nakonfigurovaný, můžete ho připojit k frontě.

Ke každé frontě může být připojený jen jeden Worker konzumenta. Pokud se pokusíte k téže frontě připojit více konzumentů, při publikování tohoto Workeru dojde k chybě.

Chcete-li propojit frontu s konzumentským Workerem, otevřete soubor Wrangler a na konec přidejte následující:

{
	"queues": {
		"consumers": [
			{
				"queue": "<MY-QUEUE-NAME>",
				// Required: this should match the name of the queue you created in step 3.
				// If you misspell the name, you will receive an error when attempting to publish your Worker.
				"max_batch_size": 10, // optional: defaults to 10
				"max_batch_timeout": 5 // optional: defaults to 5 seconds
			}
		]
	}
}

[[queues.consumers]]
queue = "<MY-QUEUE-NAME>"
max_batch_size = 10
max_batch_timeout = 5

Nahraďte MY-QUEUE-NAME frontou, kterou jste vytvořili v krok 2.

V konzumujícím Workeru využíváte fronty k automatickému dávkování zpráv pomocí max_batch_size a max_batch_timeout. Spotřebitelský Worker bude přijímat zprávy v dávkách o velikosti 10 nebo každých 5 sekund, podle toho, co nastane dříve.

max_batch_size (výchozí hodnota 10) pomáhá snížit počet volání konzumentského Workeru. Místo volání pro každou jednotlivou zprávu se Worker zavolá až po vstupu 10 zpráv do fronty.

max_batch_timeout (výchozí hodnota 5 sekund) pomáhá zkrátit dobu čekání. Pokud producentský Worker neodesílá do fronty až 10 zpráv potřebných k vyvolání konzumentského Workeru, bude tento Worker volán každých 5 sekund, aby přijal zprávy čekající ve frontě.

S vaším souborem Wrangler a index.ts soubor nakonfigurovaný, publikujte svůj konzumentský Worker spuštěním:

npx wrangler deploy

Jakmile nastavíte Worker konzumenta, můžete z fronty číst zprávy.

Spustit wrangler tail a začněte čekat, až náš spotřebitel zaznamená přijaté zprávy:

npx wrangler tail

S wrangler tail spuštěné, otevřete URL adresu Workeru, kterou jste otevřeli v krok 3.

Měli byste obdržet Success zprávu v okně prohlížeče.

Pokud obdržíte Success zprávu, obnovte URL několikrát, abyste vygenerovali zprávy a odeslali je do fronty.

S wrangler tail spuštěné, váš spotřebitelský Worker začne zaznamenávat požadavky generované obnovováním stránky.

Pokud stránku obnovíte méně než desetkrát, může chvíli trvat, než se zprávy zobrazí, protože časový limit dávky je nastaven na 10 sekund. Po 10 sekundách by se zprávy měly objevit ve vašem terminálu.

Pokud se při obnovení stránky zobrazí chyby, ověřte, že název fronty, kterou jste vytvořili v krok 2 a fronta, na kterou odkazujete ve svém souboru Wrangler, je stejná. Měli byste zajistit, aby váš producentský Worker vracel Success a nevrací chybu.

Dokončením tohoto návodu jste vytvořili frontu, Worker producenta, který do ní zveřejňuje zprávy, a Worker konzumenta, který tyto zprávy z fronty zpracovává.

• Další informace o Cloudflare Workers a aplikace, které můžete na Cloudflare vytvářet.