Cloud Storage용 Cloud Pub/Sub 알림

이 페이지에서는 Cloud Storage용 Cloud Pub/Sub 알림을 간략하게 설명합니다. Cloud Pub/Sub 알림을 설정하고 사용하는 방법은 객체 변경 등록을 참조하세요.

개요

Cloud Pub/Sub 알림은 버킷의 객체 변경 정보를 Cloud Pub/Sub로 보냅니다. 여기서 정보는 메시지의 형태로 사용자가 선택한 Cloud Pub/Sub 주제에 추가됩니다. 예를 들어, 버킷에서 만들어지고 삭제되는 객체를 추적할 수 있습니다. 각 알림에는 알림을 트리거한 이벤트와 변경된 객체를 설명하는 정보가 포함됩니다.

프로젝트에 대한 권한이 충분한 경우 어떤 Cloud Pub/Sub 주제에도 알림을 전송할 수 있습니다. Cloud Pub/Sub 주제가 수신되면 주제 구독자 수에 상관없이 결과 메시지를 전송할 수 있습니다. Cloud Storage 버킷을 Cloud Pub/Sub 주제에 연결하는 방법은 기본 요건을 참조하세요.

기타 알림 옵션

Cloud Pub/Sub 알림을 구독하면 버킷의 변경에 대응하여 다양한 목적에 맞게 알림과 작업을 트리거할 수 있습니다. 다음 옵션도 사용할 수 있습니다.

  • Cloud Functions: Cloud Pub/Sub 주제를 관리하지 않으면서 이벤트에 응답하여 가벼운 독립 실행형 함수만 트리거하려면 Cloud Functions를 사용합니다. Cloud Functions를 사용하면 버킷의 객체가 변경될 때 자바스크립트, Python, Go 함수를 실행할 수 있습니다. 버킷은 Cloud Functions와 동일한 프로젝트에 있어야 합니다. Cloud Storage에서 Cloud Functions를 사용하는 예에 대해서는 관련 가이드를 참조하세요.

  • 객체 변경 알림: 객체 변경 알림은 알림을 생성하기 위해 Cloud Storage에서 제공하는 별도의 기존 기능입니다. 이 기능은 별도로 설정한 클라이언트 애플리케이션에 HTTPS 메시지를 보냅니다. 일반적으로 Cloud Pub/Sub 알림이 더 저렴하고 사용하기 쉽고 유연합니다.

알림 구성

알림 구성은 사용자가 버킷에 부가하는 규칙으로, 다음을 지정합니다.

  • 알림을 수신하는 Cloud Pub/Sub의 주제
  • 보낼 알림을 트리거하는 이벤트
  • 알림에 포함된 정보

버킷에 알림 구성을 여러 개 연결할 수 있습니다. 각 이벤트에 대해 알림을 트리거하기 위한 알림 구성을 최대 10개까지 설정할 수 있습니다.

예를 들어, 하나의 Cloud Pub/Sub 주제로 삭제 알림을 보내는 알림 구성이 있는 경우 삭제 알림을 다른 주제로 보내는 두 번째 알림 구성을 버킷에 추가할 수 있습니다. 그러나 이를 수행하는 알림 구성을 10개 이상 만들려고 하면 오류가 발생합니다. 이러한 알림 구성 외에도 객체 생성과 같은 다른 이벤트에 대한 알림을 삭제 알림에 사용되는 Cloud Pub/Sub 주제나 다른 주제로 보내는 알림 구성을 만들 수도 있습니다.

각 알림 구성은 정수로 식별됩니다. 이 정수는 다음과 같은 경우에 반환됩니다.

  • 알림 구성 생성 시
  • 버킷에 연결된 알림 구성 나열 시
  • 알림 구성으로 트리거된 각 알림의 notificationConfig 속성에서

알림 구성을 만들고 삭제하면 버킷의 메타 세대 번호가 증가합니다.

이벤트 유형

다음은 현재 Cloud Storage가 지원하는 이벤트 유형 목록입니다.

이벤트 유형 설명
OBJECT_FINALIZE 버킷에서 새 객체(또는 기존 객체의 새로운 세대)가 성공적으로 생성되면 발송됩니다. 여기에는 기존 객체 복사나 재작성이 포함됩니다. 실패한 업로드는 이 이벤트를 트리거하지 않습니다.
OBJECT_METADATA_UPDATE 기존 객체의 메타데이터가 변경되면 발송됩니다.
OBJECT_DELETE 객체가 영구 삭제되면 발송됩니다. 여기에는 덮어썼거나 버킷 수명 주기 구성에 따라 삭제된 객체가 포함됩니다. 객체 버전 관리가 사용 설정된 버킷의 경우 storage.objects.delete 메서드를 통해 보관처리가 발생하더라도 객체를 보관처리할 때 이벤트가 발송되지 않습니다(OBJECT_ARCHIVE 참조).
OBJECT_ARCHIVE 버킷에 객체 버전 관리 사용이 설정된 경우에만 발송됩니다. 객체 버전을 보관처리했거나 이름이 동일한 객체를 업로드하여 덮어썼으므로, 이 이벤트는 객체의 실시간 버전이 보관처리 버전이 되었음을 나타냅니다.

객체 덮어쓰기

기존 객체를 동일한 이름의 새 객체로 덮어쓰면 두 가지 개별 이벤트가 트리거됩니다. 즉, 새 객체 버전의 경우 OBJECT_FINALIZE 이벤트가, 덮어쓴 객체의 경우 OBJECT_ARCHIVE 또는 OBJECT_DELETE 이벤트가 트리거됩니다. OBJECT_FINALIZE 이벤트는 덮어쓴 객체의 세대 번호를 제공하는 추가 속성인 overwroteGeneration을 포함합니다. OBJECT_ARCHIVE 또는 OBJECT_DELETE 이벤트는 새 객체의 세대 번호를 제공하는 추가 속성인 overwrittenByGeneration을 포함합니다.

