객체 변경 알림

객체 변경 알림은 객체가 업데이트되거나 버킷에 추가될 때 이를 애플리케이션에 알리는 데 사용됩니다.

객체 변경 알림을 사용해야 하나요?

일반적으로는 객체 변경 알림을 사용하면 안 됩니다. Cloud Storage 버킷의 객체에 대한 변경 사항을 추적하는 알림을 생성하는 데 권장되는 도구는 Cloud Storage용 Pub/Sub 알림입니다. 더 빠르고 유연하며 설정하기 쉽고 비용 효율적이기 때문입니다. Cloud Storage용 Pub/Sub 알림 설정에 대한 단계별 안내는 Cloud Storage용 Pub/Sub 알림 구성을 참조하세요.

객체 변경 알림 작동 방법

클라이언트 애플리케이션에서 특정 버킷 내 객체 변경사항을 감시하라는 요청을 보낼 수 있습니다.

감시 요청을 완료하면 새 알림 채널이 만들어집니다. 알림 채널을 통해 알림 메시지가 버킷을 감시하는 애플리케이션에 전송됩니다. 현재 한 가지 유형의 알림 채널인 웹훅만 지원됩니다.

알림 채널이 시작되면 Cloud Storage는 객체 추가/업데이트 또는 객체가 버킷에서 제거될 때마다 애플리케이션에 알립니다. 예를 들어, 버킷에 새 그림을 추가하면 애플리케이션은 미리보기 이미지를 만들라는 알림을 받을 수 있습니다.

객체 변경 알림 세부정보

용어

다음 표에는 객체 변경 알림 문서에 사용된 여러 가지 용어를 설명합니다.

용어	설명
애플리케이션 URL	애플리케이션의 URL입니다. 알림이 전송될 주소입니다. HTTPS URL이어야 하며, HTTP URL은 허용되지 않습니다.
채널 식별자	알림 채널의 식별자입니다. 특정 버킷 내에서 고유해야 합니다. 즉, 단일 버킷에 대해 여러 알림 채널이 있는 경우 각 알림 채널은 고유한 채널 식별자를 가져야 합니다. 이 식별자는 각 알림 메시지와 함께 애플리케이션에 전송됩니다.
리소스 식별자	감시 중인 리소스의 불투명한 식별자입니다. 리소스 식별자는 알림 채널을 중지하는 데 필요합니다. 이 식별자는 감시 요청에 대한 응답에서 또는 알림 이벤트 메시지의 `X-Goog-Resource-Id` 헤더에서 검색할 수 있습니다.
클라이언트 토큰	(선택사항) 클라이언트 토큰을 사용하여 알림 이벤트의 유효성을 검사할 수 있습니다. 이를 위해 감시 요청과 함께 커스텀 클라이언트 토큰을 설정합니다. 알림 메시지에 이 토큰이 포함되어 있어 신뢰할 수 있는 메시지인지 확인할 수 있습니다.

버킷 감시하기

변경 알림 이벤트를 위해 버킷 감시를 시작하려면 watchAll 요청을 실행합니다. 지정된 버킷의 지정된 address로 알림 이벤트를 전송하는 알림 채널이 생성됩니다. 알림 채널에는 커스텀 클라이언트 토큰과 채널 식별자(지정된 경우)가 포함됩니다.

버킷 감시를 위한 POST 요청 예시:

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "token": "ClientToken",
  "type": "web_hook",
  "id": "ChannelId",
  "address": "ApplicationUrl"
}

알림 승인

버킷을 감시 중일 때는 생성 중인 알림 채널이 API 요청을 시작하는 애플리케이션의 Google Cloud Console 프로젝트와 연결됩니다. 예를 들어 사용자가 OAuth2 흐름을 통해 설치된 애플리케이션 또는 웹 애플리케이션에 액세스하는 경우 애플리케이션에서 만든 알림 채널은 감시 중인 버킷이 포함된 프로젝트가 아니라 애플리케이션의 프로젝트와 연결됩니다.

서비스 계정은 프로젝트와 연결되어 있으므로 서비스 계정을 사용하여 버킷을 감시하면 서비스 계정의 프로젝트에 알림 채널이 만들어집니다.

알림 채널 삭제하기

알림 채널을 중지하려면 stop 요청을 실행합니다. 지정된 리소스 식별자(resourceId)와 채널 식별자(id) 쌍에 대한 모든 알림 이벤트가 중지됩니다. 동일한 리소스에 대한 추가 활성 채널은 영향을 받지 않습니다. 리소스 및 채널 식별자는 감시 요청의 응답이나 알림 이벤트 메시지 본문에서 찾을 수 있습니다.

