리소스 변경 알림

이 문서에서는 리소스가 변경될 때 애플리케이션에 알리는 푸시 알림을 사용하는 방법을 설명합니다.

개요

Google Drive API는 리소스의 변경사항을 모니터링할 수 있는 푸시 알림을 제공합니다. 이 기능을 사용하여 애플리케이션의 성능을 개선할 수 있습니다. 이를 통해 리소스가 변경되었는지 확인하기 위해 리소스를 폴링하는 데 드는 추가 네트워크 및 컴퓨팅 비용을 없앨 수 있습니다. 감시 중인 리소스가 변경될 때마다 Google Drive API는 애플리케이션에 알립니다.

푸시 알림을 사용하려면 다음 두 가지 작업을 수행해야 합니다.

• 수신 URL 또는 '웹훅' 콜백 수신기를 설정합니다.

  이는 리소스가 변경될 때 트리거되는 API 알림 메시지를 처리하는 HTTPS 서버입니다.

• 모니터링할 각 리소스 엔드포인트에 대해 (알림 채널)을 설정합니다.

  채널은 알림 메시지의 라우팅 정보를 지정합니다. 채널 설정의 일환으로 알림을 수신할 특정 URL을 식별해야 합니다. 채널의 리소스가 변경될 때마다 Google Drive API는 해당 URL에 POST 요청으로 알림 메시지를 보냅니다.

참고: 이 문서에서 사용되는 '채널'이라는 단어는 알림 채널을 구체적으로 지칭하며 이 API 또는 서비스에서 사용되는 다른 유형의 채널을 지칭하지 않습니다. 동일한 리소스에 대해 여러 알림 채널이 동시에 활성화될 수 있습니다.

현재 Google Drive API는 files 및 changes 메서드의 변경사항에 대한 알림을 지원합니다.

알림 채널 만들기

푸시 알림을 요청하려면 모니터링할 각 리소스에 대해 알림 채널을 설정해야 합니다. 알림 채널이 설정되면 Google Drive API는 모니터링되는 리소스가 변경될 때 애플리케이션에 알립니다.

워치 요청하기

각 감시 가능한 Google Drive API 리소스에는 다음 형식의 URI에 연결된 watch 메서드가 있습니다.

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

특정 리소스의 변경사항에 관한 메시지의 알림 채널을 설정하려면 리소스의 watch 메서드에 POST 요청을 전송합니다.

각 알림 채널은 특정 사용자 및 특정 리소스 (또는 리소스 집합)와 연결됩니다. 현재 사용자 또는 서비스 계정이 이 리소스를 소유하거나 이 리소스에 액세스할 권한이 없으면 watch 요청이 성공하지 않습니다.

예

다음 코드 샘플은 channels 리소스를 사용하여 files.watch 메서드를 통해 단일 files 리소스의 변경사항을 감시하는 방법을 보여줍니다.

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

다음 코드 샘플은 channels 리소스를 사용하여 changes.watch 메서드를 통해 모든 changes의 감시를 시작하는 방법을 보여줍니다.

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

필수 속성

각 watch 요청에는 다음 필드를 제공해야 합니다.

• 프로젝트 내에서 이 새 알림 채널을 고유하게 식별하는 id 속성 문자열입니다. 범용 고유 식별자(UUID) 또는 유사한 고유 문자열을 사용하는 것이 좋습니다. 최대 길이: 64자(영문 기준)

  설정한 ID 값은 이 채널에 대해 수신하는 모든 알림 메시지의 X-Goog-Channel-Id HTTP 헤더에 다시 표시됩니다.

• web_hook 값으로 설정된 type 속성 문자열입니다.

