이벤트 알림 (Event notifications)

원문 보기 위키 갱신 2026.10.07

이벤트 알림은 R2 버킷의 데이터가 변경될 때 큐(queue)로 메시지를 보내요. 컨슈머 Worker로 이 메시지를 소비하거나, Cloudflare Workers 외부에서 HTTP 풀(pull)로 가져올 수 있어요.

출처: 문서

본문

이벤트 알림 시작하기 (Get started with event notifications)

사전 요구 사항 (Prerequisites)

시작하기 전에 다음이 필요해요.

기존 R2 버킷. 아직 R2 버킷이 없다면 버킷 생성(Create buckets)을 참고해요.
기존 큐. 아직 큐가 없다면 큐 생성(Create a queue)을 참고해요.
큐에서 활성화된 컨슈머 Worker 또는 HTTP 풀.

대시보드로 이벤트 알림 활성화 (Enable event notifications via Dashboard)

Cloudflare 대시보드에서 R2 객체 스토리지(R2 object storage) 페이지로 이동해요. 개요(Overview)로 이동 ↗
이벤트 알림 규칙을 추가할 버킷을 선택해요.
설정(Settings) 탭으로 전환한 뒤 이벤트 알림(Event notifications) 카드까지 스크롤해요.
알림 추가(Add notification) 를 선택하고 알림을 받을 큐와 이를 트리거할 이벤트 유형을 선택해요.
알림 추가(Add notification) 를 선택해요.

Wrangler로 이벤트 알림 활성화 (Enable event notifications via Wrangler)

Wrangler 설정 (Set up Wrangler)

시작하려면 npm ↗︎을 설치해요. 그다음 Wrangler(Developer Platform CLI)를 설치해요.

R2 버킷에서 이벤트 알림 활성화 (Enable event notifications on your R2 bucket)

wrangler login 명령으로 Wrangler에 로그인해요. 그런 다음 r2 bucket notification create 명령을 실행해 버킷에 이벤트 알림 규칙을 추가해요.

npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME>

prefix 또는 suffix 기준의 필터링을 추가하려면 각각 --prefix 또는 --suffix 플래그를 사용해요.

# prefix를 사용한 필터링
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>"

# suffix를 사용한 필터링
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --suffix "<SUFFIX_VALUE>"

# prefix와 suffix를 함께 사용한 필터링. 두 조건 모두 필터링에 사용됩니다.
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>" --suffix "<SUFFIX_VALUE>"

더 완전한 단계별 예시는 이벤트 알림을 사용해 R2 업로드 이벤트를 기록하고 저장하기 예시를 참고해요.

이벤트 알림 규칙 (Event notification rules)

이벤트 알림 규칙은 알림을 트리거할 이벤트 유형을 결정하고, 객체 prefix와 suffix 기준의 필터링을 선택적으로 활성화해요. R2 버킷당 최대 100개의 이벤트 알림 규칙을 가질 수 있어요.

이벤트 유형 (Event types)

메시지 형식 (Message format)

큐 컨슈머는 알림을 메시지(Message)로 받아요. 다음은 컨슈머 Worker가 받게 될 메시지 본문의 예시예요.

{
	"account": "3f4b7e3dcab231cbfdaa90a6a28bd548",
	"action": "CopyObject",
	"bucket": "my-bucket",
	"object": {
		"key": "my-new-object",
		"size": 65536,
		"eTag": "c846ff7a18f28c2e262116d6e8719ef0"
	},
	"eventTime": "2024-05-24T19:36:44.379Z",
	"copySource": {
		"bucket": "my-bucket",
		"object": "my-original-object"
	}
}

속성 (Properties)

참고 사항 (Notes)

큐의 큐당 메시지 처리량은 현재 초당 5,000개 메시지예요. 워크로드가 초당 5,000개 이상의 알림을 생성한다면 알림 규칙을 여러 큐에 나눠 두는 걸 권장해요.
prefix/suffix가 없는 규칙은 버킷의 모든 객체에 적용돼요.
같은 이벤트에 대해 여러 알림을 트리거할 수 있는 중복되거나 충돌하는 규칙은 허용되지 않아요. 예를 들어 prefix와 suffix가 없는 object-create(또는 PutObject 작업) 규칙이 있는데, images/ 같은 prefix를 가진 또 다른 object-create(또는 PutObject 작업) 규칙을 추가하면 한 번의 업로드에 두 개 이상의 알림이 트리거될 수 있어 유효하지 않아요.