이 페이지에서는 Cloud Storage용 Pub/Sub 알림을 간략하게 설명합니다.
개요
Pub/Sub 알림은 버킷의 객체 변경사항에 대한 정보를 Pub/Sub로 전송하며, 여기에서 정보는 메시지의 형태로 선택한 Pub/Sub 주제에 추가됩니다. 예를 들어, 버킷에서 만들어지고 삭제되는 객체를 추적할 수 있습니다. 각 알림에는 알림을 트리거한 이벤트와 변경된 객체를 설명하는 정보가 포함됩니다.
프로젝트에 대한 권한이 충분한 경우 어떤 Pub/Sub 주제에도 알림을 전송할 수 있습니다. Pub/Sub 주제로 수신된 후 주제 구독자가 관련 메시지를 수신할 수 있습니다. Cloud Storage 버킷을 Pub/Sub 주제에 연결하는 방법은 기본 요건을 참조하세요.
기타 알림 옵션
Pub/Sub 알림을 구독하면 버킷의 변경에 대응하여 다양한 목적에 맞게 알림과 작업을 트리거할 수 있습니다. 다음 옵션도 사용할 수 있습니다.
Cloud Functions: Pub/Sub 주제를 관리하지 않으면서 이벤트에 응답하여 가벼운 독립 실행형 함수만 트리거하려면 Cloud Functions를 사용합니다. Cloud Functions를 사용하면 버킷의 객체가 변경될 때 C#, Go, Java, Node.js, Python, PHP, Ruby 함수를 실행할 수 있습니다. 버킷은 Cloud Functions와 동일한 프로젝트에 있어야 합니다. Cloud Storage에서 Cloud Functions를 사용하는 예에 대해서는 관련 튜토리얼을 참조하세요.
객체 변경 알림: 객체 변경 알림은 알림을 생성하기 위해 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가 더 이상 주제에 게시할 권한이 없거나 주제를 소유하는 프로젝트가 게시 할당량을 초과하는 경우 전송 실패가 발생할 수 있습니다.
다음 단계
- Cloud Storage용 Pub/Sub 알림 구성
- Pub/Sub 자세히 알아보기
- 버킷을 구독하여 Pub/Sub로 전송된 알림 수신
- Cloud Functions를 사용하여 Cloud Storage 트리거로 이벤트를 전송
- Cloud Storage 버킷 간 이벤트 기반 전송에 대한 Pub/Sub 알림 사용