• 이 알림 채널의 알림을 수신하고 이에 응답하는 URL로 설정된 address 속성 문자열입니다. 이는 웹훅 콜백 URL이며 HTTPS를 사용해야 합니다.

  웹 서버에 유효한 SSL 인증서가 설치된 경우에만 Google Drive API가 이 HTTPS 주소로 알림을 보낼 수 있습니다. 다음 인증서는 유효하지 않습니다.

  • 자체 서명된 인증서
  • 신뢰할 수 없는 출처에서 서명한 인증서
  • 취소된 인증서
  • 주체가 대상 호스트 이름과 일치하지 않는 인증서

선택 속성

watch 요청으로 다음 선택적 필드를 지정할 수도 있습니다.

• 채널 토큰으로 사용할 임의의 문자열 값을 지정하는 token 속성입니다. 다양한 용도로 알림 채널 토큰을 사용할 수 있습니다. 예를 들어 토큰을 사용하여 각 수신 메시지가 애플리케이션에서 만든 채널용인지 확인하여 알림이 스푸핑되지 않도록 하거나 이 채널의 목적에 따라 애플리케이션 내에서 메시지를 올바른 대상으로 라우팅할 수 있습니다. 최대 길이: 256자(영문 기준)

  이 토큰은 애플리케이션이 이 채널에 대해 수신하는 모든 알림 메시지의 X-Goog-Channel-Token HTTP 헤더에 포함됩니다.

  알림 채널 토큰을 사용하는 경우 다음을 권장합니다.

  • URL 쿼리 매개변수와 같은 확장 가능한 인코딩 형식을 사용합니다. 예: forwardTo=hr&createdBy=mobile

  • OAuth 토큰과 같은 민감한 정보는 포함하지 마세요.

  참고: 매우 민감한 데이터를 전송해야 하는 경우 토큰에 추가하기 전에 암호화해야 합니다.

• 이 알림 채널에 대한 메시지 전송을 Google Drive API가 중지해야 하는 날짜와 시간의 Unix 타임스탬프(밀리초)로 설정된 expiration 속성 문자열입니다.

  채널에 만료 시간이 있는 경우 애플리케이션이 이 채널에 대해 수신하는 모든 알림 메시지에 X-Goog-Channel-Expiration HTTP 헤더의 값 (사람이 읽을 수 있는 형식)으로 포함됩니다.

참고: Google Drive API의 경우 최대 만료 시간은 files 리소스의 경우 현재 시간 후 86,400초 (1일)이고 changes의 경우 604,800초 (1주일)입니다. 요청에서 expiration 속성을 설정하지 않으면 만료 시간이 현재 시간으로부터 3, 600초로 기본 설정됩니다.

요청에 관한 자세한 내용은 API 참조에서 files 및 changes 메서드의 watch 메서드를 참고하세요.

시계 응답

watch 요청이 알림 채널을 성공적으로 생성하면 HTTP 200 OK 상태 코드를 반환합니다.

워치 응답의 메시지 본문은 아래 예와 같이 방금 만든 알림 채널에 관한 정보를 제공합니다.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

요청의 일부로 전송한 속성 외에도 반환된 정보에는 이 알림 채널에서 모니터링되는 리소스를 식별하는 resourceId 및 resourceUri도 포함됩니다.

참고: resourceId 속성은 리소스의 안정적이고 버전과 관계없는 식별자입니다. resourceUri 속성은 현재 API 버전의 컨텍스트에서 모니터링되는 리소스의 표준 URI이므로 버전별로 다릅니다.

알림 수신을 중지하려는 경우와 같이 반환된 정보를 다른 알림 채널 작업에 전달할 수 있습니다.

응답에 관한 자세한 내용은 API 참조의 files 및 changes 메서드에 관한 watch 메서드를 참고하세요.

동기화 메시지

리소스 감시를 위한 알림 채널을 만든 후 Google Drive API는 알림이 시작됨을 나타내는 sync 메시지를 전송합니다. 이러한 메시지의 X-Goog-Resource-State HTTP 헤더 값은 sync입니다. 네트워크 타이밍 문제로 인해 watch 메서드 응답을 받기 전에도 sync 메시지를 받을 수 있습니다.

