INTEGRITY Dokumentace

← Cloudflare R2 / r2 / api / workers

Referenční dokumentace Workers API

K API R2 uvnitř Workeru se přistupuje navázáním bucketu R2 na Worker. Worker, který napíšete, může prostřednictvím route poskytovat externí přístup k bucketům, nebo interně pracovat s objekty R2.

R2 API obsahuje některá rozšíření a sémantické rozdíly oproti S3 API. Pokud potřebujete kompatibilitu s S3, zvažte použití S3 kompatibilní API.

Základní pojmy

R2 organizuje uložená data, označovaná jako objekty, do kontejnerů označovaných jako buckety. Buckety jsou základní jednotkou výkonu, škálování a přístupu v rámci R2.

Vytvoření bindingu

Chcete-li svázat bucket R2 se svým Workerem, přidejte do souboru Wrangler následující. Aktualizujte binding vlastnost na platný identifikátor proměnné v JavaScriptu a bucket_name na název vašeho bucketu R2:

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET", // <~ valid JavaScript variable name
			"bucket_name": "<YOUR_BUCKET_NAME>"
		}
	]
}
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

Ve vašem Workeru je nyní vazba na bucket dostupná pod MY_BUCKET proměnná a můžete s ní začít pracovat pomocí metody bucketu popsáno níže.

Definice metod bucketu

Na objektu vazby bucketu vloženém do vašeho kódu jsou k dispozici následující metody.

Pokud chcete například odeslat PUT objekt pomocí výše uvedeného propojení (binding):

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		switch (request.method) {
			case "PUT":
				await env.MY_BUCKET.put(key, request.body);
				return new Response(`Put ${key} successfully!`);

			default:
				return new Response(`${request.method} is not allowed.`, {
					status: 405,
					headers: {
						Allow: "PUT",
					},
				});
		}
	},
};
from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if request.method == "PUT":
			await self.env.MY_BUCKET.put(key, request.body)
			return Response(f"Put {key} successfully!")
		else:
			return Response(
				f"{request.method} is not allowed.",
				status=405,
				headers={"Allow": "PUT"}
			)

R2Object definice

R2Object se vytvoří, když PUT objekt do R2 bucketu. R2Object představuje metadata objektu na základě informací poskytnutých nahrávajícím. Každý objekt, který PUT do R2 bucketu bude mít R2Object vytvořeno.

R2ObjectBody definice

R2ObjectBody představuje metadata objektu spolu s jeho tělem. Vrací se, když GET objekt z bucketu R2. Úplný seznam klíčů pro R2ObjectBody zahrnuje seznam níže a všechny klíče zděděné z R2Object.

R2MultipartUpload definice

R2MultipartUpload objekt se vytvoří při volání createMultipartUpload nebo resumeMultipartUpload. R2MultipartUpload představuje probíhající vícedílné nahrávání.

Nedokončené vícedílné nahrávání se po 7 dnech automaticky zruší.

Typy specifické pro metodu

R2GetOptions

Čtení v rozsahu

R2GetOptions přijímá range parametr, který lze použít k omezení dat vrácených v body.

Existují 3 varianty argumentů, které lze použít v rozsahu:

R2PutOptions

R2MultipartOptions

R2ListOptions

const options = {
	limit: 500,
	include: ["customMetadata"],
};

const listed = await env.MY_BUCKET.list(options);

let truncated = listed.truncated;
let cursor = truncated ? listed.cursor : undefined;

// ❌ - if your limit can't fit into a single response or your
// bucket has less objects than the limit, it will get stuck here.
while (listed.objects.length < options.limit) {
	// ...
}

// ✅ - use the truncated property to check if there are more
// objects to be returned
while (truncated) {
	const next = await env.MY_BUCKET.list({
		...options,
		cursor: cursor,
	});
	listed.objects.push(...next.objects);

	truncated = next.truncated;
	cursor = next.cursor;
}
limit = 500
include = ["customMetadata"]

listed = await self.env.MY_BUCKET.list(limit=limit, include=include)

truncated = listed.truncated
cursor = listed.cursor if truncated else None

# ❌ - if your limit can't fit into a single response or your
# bucket has less objects than the limit, it will get stuck here.
while len(listed.objects) < limit:
    ...

# ✅ - use the truncated property to check if there are more
# objects to be returned
while truncated:
    next_page = await self.env.MY_BUCKET.list(limit=limit, include=include, cursor=cursor)
    listed.objects.extend(next_page.objects)

    truncated = next_page.truncated
    cursor = next_page.cursor

R2Objects

Objekt obsahující R2Object pole, vrácené BUCKET_BINDING.list().

Podmíněné operace

Můžete předat R2Conditional objekt na R2GetOptions a R2PutOptions. Pokud kontrola podmínky pro get() selže, tělo nebude vráceno. Díky tomu bude get() mají nižší latenci.

Pokud kontrola podmínky pro put() selže, null bude vrácen místo R2Object.

Alternativně můžete předat Headers objekt obsahující podmíněné hlavičky do R2GetOptions a R2PutOptions. Informace o těchto podmíněných hlavičkách najdete v dokumentace MDN o podmíněných požadavcích ↗. Všechny podmíněné hlavičky kromě If-Range jsou podporovány.

Podrobnější informace o podmíněných požadavcích najdete v RFC 7232 ↗.

Metadata HTTP

Tato pole obvykle odpovídají metadatům HTTP předaným při vytvoření objektu. Lze je přepsat při vydání GET požadavků, v takovém případě budou zadané hodnoty vráceny zpět v odpovědi.

Kontrolní součty

Pokud byl zadán kontrolní součet při použití put() binding bude k dispozici na vráceném objektu pod checksums vlastnost. Kontrolní součet MD5 bude ve výchozím nastavení zahrnut u objektů, které nejsou vícedílné.

R2UploadedPart

R2UploadedPart objekt představuje část, která byla nahrána. R2UploadedPart objekty se vracejí z uploadPart operace a musí být předán do completeMultipartUpload operace.

Třída úložiště

Třída úložiště, kde R2Object se ukládá. Dostupné třídy úložiště jsou Standard a InfrequentAccess. Viz Třídy úložiště pro více informací.