aws-sdk-js-v3

開始する前に、Access Key を生成する必要があります。以降の例では、生成した Access Key ID と Secret Access Key の値を表す access_key_id と access_key_secret 変数を使います。

JavaScript または TypeScript では、通常どおり @aws-sdk/client-s3 ↗ npm パッケージを使えます。S3 サービスクライアントを生成するときに、R2 の設定と認証情報を渡します。

import {
	S3Client,
	ListBucketsCommand,
	ListObjectsV2Command,
	GetObjectCommand,
	PutObjectCommand,
} from "@aws-sdk/client-s3";

const S3 = new S3Client({
	region: "auto", // Required by SDK but not used by R2
	// Provide your Cloudflare account ID
	endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
	// Retrieve your S3 API credentials for your R2 bucket via API tokens (see: https://developers.cloudflare.com/r2/api/tokens)
	credentials: {
		accessKeyId: ACCESS_KEY_ID,
		secretAccessKey: SECRET_ACCESS_KEY,
	},
});

console.log(await S3.send(new ListBucketsCommand({})));
// {
//     '$metadata': {
//     httpStatusCode: 200,
//         requestId: undefined,
//         extendedRequestId: undefined,
//         cfId: undefined,
//         attempts: 1,
//         totalRetryDelay: 0
// },
//     Buckets: [
//     { Name: 'user-uploads', CreationDate: 2022-04-13T21:23:47.102Z },
//     { Name: 'my-bucket', CreationDate: 2022-05-07T02:46:49.218Z }
//     ],
//     Owner: {
//         DisplayName: '...',
//         ID: '...'
//     }
// }

console.log(
	await S3.send(new ListObjectsV2Command({ Bucket: "my-bucket" })),
);
// {
//     '$metadata': {
//       httpStatusCode: 200,
//       requestId: undefined,
//       extendedRequestId: undefined,
//       cfId: undefined,
//       attempts: 1,
//       totalRetryDelay: 0
//     },
//     CommonPrefixes: undefined,
//     Contents: [
//       {
//         Key: 'cat.png',
//         LastModified: 2022-05-07T02:50:45.616Z,
//         ETag: '"c4da329b38467509049e615c11b0c48a"',
//         ChecksumAlgorithm: undefined,
//         Size: 751832,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       },
//       {
//         Key: 'todos.txt',
//         LastModified: 2022-05-07T21:37:17.150Z,
//         ETag: '"29d911f495d1ba7cb3a4d7d15e63236a"',
//         ChecksumAlgorithm: undefined,
//         Size: 279,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       }
//     ],
//     ContinuationToken: undefined,
//     Delimiter: undefined,
//     EncodingType: undefined,
//     IsTruncated: false,
//     KeyCount: 8,
//     MaxKeys: 1000,
//     Name: 'my-bucket',
//     NextContinuationToken: undefined,
//     Prefix: undefined,
//     StartAfter: undefined
//   }

Presigned URL を生成する

一時的にバケットへの読み取りまたは書き込みを公開できる Presigned リンクも生成できます。

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// Use the expiresIn property to determine how long the presigned link is valid.
console.log(
	await getSignedUrl(
		S3,
		new GetObjectCommand({ Bucket: "my-bucket", Key: "dog.png" }),
		{ expiresIn: 3600 },
	),
);
// You can also create links for operations such as PutObject to allow temporary write access to a specific key.
// Specify ContentType to restrict uploads to a specific file type.
console.log(
	await getSignedUrl(
		S3,
		new PutObjectCommand({
			Bucket: "my-bucket",
			Key: "dog.png",
			ContentType: "image/png",
		}),
		{ expiresIn: 3600 },
	),
);

https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>&x-id=GetObject
https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=<signature>&x-id=PutObject

PutObject の例で生成したリンクを使うと、Presigned リンクの有効期限まで、指定したバケットとキーへアップロードできます。ContentType 付きの Presigned URL を使う場合、クライアントはリクエストに一致する Content-Type ヘッダーを含める必要があります。

curl -X PUT "https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=..." \
  -H "Content-Type: image/png" \
  --data-binary @dog.png

CORS と Content-Type でアップロードを制限する

アップロード用の Presigned URL を生成するとき、不正利用を減らすには次の方法があります。

Content-Type を制限する: PutObjectCommand で許可する Content-Type を指定します。クライアントが別の Content-Type ヘッダーを送ると、アップロードは失敗します。
CORS を設定する: バケットに CORS ルールを設定し、アップロードを許可するオリジンを制御します。Cloudflare ダッシュボード ↗ のバケット設定に JSON ポリシーを追加して CORS を設定します。

[
  {
    "AllowedOrigins": ["https://example.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["Content-Type"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

次に、Content-Type を制限した Presigned URL を生成します。

const putUrl = await getSignedUrl(
	S3,
	new PutObjectCommand({
		Bucket: "my-bucket",
		Key: "dog.png",
		ContentType: "image/png",
	}),
	{ expiresIn: 3600 },
);

クライアントがこの Presigned URL を使うときは、次が必要です。

許可されたオリジンからリクエストする（CORS で強制）
Content-Type: image/png ヘッダーを付ける（署名で強制）