← Images / images / storage

Správa hostovaných obrázků pomocí Workers

A binding propojuje váš Worker na externí zdroje na Developer Platform, například Obrázky, R2 buckety, nebo KV namespaces.

Při správě hostovaných obrázků umožňuje vazba Images vašemu Workeru nahrávat, vypisovat, načítat, aktualizovat a mazat hostované obrázky bez přímého volání REST API. Následující hosted zpřístupňuje operace pro ukládání a správu. Tuto vazbu (binding) lze také použít k optimalizovat hostované obrázky.

Bindings lze nakonfigurovat v Cloudflare dashboardu pro váš Worker nebo v konfiguračním souboru Wrangler v adresáři vašeho projektu.

Chcete-li Images svázat s Workerem, přidejte následující do konfiguračního souboru Wrangler:

{
	"images": {
		"binding": "IMAGES", // available in your Worker on env.IMAGES
	},
}

[images]
binding = "IMAGES"

V kódu Workeru můžete spravovat hostované obrázky pomocí env.IMAGES.hosted namespace.

env.IMAGES.hosted umožňuje nahrávat a vypisovat obrázky v rámci celého účtu. Ke správě konkrétního obrázku zavolejte .image(imageId) k získání handle a poté na něm zavolejte metodu.

Nahraje nový obrázek do vašeho účtu. Bajty obrázku můžete předat jako datový proud nebo ArrayBuffer. Vrací ImageMetadata.

Přijímá následující možnosti jako ImageUploadOptions objekt:

• id string : Vlastní ID, které se má obrázku přiřadit. Pokud ho vynecháte, Cloudflare vygeneruje UUID. Viz Nahrát na vlastní cestu.
• filename string : Název souboru, který se má k obrázku přiřadit.
• requireSignedURLs boolean : Určuje, zda je pro zobrazení obrázku vyžadována podepsaná URL adresa. Výchozí hodnota je false.
• metadata Record<string, unknown> : Libovolná metadata uložená společně s obrázkem.
• creator string : Uživatelem definovaný identifikátor autora obrázku.
• encoding 'base64' : nastaveno na base64 pokud jsou zadané bajty kódovány pomocí base64. Binding je před nahráním dekóduje.

Vypíše obrázky ve vašem účtu se stránkováním. Vrací ImageList.

Přijímá následující možnosti jako ImageListOptions objekt:

• limit number : Maximální počet obrázků vrácených na jedné stránce.
• cursor string : Token pro pokračování vrácený předchozím list() volání. Na první stránce vynechte.
• sortOrder 'asc' | 'desc' : Pořadí, ve kterém se výsledky řadí podle uploaded časové razítko. Výchozí hodnota je asc.
• creator string : Filtrujte výsledky na obrázky nahrané s tímto identifikátorem autora.

Vrátí popisovač (handle) pro jeden hostovaný obrázek. imageId může být UUID vygenerované Cloudflare nebo vlastní ID.

Samotný handle nevytváří síťový požadavek, takže jeho vytvoření je levné.

Získání metadat obrázku. Vrací ImageMetadata nebo null pokud obrázek se zadaným ID neexistuje.

Získání nezpracovaných bajtů obrázku. Vrací ReadableStream<Uint8Array> nebo null pokud obrázek se zadaným ID neexistuje. Tím se streamuje původní nahraný soubor. Předejte bajty obrázku do .input() k optimalizaci před doručením, nebo použijte URL vrácené v ImageMetadata.variants nebo doručovací URL adresa obrázku k doručení předdefinované varianty.

Aktualizuje metadata nebo řízení přístupu obrázku. Všechna pole jsou volitelná, změní se pouze zadaná pole. Vrací ImageMetadata s aktualizovanými hodnotami.

Přijímá následující možnosti jako ImageUpdateOptions objekt:

• requireSignedURLs boolean : Určuje, zda je pro zobrazení obrázku vyžadována podepsaná URL adresa. Nelze nastavit na true na obrázku, který byl nahrán s vlastní ID.
• metadata Record<string, unknown> : Náhradní metadata pro obrázek. Tato metadata nahradí ta stávající, místo aby se s nimi sloučila.
• creator string : Uživatelem definovaný identifikátor autora obrázku.

Odstraní obrázek. Vrátí true pokud byl obrázek odstraněn nebo false pokud obrázek se zadaným ID neexistoval.

export default {
	async fetch(request, env) {
		if (!request.body) {
			return new Response("Missing body", { status: 400 });
		}

		const image = await env.IMAGES.hosted.upload(request.body, {
			filename: "upload.jpg",
			metadata: { source: "worker" },
			requireSignedURLs: false,
		});

		return Response.json(image);
	},
};

export default {
	async fetch(request, env) {
		if (!request.body) {
			return new Response("Missing body", { status: 400 });
		}

		const image = await env.IMAGES.hosted.upload(request.body, {
			filename: "upload.jpg",
			metadata: { source: "worker" },
			requireSignedURLs: false,
		});

		return Response.json(image);
	},
};

Nastavte encoding: "base64" a binding tělo požadavku před nahráním sám dekóduje.

export default {
	async fetch(request, env) {
		if (!request.body) {
			return new Response("Missing body", { status: 400 });
		}

		const image = await env.IMAGES.hosted.upload(request.body, {
			encoding: "base64",
			filename: "upload.png",
		});

		return Response.json(image);
	},
};

export default {
	async fetch(request, env) {
		if (!request.body) {
			return new Response("Missing body", { status: 400 });
		}

		const image = await env.IMAGES.hosted.upload(request.body, {
			encoding: "base64",
			filename: "upload.png",
		});

		return Response.json(image);
	},
};

