Workers API 参考

Worker 内 R2 API 通过将 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"}
			)

head (key: string): Promise<R2Object | null>
- 检索给定键的 R2Object（仅含对象元数据），键存在时返回对象，不存在时返回 null。
get (key: string, options?: R2GetOptions): Promise<R2ObjectBody | R2Object | null>
- 检索给定键的 R2ObjectBody（含对象元数据和 ReadableStream 形式的对象体），键存在时返回对象，不存在时返回 null。
- 若 options 中指定的 precondition 失败，get() 返回 body 为 undefined 的 R2Object。
put (key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions): Promise<R2Object | null>
- 在关联的 key 下存储给定的 value 和元数据。写入成功后，返回包含已存储对象元数据的 R2Object。
- 若 options 中指定的 precondition 失败，put() 返回 null，对象不会被存储。
- R2 写入具有强一致性。Promise resolve 后，所有后续读取操作将在全球范围内看到此键值对。
delete (key: string | string[]): Promise<void>
- 删除关联 keys 下给定的 values 和元数据。删除成功后返回 void。
- R2 删除具有强一致性。Promise resolve 后，所有后续读取操作将不再在全球范围内看到提供的键值对。
- 每次调用最多可删除 1000 个键。
list (options?: R2ListOptions): Promise<R2Objects>
- 返回包含存储桶内 R2Object 列表的 R2Objects。
- 返回的对象列表按字典序排列。
- 最多返回 1000 条，为减少 Worker 内内存压力可能返回更少。
- 要显式设置列出对象数量，请提供设置了 limit 属性的 R2ListOptions 对象。