sync 알림은 무시해도 되지만 사용할 수도 있습니다. 예를 들어 채널을 유지하지 않기로 결정한 경우 알림 수신 중지 호출에서 X-Goog-Channel-ID 및 X-Goog-Resource-ID 값을 사용할 수 있습니다. sync 알림을 사용하여 후속 이벤트를 준비하기 위한 초기화를 실행할 수도 있습니다.

Google Drive API가 수신 URL로 전송하는 sync 메시지의 형식은 아래와 같습니다.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

동기화 메시지의 X-Goog-Message-Number HTTP 헤더 값은 항상 1입니다. 이 채널의 각 후속 알림에는 이전 알림보다 큰 메시지 번호가 있지만 메시지 번호는 순차적이지 않습니다.

알림 채널 갱신

알림 채널에는 만료 시간이 있을 수 있으며, 값은 요청에 의해 결정되거나 Google Drive API 내부 제한 또는 기본값에 의해 결정됩니다 (더 제한적인 값이 사용됨). 채널의 만료 시간(있는 경우)은 watch 메서드에서 반환된 정보에 Unix 타임스탬프(밀리초)로 포함됩니다. 또한 만료일 및 시간이 사람이 읽을 수 있는 형식으로 애플리케이션이 이 채널에 대해 수신하는 모든 알림 메시지의 X-Goog-Channel-Expiration HTTP 헤더에 포함됩니다.

현재 알림 채널을 자동으로 갱신하는 방법은 없습니다. 채널의 만료가 임박한 경우 watch 메서드를 호출하여 새 채널로 대체해야 합니다. 새 채널의 id 속성에는 항상 고유한 값을 사용해야 합니다. 동일한 리소스의 두 알림 채널이 활성화된 경우 '중복' 기간이 있을 수 있습니다.

알림 수신

관찰 중인 리소스가 변경될 때마다 애플리케이션은 변경사항을 설명하는 알림 메시지를 수신합니다. Google Drive API는 이러한 메시지를 HTTPS POST 요청으로 이 알림 채널의 address 속성으로 지정한 URL에 전송합니다.

참고: 알림 전송 HTTPS 요청은 APIs Google 사용자 에이전트에 설명된 대로 APIs-Google 사용자 에이전트를 지정하고 robots.txt 명령어를 따릅니다.

알림 메시지 형식 해석

모든 알림 메시지에는 X-Goog- 접두사가 있는 HTTP 헤더 집합이 포함됩니다. 일부 유형의 알림에는 메시지 본문도 포함될 수 있습니다.

헤더

Google Drive API가 수신 URL에 게시한 알림 메시지에는 다음 HTTP 헤더가 포함됩니다.

헤더	설명
항상 표시
X-Goog-Channel-ID	이 알림 채널을 식별하기 위해 제공한 UUID 또는 기타 고유 문자열입니다.
X-Goog-Message-Number	이 알림 채널의 이 메시지를 식별하는 정수입니다. sync 메시지의 값은 항상 1입니다. 채널의 후속 메시지마다 메시지 번호가 증가하지만 순차적이지는 않습니다.
X-Goog-Resource-ID	감시 중인 리소스를 식별하는 불투명 값입니다. 이 ID는 API 버전 간에 안정적입니다.
X-Goog-Resource-State	알림을 트리거한 새 리소스 상태입니다. 가능한 값: sync, add, remove, update, trash, untrash 또는 change입니다.
X-Goog-Resource-URI	감시 중인 리소스의 API 버전별 식별자입니다.
때때로 있음
X-Goog-Changed	변경사항에 대한 추가 세부정보입니다. 가능한 값: content, parents, children 또는 permissions . sync 메시지에는 제공되지 않습니다.
X-Goog-Channel-Expiration	알림 채널 만료일 및 시간입니다. 사람이 읽을 수 있는 형식으로 표현됩니다. 정의된 경우에만 표시됩니다.
X-Goog-Channel-Token	애플리케이션에서 설정했으며 알림 소스를 확인하는 데 사용할 수 있는 알림 채널 토큰입니다. 정의된 경우에만 표시됩니다.

