INTEGRITY Документация

← Cloudflare R2 / r2 / api / workers

Справочник Workers API

Доступ к API R2 внутри Worker осуществляется путём привязки бакета R2 к Worker. Написанный вами Worker может предоставлять внешний доступ к бакетам через маршрут или работать с объектами R2 изнутри.

R2 API включает ряд расширений и семантических отличий от S3 API. Если вам необходима совместимость с S3, рассмотрите использование S3-совместимый API.

Основные понятия

Данные, которые вы храните в R2, называются объектами и организованы в контейнеры, называемые бакетами. Бакеты являются базовой единицей производительности, масштабирования и доступа в R2.

Создание привязки

Чтобы привязать бакет R2 к своему Worker, добавьте следующее в файл Wrangler. Обновите binding свойство в допустимый идентификатор переменной JavaScript и bucket_name к имени вашего бакета 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>"

Теперь в вашем Worker привязка к бакету доступна через MY_BUCKET переменную, после чего вы можете начать работу с ней с помощью методы бакета описано ниже.

Определения методов бакета

На объекте привязки бакета, внедрённом в ваш код, доступны следующие методы.

Например, чтобы выполнить PUT объекта с помощью указанной выше привязки:

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 определение

R2Object создаётся, когда вы PUT объект в бакет R2. R2Object представляет метаданные объекта на основе информации, предоставленной загрузившим его пользователем. Каждый объект, который вы PUT в бакет R2 будет иметь R2Object создан.

R2ObjectBody определение

R2ObjectBody представляет собой метаданные объекта в сочетании с его телом. Он возвращается, когда вы GET объект из бакета R2. Полный список ключей для R2ObjectBody включает список ниже и все ключи, унаследованные от R2Object.

R2MultipartUpload определение

Одна R2MultipartUpload объект создаётся при вызове createMultipartUpload или resumeMultipartUpload. R2MultipartUpload представляет текущую составную загрузку.

Незавершённые составные загрузки будут автоматически отменены через 7 дней.

Типы, специфичные для метода

R2GetOptions

Чтение по диапазону

R2GetOptions принимает range параметр, который можно использовать для ограничения данных, возвращаемых в body.

Существует 3 варианта аргументов, которые можно использовать в диапазоне:

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

Объект, содержащий R2Object массив, возвращаемый BUCKET_BINDING.list().

Условные операции

Можно передать R2Conditional объект на R2GetOptions и R2PutOptions. Если проверка условия для get() завершается ошибкой, тело не будет возвращено. Из-за этого get() имеют меньшую задержку.

Если проверка условия для put() завершается ошибкой, null будет возвращён вместо R2Object.

Также вы можете передать Headers объект, содержащий условные заголовки, в R2GetOptions и R2PutOptions. Информацию об этих условных заголовках см. документация MDN по условным запросам ↗. Все условные заголовки, кроме If-Range поддерживаются.

Более подробную информацию об условных запросах см. RFC 7232 ↗.

HTTP-метаданные

Как правило, эти поля соответствуют HTTP-метаданным, переданным при создании объекта. Их можно переопределить при выполнении GET запросов, в этом случае указанные значения будут возвращены в ответе.

Контрольные суммы

Если контрольная сумма была указана при использовании put() привязку, он будет доступен в возвращаемом объекте под checksums свойство. По умолчанию контрольная сумма MD5 включается для объектов, загруженных не через многосоставную (multipart) загрузку.

R2UploadedPart

Одна R2UploadedPart объект представляет часть, которая была загружена. R2UploadedPart объекты возвращаются из uploadPart операции и должен быть передан в completeMultipartUpload операции.

Класс хранения

Класс хранения, в котором R2Object хранится. Доступными классами хранения являются Standard и InfrequentAccess. См. Классы хранения для получения дополнительной информации.