createMultipartUpload (key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>
- 创建分片上传。
- 返回 resolve 为 R2MultipartUpload 对象的 Promise，表示新创建的分片上传。分片上传创建后，可通过 Workers API 或 S3 API 立即在全球范围交互。

resumeMultipartUpload (key: string, uploadId: string): R2MultipartUpload
- 返回表示具有给定 key 和 uploadId 的分片上传的对象。
- resumeMultipartUpload 操作不检查 uploadId 的有效性，也不验证是否存在对应的活跃分片上传。这是为了减少在可对 R2MultipartUpload 对象调用后续操作之前的延迟。

`R2Object` 定义

R2Object 在您向 R2 存储桶 PUT 对象时创建。R2Object 表示基于上传者提供信息的对象元数据。向 R2 存储桶 PUT 的每个对象都会创建 R2Object。

key string
- 对象的键。
version string
- 与键的特定上传关联的随机唯一字符串。
size number
- 对象大小（字节）。
etag string

与对象上传关联的 etag。
httpEtag string
- 对象的 etag，带引号以便作为请求头返回。
uploaded Date
- 表示对象上传时间的 Date 对象。
httpMetadata R2HTTPMetadata
- 与对象关联的各种 HTTP 请求头。请参阅 HTTP 元数据。
customMetadata Record<string, string>
- 与对象关联的自定义用户定义元数据映射。
range R2Range
- 包含对象返回范围的 R2Range 对象。
checksums R2Checksums
- 包含对象存储校验和的 R2Checksums 对象。请参阅 checksums。
writeHttpMetadata (headers: Headers): void
- 从 R2Object 检索 httpMetadata 并将其对应的 HTTP 请求头应用到 Headers 输入对象。请参阅 HTTP 元数据。
storageClass 'Standard' | 'InfrequentAccess'
- 与对象关联的存储类别。请参阅存储类别。
ssecKeyMd5 string
- 用于加密的 SSE-C 密钥的十六进制 MD5 哈希（若提供）。哈希可用于识别解密对象所需的密钥。

`R2ObjectBody` 定义

R2ObjectBody 表示对象元数据与其体的组合。从 R2 存储桶 GET 对象时返回。R2ObjectBody 的完整键列表包括以下列表及从 R2Object 继承的所有键。

body ReadableStream
- 对象的值。
bodyUsed boolean
- 对象的值是否已被消费。
arrayBuffer (): Promise<ArrayBuffer>
- 返回 resolve 为包含对象值的 ArrayBuffer 的 Promise。
text (): Promise<string>
- 返回 resolve 为包含对象值字符串的 Promise。
json <T>() : Promise<T>
- 返回 resolve 为包含对象值的给定对象的 Promise。
blob (): Promise<Blob>
- 返回 resolve 为包含对象值二进制 Blob 的 Promise。

`R2MultipartUpload` 定义

调用 createMultipartUpload 或 resumeMultipartUpload 时创建 R2MultipartUpload 对象。R2MultipartUpload 表示进行中的分片上传。

未完成的分片上传将在 7 天后自动中止。

key string
- 分片上传的 key。
uploadId string
- 分片上传的 uploadId。
uploadPart (partNumber: number, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob, options?: R2MultipartOptions): Promise<R2UploadedPart>
- 将具有指定分片编号的分片上传到此分片上传。每个分片大小必须一致，最后一片可以更小。
- 返回包含 etag 和 partNumber 的 R2UploadedPart 对象。完成分片上传时需要这些 R2UploadedPart 对象。
abort (): Promise<void>
- 中止分片上传。返回在上传成功中止时 resolve 的 Promise。
complete (uploadedParts: R2UploadedPart[]): Promise<R2Object>
- 使用给定分片完成分片上传。
- 返回在完成操作完成时 resolve 的 Promise。完成后，对象立即可通过任何后续读取操作在全球访问。

方法特定类型

R2GetOptions

onlyIf R2Conditional | Headers
- 指定仅当 R2Conditional 或条件 Headers 中的特定条件满足时才返回对象。请参阅条件操作。
range R2Range
- 指定仅返回对象中特定长度（从可选 offset）或 suffix 的字节。请参阅范围读取。
ssecKey ArrayBuffer | string
- 指定用于 SSE-C 的密钥。密钥长度必须为 32 字节，格式为十六进制编码字符串或 ArrayBuffer。

范围读取

R2GetOptions 接受 range 参数，可用于限制 body 中返回的数据。

range 可使用 3 种参数变体：

带可选 length 的 offset。
带 length 的可选 offset。
suffix。
offset number
- 开始返回数据的字节（含）。
length number
- 要返回的字节数。若请求的字节数超过对象中的字节数，可能返回少于该数量的字节。
suffix number
- 从文件末尾开始返回的字节数，从最后一个字节起算。若请求的字节数超过对象中的字节数，可能返回少于该数量的字节。

R2PutOptions

onlyIf R2Conditional | Headers
- 指定仅当 R2Conditional 中的特定条件满足时才存储对象。请参阅条件操作。
httpMetadata R2HTTPMetadata | Headersoptional
- 与对象关联的各种 HTTP 请求头。请参阅 HTTP 元数据。
customMetadata Record<string, string>optional
- 将与对象一起存储的自定义用户定义元数据映射。

md5 ArrayBuffer | stringoptional
- 用于检查接收对象完整性的 md5 哈希。
sha1 ArrayBuffer | stringoptional
- 用于检查接收对象完整性的 SHA-1 哈希。
sha256 ArrayBuffer | stringoptional
- 用于检查接收对象完整性的 SHA-256 哈希。
sha384 ArrayBuffer | stringoptional
- 用于检查接收对象完整性的 SHA-384 哈希。
sha512 ArrayBuffer | stringoptional
- 用于检查接收对象完整性的 SHA-512 哈希。
storageClass 'Standard' | 'InfrequentAccess'
- 若提供，设置对象的存储类别。否则，对象将存储在与存储桶关联的默认存储类别中。请参阅存储类别。
ssecKey ArrayBuffer | string
- 指定用于 SSE-C 的密钥。密钥长度必须为 32 字节，格式为十六进制编码字符串或 ArrayBuffer。

R2MultipartOptions

httpMetadata R2HTTPMetadata | Headersoptional
- 与对象关联的各种 HTTP 请求头。请参阅 HTTP 元数据。
customMetadata Record<string, string>optional
- 将与对象一起存储的自定义用户定义元数据映射。
storageClass string
- 若提供，设置对象的存储类别。否则，对象将存储在与存储桶关联的默认存储类别中。请参阅存储类别。
ssecKey ArrayBuffer | string
- 指定用于 SSE-C 的密钥。密钥长度必须为 32 字节，格式为十六进制编码字符串或 ArrayBuffer。

R2ListOptions

limit numberoptional
- 要返回的结果数。默认为 1000，最大为 1000。
- 若设置了 include，为容纳元数据，响应中可能少于 limit 个结果。
prefix stringoptional
- 匹配键的前缀。仅当键以给定前缀开头时才返回。
cursor stringoptional
- 指示从何处继续列出对象的不透明令牌。cursor 可从先前的 list 操作检索。
delimiter stringoptional
- 分组键时使用的字符。
include Array<string>optional
- 可包含 httpMetadata 和/或 customMetadata。若包含，list 返回的项将包含指定元数据。
- 注意单个 list 操作可返回的数据总量有限制。若请求数据，为容纳元数据，响应中可能少于 limit 个结果。
- 兼容性日期必须在 Wrangler 文件中设为 2022-08-04 或更高。否则须设置 r2_list_honor_include 兼容性标志。否则无论实际提供的 include 选项是什么，都视为 include: ['httpMetadata', 'customMetadata']。
这意味着应用须避免将返回对象数量与 limit 比较。应使用 truncated 属性判断 list 请求是否还有更多数据可返回。

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

An object containing an R2Object array, returned by BUCKET_BINDING.list().

objects Array<R2Object>
- 匹配 list 请求的对象数组。
truncated boolean
- 若为 true，表示当前 list 请求还有更多结果可检索。
cursor stringoptional
- 可传递给未来 list 调用的令牌，从该点继续列出。仅在 truncated 为 true 时存在。
delimitedPrefixes Array<string>
- 若指定了 delimiter，包含指定 prefix 与 delimiter 下一次出现之间的所有 prefix。
- 例如，若未提供 prefix 且 delimiter 为 '/'，foo/bar/baz 将返回 foo 作为 delimited prefix。若以相同结构和 delimiter 传入 foo/ 作为 prefix，将返回 foo/bar 作为 delimited prefix。

条件操作

您可以将 R2Conditional 对象传递给 R2GetOptions 和 R2PutOptions。若 get() 的条件检查失败，不会返回 body。这会使 get() 具有更低延迟。

若 put() 的条件检查失败，将返回 null 而非 R2Object。

etagMatches stringoptional
- 若对象的 etag 与给定字符串匹配则执行操作。
etagDoesNotMatch stringoptional
- 若对象的 etag 与给定字符串不匹配则执行操作。
uploadedBefore Dateoptional
- 若对象在给定日期之前上传则执行操作。
uploadedAfter Dateoptional
- 若对象在给定日期之后上传则执行操作。

或者，您可以将包含条件请求头的 Headers 对象传递给 R2GetOptions 和 R2PutOptions。有关这些条件请求头的信息，请参阅 MDN 条件请求文档 ↗。除 If-Range 外，所有条件请求头均受支持。

有关条件请求的更多具体信息，请参阅 RFC 7232 ↗。

HTTP 元数据

通常，这些字段与创建对象时传递的 HTTP 元数据匹配。发起 GET 请求时可覆盖，此时给定值将在响应中回显。

contentType stringoptional
contentLanguage stringoptional
contentDisposition stringoptional
contentEncoding stringoptional
cacheControl stringoptional
cacheExpiry Dateoptional

校验和

使用 put() 绑定时若提供了校验和，它将在返回对象的 checksums 属性下可用。非分片对象默认包含 MD5 校验和。

md5 ArrayBufferoptional
- 对象的 MD5 校验和。
sha1 ArrayBufferoptional
- 对象的 SHA-1 校验和。
sha256 ArrayBufferoptional
- 对象的 SHA-256 校验和。
sha384 ArrayBufferoptional
- 对象的 SHA-384 校验和。
sha512 ArrayBufferoptional
- 对象的 SHA-512 校验和。

`R2UploadedPart`

R2UploadedPart 对象表示已上传的分片。R2UploadedPart 对象从 uploadPart 操作返回，必须传递给 completeMultipartUpload 操作。

partNumber number
- 分片编号。
etag string
- 分片的 etag。

存储类别

R2Object 存储的存储类别。可用存储类别为 Standard 和 InfrequentAccess。更多信息请参阅存储类别。