알림 형식

Cloud Pub/Sub 주제로 전송되는 알림은 다음 두 부분으로 구성됩니다.

  • 속성: 이벤트를 설명하는 키:값 쌍의 조합입니다.
  • 페이로드: 변경된 객체의 메타데이터를 포함하는 문자열입니다.

속성

속성은 Cloud Storage에서 Cloud Pub/Sub 주제로 발송된 모든 알림에 포함된 키:값 쌍입니다. 알림 페이로드에 관계없이 알림에는 항상 다음 키:값 쌍 조합이 포함됩니다.

속성 이름 설명
notificationConfig projects/_/buckets/foo/notificationConfigs/3 이 알림을 트리거한 알림 구성의 식별자입니다.
eventType OBJECT_FINALIZE 방금 발생한 이벤트의 유형. 가능한 값 목록은 이벤트 유형을 참조하세요.
payloadFormat JSON_API_V1 객체 페이로드의 형식. 가능한 값 목록은 페이로드를 참조하세요.
bucketId foo 변경된 객체를 포함하는 버킷 이름입니다.
objectId bar 변경된 객체 이름입니다.
objectGeneration 123456 변경된 객체의 세대 번호입니다.

알림 페이로드에 관계없이 알림에는 간혹 다음 키:값 쌍 조합이 포함됩니다.

속성 이름 설명
overwrittenByGeneration 107458 이 알림이 속한 객체를 덮어쓴 객체의 세대 번호입니다. 덮어쓰는 경우 이 속성은 OBJECT_ARCHIVE 또는 OBJECT_DELETE 이벤트에만 나타납니다.
overwroteGeneration 352947 이 알림이 속한 객체가 덮어쓴 객체의 세대 번호입니다. 덮어쓰는 경우 이 속성은 OBJECT_FINALIZE 이벤트에만 나타납니다.

다음 키:값 쌍은 사용되지 않습니다. 이 쌍은 새로운 구독에 나타나지 않으며 2018년 6월 1일 이후의 모든 구독에 나타나지 않습니다.

속성 이름 설명
리소스 projects/_/buckets/foo/objects/bar#123456 변경된 Cloud Storage 객체 경로입니다.

위의 속성 이외에도 알림에는 커스텀 속성이 포함될 수 있습니다. 이러한 속성은 알림 구성을 만들 때 gsutil notification 명령어-m 플래그를 사용하거나 POST notificationConfigs JSON 요청 본문에 custom_attributes 객체를 사용하여 정의됩니다.

페이로드

페이로드는 변경된 객체의 메타데이터를 포함하는 문자열입니다. 알림 구성을 만들 때 이 구성으로 트리거되는 알림에 포함할 페이로드 유형을 지정합니다. 다음 유형의 페이로드를 지정할 수 있습니다.

페이로드 유형 설명
없음 알림에 페이로드가 포함되지 않습니다.
JSON_API_V1 이 페이로드는 객체의 메타데이터에 대한 리소스 표현을 포함한 UTF-8 문자열입니다.

OBJECT_DELETE 알림의 경우 페이로드에 포함된 메타데이터는 추가 timeDeleted 속성과 함께 삭제되기 전의 객체 메타데이터를 나타냅니다. 다른 모든 알림의 경우, 페이로드에 포함된 메타데이터는 변경이 발생한 이후의 객체 메타데이터를 나타냅니다.

예를 들어 OBJECT_METADATA_UPDATE 이벤트를 추적하는 알림 구성이 있다고 가정해 보겠습니다. 사용자가 객체의 contentType 속성을 binary/octet-stream에서 video/mp4로 변경하는 경우 OBJECT_METADATA_UPDATE 알림이 발생하고 페이로드의 메타데이터에 "contentType":"video/mp4"가 포함됩니다.

전송 보장

알림 구성을 추가하면 Cloud Storage가 이와 관련된 알림을 보내기 시작하기까지 최대 30초가 걸릴 수 있습니다. 전송이 시작되면 Cloud Storage는 Cloud Pub/Sub로 최소 일회 전송을 보장합니다. Cloud Pub/Sub도 수신자에게 최소 일회 전송을 제공하므로, 동일한 Cloud Storage 이벤트를 나타내고 여러 ID를 가진 다수의 메시지가 수신될 수 있습니다. 현재 전송 시간에 대한 SLA는 없지만 알림은 일반적으로 수초 내에 전송됩니다. 드문 경우지만 알림이 훨씬 더 오래 지연될 수도 있습니다.

알림은 Cloud Pub/Sub가 알림을 수신하는 순서로 게시된다고 보장되지 않습니다. 알림을 토대로 Cloud Storage 객체를 수정하려면 객체의 세대 번호와 메타세대 번호를 업데이트 요청에 대한 전제 조건으로 사용하는 것이 좋습니다.

알림이 Cloud Pub/Sub 주제로 계속해서 전송되지 않으면 Cloud Storage가 7일 후 알림을 삭제할 수 있습니다. Cloud Pub/Sub 주제가 더 이상 존재하지 않는 경우, Cloud Storage가 더 이상 주제에 게시할 권한을 갖고 있지 않은 경우 또는 주제를 소유한 프로젝트가 게시 할당량을 초과한 경우에 전송이 실패할 수 있습니다.

다음 단계