채널 중지를 위한 POST 요청 예시:

POST /storage/v1/channels/stop HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "resourceId": "ResourceId",
  "id": "ChannelId"
}

알림 이벤트 메시지 유형

동기화

감시 요청 실행 후 새 알림 채널이 생성되면 알림 이벤트가 전송됩니다. 동기화 이벤트를 수신하면 버킷의 이후 변경사항이 채널용으로 구성된 애플리케이션 URL에 모두 전송됩니다.

알림은 POST 요청으로 구성된 애플리케이션 URL에 전송됩니다. 요청에는 본문이 없습니다. 동기화 알림 메타데이터는 요청의 헤더에 포함됩니다. 다음은 동기화 알림 요청의 예입니다.

POST /ApplicationUrlPath
Accept: */*
Content-Type: application/json; charset="utf-8"
Content_Length: 0
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: sync
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

객체 추가, 업데이트, 삭제

새 객체가 버킷에 추가되거나, 기존 객체의 콘텐츠 또는 메타데이터가 수정되거나, 객체가 버킷에서 삭제될 때 알림 이벤트가 전송됩니다.

알림은 구성된 애플리케이션 URL에 POST 요청으로 전송됩니다. 요청의 본문에는 다음 알림 요청과 같이 JSON으로 인코딩된 메시지가 들어 있습니다.

POST /ApplicationUrlPath
Accept: */*
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
 "kind": "storage#object",
 "id": "BucketName/ObjectName",
 "selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
 "name": "ObjectName",
 "bucket": "BucketName",
 "generation": "1367014943964000",
 "metageneration": "1",
 "contentType": "application/octet-stream",
 "updated": "2013-04-26T22:22:23.832Z",
 "size": "10",
 "md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
 "mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}

여기서 ResourceState는 각각 다음과 같습니다.

exists - 객체 추가 및 업데이트
not_exists - 객체 삭제

JSON 메시지의 콘텐츠에는 객체 리소스 설명에 나와 있는 객체의 현재 표현이 들어 있습니다.

안정적인 전송

객체 변경 알림은 안정적인 방식으로 애플리케이션에 알림을 전송하고자 하지만, 알림이 무기한으로 지연되고 적시성이 보장되지 않을 수도 있습니다. 애플리케이션을 항상 사용할 수 있는 것은 아니기 때문에 알림을 전송할 때 다음 규칙이 적용됩니다.

알림 전달 시도가 실패하면 재시도됩니다. 추가 전송 시도 간격은 최초 실패로부터 30초 후 재시도로 시작하는 지수 백오프 알고리즘으로 결정됩니다. 후속 전송은 최대 90분까지 간격이 점점 증가되며 시도됩니다. 후속 재시도 간격은 임의로 선택되므로 정확한 지수 값에서 발생하지 않습니다. 재시도 간격이 최대치인 90분에 이르면 이후에는 7일 동안 90분마다 후속 재시도가 지속됩니다. 해당 시간에 알림을 전송할 수 없는 경우 알림이 삭제됩니다.
20초 후에 애플리케이션에 도달할 수 없거나 애플리케이션이 다음 HTTP 응답 코드 중 하나로 응답하는 경우 알림 전송 시도는 실패로 처리되고 재시도됩니다.
- 500 내부 서버 오류
- 502 잘못된 게이트웨이
- 503 서비스를 사용할 수 없음
- 504 게이트웨이 시간 초과
애플리케이션이 다음 HTTP 응답 코드 중 하나로 응답하는 경우 알림은 성공적으로 전송된 것으로 처리됩니다.
- 102 처리 중
- 200 확인
- 201 생성됨
- 202 수락됨
- 204 콘텐츠 없음
애플리케이션에서 반환한 다른 모든 HTTP 응답 코드는 영구적인 실패로 처리되며 재시도되지 않습니다.

참고: 위의 재시도 메커니즘으로 인해 알림이 두 번 이상 전송될 수 있습니다. 고유한 알림 처리에 관해 애플리케이션이 멱등성인지 확인하세요. X-Goog-Channel-Id, X-Goog-Resource-Id, X-Goog-Resource-State, X-Goog-Generation, X-Goog-Metageneration 등의 알림을 고유하게 식별하는 데 도움이 되는 알림 헤더 조합을 선택하여 이를 수행할 수 있습니다.

