이 가이드는 Cloud Storage의 지원 중단된 객체 변경 알림 기능 사용자를 위한 것입니다.
Cloud Storage용 Pub/Sub 알림은 Cloud Storage 버킷의 객체에 대한 변경사항을 추적하는 알림을 생성하는 데 권장되는 도구입니다. Pub/Sub 알림은 속도, 유연성, 설정, 비용 효율성이 개선되었습니다. 이 가이드에서는 객체 변경 알림과 Cloud Storage용 Pub/Sub 알림의 차이점을 설명하고 객체 변경 알림에서 Pub/Sub 알림으로 마이그레이션하는 단계를 제공합니다.
객체 변경 알림 개요
객체 변경 알림은 버킷 내 객체 변경사항을 애플리케이션에 알리는 Cloud Storage의 기존 메커니즘입니다. 객체 변경 알림이 설정되면 객체가 추가, 업데이트 또는 삭제될 때마다 Cloud Storage는 지정된 애플리케이션 URL로 HTTP POST 요청(웹훅)을 보냅니다. 객체 변경 알림은 JSON API, 클라이언트 라이브러리 또는 gsutil 알림 watchbucket 명령어를 사용하여 Cloud Storage에 watchAll 요청을 전송하여 설정됩니다. pull 메커니즘이 없으며 웹훅 메시지를 수신하려면 HTTP 서버에서 지원하는 공개적으로 액세스 가능한 도메인 이름이 있어야 합니다. 새로운 구현의 경우 안정성, 확장성, 유연성으로 인해 Cloud Storage용 Pub/Sub 알림을 사용하는 것이 좋습니다.
Cloud Storage용 Pub/Sub 알림은 Pub/Sub 주제에 이벤트 정보를 전송하여 Cloud Storage 버킷의 변경사항에 대한 응답으로 작업을 트리거하는 확장 가능하고 안정적인 최신 방법을 제공합니다. Pub/Sub는 웹훅에 대한 HTTP POST 요청으로 푸시 기반의 메시지 전송을 제공합니다. 객체가 생성, 업데이트 또는 삭제되면 Cloud Storage는 객체 메타데이터가 포함된 메시지를 지정된 Pub/Sub 주제에 게시합니다. 그러면 Cloud Run Functions, 데이터 파이프라인, 마이크로서비스와 같은 다양한 구독자가 이를 사용할 수 있으므로 최소 1회 전송 및 강력한 오류 처리 기능을 갖춘 유연한 이벤트 기반 아키텍처를 지원합니다.
버킷의 객체가 변경될 때 HTTP POST 요청(웹훅)을 통해 애플리케이션에 직접 알립니다.
Cloud Storage 버킷의 객체 변경사항에 대한 정보를 Pub/Sub 주제로 전송합니다.
전송 메커니즘
지정된 애플리케이션 URL에 직접 HTTP POST(웹훅)
Pub/Sub 주제에 게시된 메시지는 Cloud Run Functions, 기타 애플리케이션, 데이터 파이프라인과 같은 다양한 구독자가 사용할 수 있습니다.
안정성
안정적인 전송을 시도하지만 적시성은 보장되지 않습니다. 알림이 무기한 지연될 수 있습니다.
최소 1회 전송을 제공하므로 메시지가 여러 번 전송될 수 있지만 손실되지는 않습니다.
Pub/Sub는 메시지 지속성과 재시도를 처리합니다.
확장성
애플리케이션에서 처리해야 하는 직접 웹훅을 사용하므로 확장성이 떨어집니다.
확장성이 뛰어나고 대규모 이벤트 처리를 위해 설계되었습니다.
유연성
직접 웹훅 통합으로 제한됩니다.
매우 유연합니다. Pub/Sub 메시지는 Cloud Run Functions를 트리거하고, 데이터 파이프라인(Dataflow)에 입력되며, 다른 마이크로서비스에서 사용할 수 있습니다.
필터링
없음
Pub/Sub 구독 수준에서 사용할 수 있는 강력한 필터링 옵션을 통해 구독자는 특정 기준을 충족하는 메시지만 수신할 수 있습니다.
보안
애플리케이션 엔드포인트가 공개적으로 액세스 가능해야 합니다(HTTPS).
Pub/Sub는 주제 및 구독에 대한 세분화된 액세스 제어를 위해 IAM을 제공합니다.
Pub/Sub는 알림을 직접 가져오든 공개 엔드포인트로 푸시하든 안전한 메시지 전송을 지원합니다.
복잡성
기본 사용 사례의 경우 설정이 더 간단할 수 있지만 안정적인 전송 및 확장 관리가 복잡해질 수 있습니다.
Pub/Sub 개념(주제, 구독)을 이해해야 하지만 이벤트 기반 아키텍처를 위한 더 강력하고 관리 가능한 솔루션을 제공합니다.
지원 중단 상태
지원 중단되었습니다. 새 구현에는 Pub/Sub 알림을 사용하는 것이 좋습니다.
활동 중 Cloud Storage 알림의 적극적으로 개발되는 기본 방법입니다.
권장 사용 사례
새 프로젝트에는 권장되지 않습니다. 마이그레이션할 수 없는 덜 복잡한 기존 통합을 위한 것입니다.
Cloud Storage 변경사항에 반응하는 강력하고 확장 가능하며 이벤트 기반 아키텍처를 빌드하는 데 적극 권장됩니다.
Pub/Sub 알림으로 마이그레이션해야 하는 이유
기존 객체 변경 알림에서 Cloud Storage 알림용 Pub/Sub로 마이그레이션하는 것은 강력한 이벤트 관리를 위한 중요한 단계입니다. Pub/Sub는 Google Cloud내 이벤트 기반 아키텍처에 권장되며, 객체 변경 알림에 비해 상당한 기술적 및 운영적 이점을 제공합니다.
Pub/Sub 알림으로 마이그레이션할 때의 장점은 다음과 같습니다.
안정적인 전송: Pub/Sub는 게시된 각 메시지를 모든 구독에 최소한 한 번은 전송하여 이벤트가 소비자에게 도달하는지 확인합니다. 안정적인 전송은 데이터 손실을 최소화하고 객체 변경 알림의 덜 강력한 전송 모델에 비해 워크플로의 종속 가능성을 개선합니다.
확장성: 높은 처리량을 위해 설계된 Pub/Sub 알림은 대량의 이벤트를 자동으로 처리할 수 있습니다. Pub/Sub 알림을 사용하면 데이터 또는 이벤트 빈도가 증가할 때 객체 변경 알림에서 발생할 수 있는 성능 병목 현상을 없앨 수 있습니다.
Google Cloud 서비스와의 통합: Pub/Sub는 여러 Google Cloud 서비스와 원활하게 통합되므로 Cloud Run Functions, Cloud Run, Dataflow를 사용하여 자동화된 워크플로를 구축하고 Cloud Logging 및 Cloud Monitoring을 통해 모니터링 가능성을 개선할 수 있습니다.
세부적인 제어: Pub/Sub를 사용하면 구독 수준에서 메시지를 필터링할 수 있습니다. 이를 통해 소비자는 관련 이벤트만 수신하여 불필요한 처리 및 네트워크 트래픽을 줄일 수 있습니다.
플랫폼 지원: Pub/Sub 알림이 지원되는 메시징 서비스입니다. 마이그레이션을 통해 지원 중단된 객체 변경 알림과 달리 지속적인 개선사항, 보안 업데이트, 포괄적인 문서를 제공하는 기술을 사용할 수 있습니다.
마이그레이션 단계
객체 변경 알림과 Cloud Storage용 Pub/Sub 알림은 모두 중복 메시지를 전송할 수 있습니다. 따라서 사용하는 코드는 중복 메시지를 안전하게 처리하도록 설계해야 합니다.
객체 변경 알림에서 Pub/Sub 알림으로 마이그레이션하려면 다음 단계를 따르세요.
기존 객체 변경 알림 설정 외에 Cloud Storage용 Pub/Sub 알림을 사용합니다. Pub/Sub 알림 구성 방법에 관한 자세한 내용은 Cloud Storage용 Pub/Sub 알림 구성을 참고하세요.
애플리케이션의 Pub/Sub 알림 처리 워크플로가 올바르게 작동하는지 테스트하고 확인합니다. Pub/Sub 구독을 모니터링하는 방법에 관한 자세한 내용은 Pub/Sub 내에서 구독 모니터링을 참고하세요.
객체 변경 알림 채널에서 수신된 메시지 처리를 중지합니다. 알림 채널을 중지하려면 stop 요청을 수행합니다.
Pub/Sub 푸시(push) 구독 고려사항
Pub/Sub 풀(pull) 구독은 향상된 유연성과 제어 기능을 제공하지만 Pub/Sub 푸시(push) 구독은 객체 변경 알림 메시지와 매우 유사합니다. 따라서 푸시(push) 구독은 기존 객체 변경 알림 사용자에게 더 빠른 마이그레이션 경로가 됩니다. 푸시(push) 및 풀(pull) 구독의 자세한 비교는 구독 유형 선택을 참고하세요.
푸시(push) 구독을 사용하고 기존 알림 처리 코드를 재사용하려는 경우 객체 변경 알림과 Pub/Sub 알림 푸시 요청 형식 및 응답 코드 해석 간의 차이점을 고려해야 합니다. 차이점은 다음 섹션에 설명되어 있습니다.
푸시 요청 형식
이 섹션에서는 객체 변경 알림과 Pub/Sub 알림 간의 푸시 요청 형식 차이점을 설명합니다.
객체 변경 알림: 객체 변경 알림은 다음 형식으로 애플리케이션 URL에 HTTP POST 요청으로 전송됩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[],[],null,["# Migrate from Object change notifications to Pub/Sub notifications\n\nThis guide is for users of the Cloud Storage's deprecated [Object\nchange notifications](/storage/docs/object-change-notification) feature. [Pub/Sub notifications for\nCloud Storage](/storage/docs/pubsub-notifications) is the recommended tool\nfor generating notifications that track changes to objects in your\nCloud Storage buckets. Pub/Sub notifications offer\nimproved speed, flexibility, setup, and cost-effectiveness. This guide explains\nthe differences between Object change notifications and Pub/Sub\nnotifications for Cloud Storage and provides [migration steps](#migration-steps) from\nObject change notifications to Pub/Sub notifications.\n\nOverview of Object change notifications\n---------------------------------------\n\nObject change notifications are a legacy mechanism in Cloud Storage for\nnotifying an application about changes to objects within a bucket. When an\nObject change notification is set up, Cloud Storage sends HTTP POST\nrequests (webhooks) to a specified application URL whenever an object is added,\nupdated, or deleted. Object change notifications are established by sending a\n`watchAll` request to Cloud Storage, using the JSON API, client\nlibraries, or the gsutil notification `watchbucket` command. There is no `pull`\nmechanism, and you must have a publicly accessible domain name backed by an HTTP\nserver to receive the webhook messages. We recommend using Pub/Sub\nnotifications for Cloud Storage for new implementations due to its\nreliability, scalability, and flexibility.\n\nFor more detailed information, see [Object change\nnotification](/storage/docs/object-change-notification).\n\nOverview of Pub/Sub notifications\n---------------------------------\n\nPub/Sub notifications for Cloud Storage provide a modern,\nscalable, and reliable way to trigger actions in response to changes in your\nCloud Storage buckets by sending event information to a\nPub/Sub topic. Pub/Sub offers push-based delivery of\nmessages as HTTP POST requests to webhooks. When objects are created, updated,\nor deleted, Cloud Storage publishes messages containing object metadata\nto a specified Pub/Sub topic, which can then be consumed by\nvarious subscribers such as Cloud Run functions, data pipelines, or\nmicroservices, enabling flexible and event-driven architectures with\nat-least-once delivery and robust error handling features.\n\nFor more detailed information, see [Pub/Sub notifications for\nCloud Storage](/storage/docs/pubsub-notifications).\n\nCompare Object change notifications with Pub/Sub notifications\n--------------------------------------------------------------\n\nThe following table compares Object change notifications with\nPub/Sub notifications features:\n\nWhy migrate to Pub/Sub notifications?\n-------------------------------------\n\nMigrating from the legacy Object change notifications to Pub/Sub\nfor Cloud Storage notifications is an important step for robust event\nmanagement. Pub/Sub is recommended for event-driven architectures\nwithin Google Cloud, offering significant technical and operational\nadvantages over Object change notifications.\n\nThe following are the advantages of migrating to Pub/Sub\nnotifications:\n\n- **Reliable delivery**: Pub/Sub delivers each published message at least once for every subscription, validating that events reach your consumers. Reliable delivery minimizes data loss and improves the dependability of your workflows compared to Object change notifications less robust delivery model.\n- **Scalability**: Designed for high throughput, Pub/Sub notifications can handle large volumes of events automatically. Using Pub/Sub notifications, you can eliminate the performance bottlenecks you might encounter with Object change notifications as your data or event frequency increases.\n- **Integration with Google Cloud services**: Pub/Sub seamlessly integrates with multiple Google Cloud services, providing flexibility for building automated workflows using Cloud Run functions, Cloud Run, Dataflow, and enhanced observability through Cloud Logging and Cloud Monitoring.\n- **Granular control**: With Pub/Sub you can filter messages at the subscription level. This enables consumers to receive only relevant events, reducing unnecessary processing and network traffic.\n- **Platform support**: Pub/Sub notifications is the supported messaging service. Migrating helps you use a technology that receives ongoing enhancements, security updates, and comprehensive documentation, unlike the deprecated Object change notifications.\n\nMigration steps\n---------------\n\nBoth Object change notifications and Pub/Sub notifications for\nCloud Storage can occasionally send duplicate messages. Therefore, your\nconsuming code must be designed to safely handle duplicate messages.\n\nTo migrate from Object change notifications to Pub/Sub\nnotifications, follow these steps:\n\n1. Start using Pub/Sub notifications for Cloud Storage\n in addition to your existing Object change notifications setup. For\n information about how to configure Pub/Sub notifications, see\n [Configure Pub/Sub notifications for\n Cloud Storage](/storage/docs/pubsub-notifications).\n\n2. Test and verify that your application's Pub/Sub notifications\n processing workflow is functioning correctly. For information about how to\n monitor Pub/Sub subscription, see [Monitor subscriptions\n within Pub/Sub](/pubsub/docs/monitor-subscription).\n\n3. Stop processing messages received from an Object change notifications\n channel. To stop a notifications channel, make a\n [stop](/storage/docs/object-change-notification#_Stop) request.\n\nConsiderations for Pub/Sub push subscription\n--------------------------------------------\n\nWhile [Pub/Sub pull subscriptions](/pubsub/docs/pull) offer enhanced flexibility and\ncontrol, [Pub/Sub push subscriptions](/pubsub/docs/push) closely resemble Object change\nnotification messages. As a result, the push subscriptions become a faster migration path for\nexisting Object change notification users. For a detailed comparison of push and\npull subscriptions, see [Choose a subscription type](/pubsub/docs/subscriber).\n\nIf you plan to use push subscription and similarly plan to reuse existing\nnotification handling code, you'll need to consider the differences between\nObject change notifications and Pub/Sub notifications push request\nformats and response code interpretations. The differences are described in the\nfollowing sections.\n\n### Push request format\n\nThis section describes the push request format differences between Object change\nnotifications and Pub/Sub notifications.\n\n- **Object change notifications**: An Object change notification is delivered\n as an HTTP POST request to your application URL, in the following format:\n\n ```\n POST /ApplicationUrlPath\n Accept: * / *\n Content-Length: 1097\n Content-Type: application/json; charset=\"utf-8\"\n Host: ApplicationUrlHost\n X-Goog-Channel-Id: ChannelId\n X-Goog-Channel-Token: ClientToken\n X-Goog-Resource-Id: ResourceId\n X-Goog-Resource-State: ResourceState\n X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json\n\n {\n \"kind\": \"storage#object\",\n \"id\": \"BucketName/ObjectName\",\n \"selfLink\": \"https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName\",\n \"name\": \"ObjectName\",\n \"bucket\": \"BucketName\",\n \"generation\": \"1367014943964000\",\n \"metageneration\": \"1\",\n \"contentType\": \"application/octet-stream\",\n \"updated\": \"2013-04-26T22:22:23.832Z\",\n \"size\": \"10\",\n \"md5Hash\": \"xHZY0QLVuYng2gnOQD90Yw==\",\n \"mediaLink\": \"https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media\",\n \"owner\": {\n \"entity\": \"user-jeffersonloveshiking@gmail.com\"\n },\n \"crc32c\": \"C7+82w==\",\n \"etag\": \"COD2jMGv6bYCEAE=\"\n }\n ```\n- **Pub/Sub notifications** : A Pub/Sub\n notification, when configured for push delivery, is delivered as an HTTP\n POST request. The `data` field contains the base64-encoded\n Cloud Storage event payload. When the data field is decoded, it\n matches the Object change notifications message body.\n\n ```\n POST /YourSpecifiedURL\n Accept: * / *\n Content-Length: 1097\n Content-Type: application/json; charset=\"utf-8\"\n Host: ApplicationUrlHost\n {\n \"deliveryAttempt\": 5,\n \"message\":\n {\"attributes\":\n {\"notificationConfig\":\"projects/_/buckets/foo/notificationConfigs/3\",\n \"eventType\": \"OBJECT_FINALIZE\",\n \"payloadFormat\": \"JSON_API_V1\",\n \"bucketId\": \"foo\",\n \"objectId\": \"bar\",\n \"objectGeneration\": 123456,\n \"eventTime\": \"2021-01-15T01:30:15.01Z\"\n },\n \"data\": \"ewogImtpbm\",\n \"messageId\": \"2070443601311540\",\n \"message_id\": \"2070443601311540\",\n \"orderingKey\": \"key\",\n \"publishTime\": \"2021-02-26T19:13:55.749Z\",\n \"publish_time\": \"2021-02-26T19:13:55.749Z\"\n },\n \"subscription\": \"projects/myproject/subscriptions/mysubscription\"\n }\n ```\n\n### Response code\n\nThe following table describes the response code interpretation differences\nbetween Object change notifications and Pub/Sub notifications:\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Configure Pub/Sub notifications for Cloud Storage](/storage/docs/reporting-changes).\n- [Learn more about Pub/Sub](/pubsub/docs/overview).\n- [Subscribe a bucket](/pubsub/docs/create-cloudstorage-subscription) to receive notifications sent to Pub/Sub."]]