export default {
	async fetch(request, env) {
		let cursor;
		const ids = [];

		do {
			const page = await env.IMAGES.hosted.list({ limit: 100, cursor });
			ids.push(...page.images.map((image) => image.id));
			cursor = page.cursor;
		} while (cursor);

		return Response.json({ count: ids.length, ids });
	},
};

export default {
	async fetch(request, env) {
		let cursor: string | undefined;
		const ids: string[] = [];

		do {
			const page = await env.IMAGES.hosted.list({ limit: 100, cursor });
			ids.push(...page.images.map((image) => image.id));
			cursor = page.cursor;
		} while (cursor);

		return Response.json({ count: ids.length, ids });
	},
};

export default {
	async fetch(request, env) {
		const details = await env.IMAGES.hosted.image("IMAGE_ID").details();
		if (!details) {
			return new Response("Not found", { status: 404 });
		}
		return Response.json(details);
	},
};

export default {
	async fetch(request, env) {
		const details = await env.IMAGES.hosted.image("IMAGE_ID").details();
		if (!details) {
			return new Response("Not found", { status: 404 });
		}
		return Response.json(details);
	},
};

export default {
	async fetch(request, env) {
		const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
		if (!bytes) {
			return new Response("Not found", { status: 404 });
		}
		return new Response(bytes);
	},
};

export default {
	async fetch(request, env) {
		const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
		if (!bytes) {
			return new Response("Not found", { status: 404 });
		}
		return new Response(bytes);
	},
};

export default {
	async fetch(request, env) {
		const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({
			metadata: { reviewed: true },
		});
		return Response.json(updated);
	},
};

export default {
	async fetch(request, env) {
		const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({
			metadata: { reviewed: true },
		});
		return Response.json(updated);
	},
};

export default {
	async fetch(request, env) {
		const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete();
		return new Response(deleted ? "Deleted" : "Not found", {
			status: deleted ? 200 : 404,
		});
	},
};

export default {
	async fetch(request, env) {
		const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete();
		return new Response(deleted ? "Deleted" : "Not found", {
			status: deleted ? 200 : 404,
		});
	},
};

Tento příklad načte obrázek ze vzdálené URL adresy, nahraje jej do vašeho účtu Images a vrátí URL adresu první varianty.

export default {
	async fetch(request, env) {
		const upstream = await fetch("https://example.com/photo.jpg");
		if (!upstream.ok || !upstream.body) {
			return new Response("Upstream fetch failed", { status: 502 });
		}

		const image = await env.IMAGES.hosted.upload(upstream.body, {
			filename: "photo.jpg",
			metadata: { source: "example.com" },
		});

		return Response.json({
			id: image.id,
			variant: image.variants[0],
		});
	},
};

export default {
	async fetch(request, env) {
		const upstream = await fetch("https://example.com/photo.jpg");
		if (!upstream.ok || !upstream.body) {
			return new Response("Upstream fetch failed", { status: 502 });
		}

		const image = await env.IMAGES.hosted.upload(upstream.body, {
			filename: "photo.jpg",
			metadata: { source: "example.com" },
		});

		return Response.json({
			id: image.id,
			variant: image.variants[0],
		});
	},
};

Vráceno operacemi, které obrázek načítají, vytvářejí nebo aktualizují.

• id string
  • Jedinečný identifikátor obrázku.
• filename string volitelné
  • Původní název souboru zadaný při nahrávání.
• uploaded string volitelné
  • Datum a čas nahrání obrázku ve formátu řetězce ISO 8601.
• requireSignedURLs boolean
  • Zda je pro přístup k tomuto obrázku vyžadována podepsaná URL adresa. Více informací najdete v Poskytování soukromých obrázků.
• meta Record<string, unknown> volitelné
  • Metadata obrázku zadaná uživatelem.
• variants Array<string>
  • Plně sestavené adresy URL pro každou variantu nakonfigurovanou u vašeho účtu. Více informací najdete v Vytvoření variant.
• draft boolean volitelné
  • Zda je obrázek ve stavu konceptu (zatím nebyla nahrána žádná data). Koncepty se obvykle zobrazují jen u účtů používajících Direct Creator Uploads.
• creator string volitelné
  • Uživatelem definovaný identifikátor tvůrce obrázku.

Vráceno list().

• images Array<ImageMetadata>
  • Obrázky na této stránce výsledků.
• cursor string volitelné
  • Token pro pokračování, který se předává do dalšího list() volání. Přítomné pouze v případě, že existuje více výsledků.
• listComplete boolean
  • true pokud již nejsou žádné další stránky, false v opačném případě.

Metody, které selžou, vyhodí ImagesError, .upload(), .list(), .update() : s následujícími vlastnostmi:

• code number
  • Číselný kód chyby, který identifikuje typ selhání.
• message string
  • Popis chyby srozumitelný pro člověka.

Metody, které načtou jediný obrázek: .details(), .bytes(), a .delete() : vrátí null nebo false pro stav „nenalezeno“ místo vyvolání výjimky.

Operace, které mohou vyvolat výjimku, je vhodné obalit do try...catch blok.

Když spustíte wrangler dev, operace pro správu hostovaných obrázků obsluhuje lokální mock, který ukládá obrázky do vloženého KV namespace. Tento mock podporuje všechny metody popsané na této stránce, takže Worker můžete vyvíjet a testovat offline.

Mock je vhodný pouze pro lokální vývoj. Chcete-li ze svého lokálního prostředí použít skutečnou službu Images, spusťte wrangler dev --remote.

• Optimalizace pomocí Workers : Použijte binding k optimalizaci obrázků přímo z Workeru.
• Nahrát přes REST API : Odpovídající HTTP API.
• Správa hostovaných obrázků : Postupy pro správu uložených obrázků přes dashboard i API.