클라이언트 애플리케이션 예시

이 섹션에서는 변경 알림 이벤트를 처리하는 App Engine 클라이언트 애플리케이션을 만드는 방법을 설명합니다.

예시 애플리케이션에는 MainPage라는 클래스가 있습니다. 사용자가 객체를 업데이트하거나 버킷에 추가하면 MainPage 클래스가 알림 이벤트를 처리합니다. 간소화를 위해 실제 처리를 수행하는 post 메서드가 알림이 수신된 시간과 함께 메시지를 기록합니다. 이 코드를 실제 처리 로직으로 바꿀 수 있습니다. 아직 App Engine 애플리케이션 개발에 익숙하지 않으면 계속하기 전에 샘플 앱을 배포해 보거나 튜토리얼을 따라해 보세요.

애플리케이션 구성하기
app.yaml 구성 파일을 만들어 버킷의 변경 알림 이벤트를 처리하는 클라이언트 애플리케이션을 지정합니다.
```
application: APPLICATION
version: 1
runtime: python38
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: change_notification_client.app
```

애플리케이션 만들기
다음 예시에서는 버킷의 변경 알림 이벤트 처리를 위한 클라이언트 애플리케이션을 구현합니다. 이름을 change_notification_client.py로 지정한 다음 앱을 배포합니다.

"""Notification handling for Google Cloud Storage."""

import json
import logging

import webapp2

class MainPage(webapp2.RequestHandler):
  """Process notification events."""
  def get(self):
    logging.info("Get request to notification page.")
    self.response.write("Welcome to the notification app.")

  def post(self):  # pylint: disable-msg=C6409
    """Process the notification event.

    This method is invoked when the notification channel is first created with
    a sync event, and then subsequently every time an object is added to the
    bucket, updated (both content and metadata) or removed. It records the
    notification message in the log.
    """

    logging.debug(
        '%s\n\n%s',
        '\n'.join(['%s: %s' % x for x in self.request.headers.iteritems()]),
        self.request.body)

    # The following code is for demonstration. Replace
    # it with your own notification processing code.

    if 'X-Goog-Resource-State' in self.request.headers:
      resource_state = self.request.headers['X-Goog-Resource-State']
      if resource_state == 'sync':
        logging.info('Sync message received.')
      else:
        an_object = json.loads(self.request.body)
        bucket = an_object['bucket']
        object_name = an_object['name']
        logging.info('%s/%s %s', bucket, object_name, resource_state)
    else:
      logging.info("Other post.")

logging.getLogger().setLevel(logging.DEBUG)
app = webapp2.WSGIApplication([('/', MainPage)], debug=True)

버킷에 애플리케이션의 액세스 권한 할당하기
버킷이 App Engine 앱과 다른 서비스 계정에 의해 소유된 경우 애플리케이션에 버킷에 대한 소유자 액세스 권한을 부여합니다.
버킷에서 객체 변경 감시 시작
App Engine 애플리케이션 URL address와 함께 watchAll 요청을 사용하여 버킷을 감시하여 애플리케이션에 대한 알림 채널을 만듭니다(예: https://ApplicationId.appspot.com/).
애플리케이션 테스트
애플리케이션이 예상대로 작동하는지 확인하려면 다음 단계를 수행합니다.
1. 애플리케이션이 올바르게 배포되고 작동하는지 확인하려면 다음 curl 명령어를 실행합니다.
```
curl -X Post https://APPLICATION_ID.appspot.com
```
  도메인 이름을 사용하여 애플리케이션을 배포하는 경우 이전 명령어에서 appspot.com 대신 해당 이름을 사용하세요.
2. 프로젝트의 로깅 페이지로 이동합니다. 필요한 경우 기록된 메시지 목록을 새로고칩니다. 애플리케이션에서 생성한 로그 메시지가 기록되는지 확인합니다.
3. 버킷에 객체를 추가합니다. Cloud Storage가 애플리케이션에 알리고, 애플리케이션이 메시지를 기록합니다.
4. 프로젝트의 로깅 페이지로 이동합니다. 기록된 메시지 목록을 새로 고치고 메시지에서 객체 복사본을 찾습니다.
알림 채널 삭제
버킷 감시를 위한 알림 명령어 실행 시 반환된 채널 및 리소스 식별자를 지정하여 알림 채널을 삭제합니다.