files 및 changes의 알림 메시지가 비어 있습니다.

예

요청 본문이 포함되지 않은 files 리소스의 변경 알림 메시지:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

요청 본문이 포함된 changes 리소스의 변경 알림 메시지:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

알림에 대한 응답

성공을 나타내려면 200, 201, 202, 204 또는 102 상태 코드를 반환하면 됩니다.

서비스에서 Google API 클라이언트 라이브러리를 사용하고 500, 502, 503 또는 504를 반환하는 경우 Google Drive API는 지수 백오프를 사용하여 재시도합니다. 다른 모든 반환 상태 코드는 메시지 실패로 간주됩니다.

Google Drive API 알림 이벤트 이해하기

이 섹션에서는 Google Drive API로 푸시 알림을 사용할 때 수신할 수 있는 알림 메시지에 대해 자세히 설명합니다.

X-Goog-Resource-State	적용 대상	다음과 같은 경우에 제공됩니다.
sync	files, changes	채널이 생성되었습니다. 이제 해당 채널에 대한 알림을 받게 됩니다.
add	files	리소스가 생성되었거나 공유되었습니다.
remove	files	기존 리소스가 삭제되었거나 공유가 취소되었습니다.
update	files	리소스의 속성 (메타데이터)이 하나 이상 업데이트되었습니다.
trash	files	리소스가 휴지통으로 이동되었습니다.
untrash	files	휴지통에서 리소스가 삭제되었습니다.
change	changes	하나 이상의 변경사항 항목이 추가되었습니다.

시간이 지남에 따라 이 목록에 추가 리소스 상태 이벤트가 추가될 수 있습니다. 예기치 않은 이벤트 유형이 수신될 수 있습니다. 이러한 이벤트 핸들러는 적절히 무시해야 합니다.

update 이벤트의 경우 X-Goog-Changed HTTP 헤더가 제공될 수 있습니다. 이 헤더에는 발생한 변경사항의 유형을 설명하는 쉼표로 구분된 목록이 포함됩니다.

변경 유형	의미
content	리소스 콘텐츠가 업데이트되었습니다.
properties	하나 이상의 리소스 속성이 업데이트되었습니다.
parents	하나 이상의 리소스 상위 요소가 추가되거나 삭제되었습니다.
children	하나 이상의 리소스 하위 요소가 추가되거나 삭제되었습니다.
permissions	리소스 권한이 업데이트되었습니다.

X-Goog-Changed 헤더 예시:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

알림 중지

expiration 속성은 알림이 자동으로 중지되는 시점을 제어합니다. 다음 URI에서 stop 메서드를 호출하여 만료되기 전에 특정 채널의 알림 수신을 중지할 수 있습니다.

https://www.googleapis.com/drive/v3/channels/stop

이 메서드를 사용하려면 아래 예와 같이 채널의 id 및 resourceId 속성을 하나 이상 제공해야 합니다. Google Drive API에 watch 메서드가 있는 리소스 유형이 여러 개 있는 경우 stop 메서드는 하나만 있습니다.

올바른 권한이 있는 사용자만 채널을 중지할 수 있습니다. 특히 다음 항목이 중요합니다.

• 일반 사용자 계정으로 채널을 만든 경우 채널을 만든 동일한 클라이언트의 동일한 사용자 (인증 토큰의 OAuth 2.0 클라이언트 ID로 식별됨)만 채널을 중지할 수 있습니다.
• 채널이 서비스 계정으로 생성된 경우 동일한 클라이언트의 모든 사용자가 채널을 중지할 수 있습니다.

다음 코드 샘플은 알림 수신을 중지하는 방법을 보여줍니다.

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}