Cloud Storage용 Cloud Pub/Sub 알림

설정

이 페이지에서는 Cloud Storage용 Pub/Sub 알림을 간략하게 설명합니다.

개요

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

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

기타 알림 옵션

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

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

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

알림 구성

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

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

버킷에 알림 구성을 여러 개 연결할 수 있습니다. 버킷에는 최대 100개의 알림 구성이 포함될 수 있으며 특정 이벤트에 대해 트리거되도록 최대 10개의 알림 구성을 설정할 수 있습니다.

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

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

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

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

이벤트 유형

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

이벤트 유형 설명
OBJECT_FINALIZE 버킷에서 새 객체(또는 기존 객체의 새로운 세대)가 성공적으로 생성되면 발송됩니다. 여기에는 기존 객체 복사, 재작성 또는 복원이 포함됩니다. 실패한 업로드는 이 이벤트를 트리거하지 않습니다.
OBJECT_METADATA_UPDATE 기존 객체의 메타데이터가 변경되면 발송됩니다.
OBJECT_DELETE 객체가 영구 삭제되면 전송됩니다. 여기에는 교체됐거나 버킷 수명 주기 구성에 따라 삭제된 객체가 포함됩니다. 여기에는 이전 버전(OBJECT_ARCHIVE 참조)이거나 멀티파트 업로드가 중단된 객체는 포함되지 않습니다.
OBJECT_ARCHIVE 버킷에 객체 버전 관리 사용이 설정된 경우에만 발송됩니다. 이 이벤트는 서비스 중인 객체 버전이 명시적으로 이전 버전이 되었거나 동일한 이름의 객체를 업로드하여 교체됐기 때문에 해당 버전이 이전 버전이 되었음을 나타냅니다.

버킷 작업이나 객체 읽기와 같은 다른 Cloud Storage 이벤트의 경우 Cloud 감사 로그에서 적절한 감사 로그 유형을 사용 설정하고 필터를 사용해 감사 로그를 Pub/Sub으로 라우팅할 수 있습니다.

객체 교체

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

알림 형식

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

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

속성

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

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

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

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

알림 구성에는 위 속성 외에도 최대 10개의 커스텀 속성이 포함될 수 있습니다. 커스텀 속성은 알림 구성을 만들 때 gcloud storage 명령어에 --custom-attributes를 사용하거나 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는 Pub/Sub로 최소 일회 전송을 보장합니다. Pub/Sub도 수신자에게 최소 일회 전송을 제공하므로, 동일한 Cloud Storage 이벤트를 나타내고 여러 ID를 가진 다수의 메시지가 수신될 수 있습니다.

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

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

다음 단계