리소스 변경 알림

이 문서에서는 모바일 앱의 상태를 알리는 푸시 알림을 사용하여 애플리케이션 상태를 변경할 수 없습니다

개요

Google Drive API는 푸시 알림을 제공하여 리소스 변경 등이 있습니다 이 기능을 사용하면 실행할 수 있습니다 추가 네트워크 및 컴퓨팅 리소스를 제거하여 리소스 변경 여부를 확인하기 위한 폴링 리소스 관련 비용이 많이 들 수 있습니다. 감시한 리소스가 변경될 때마다 Google Drive API가 애플리케이션입니다.

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

  • 수신 URL 또는 '웹훅' 설정 콜백 수신자입니다.

    이 HTTP(S) 요청을 전송하는 트리거될 수 있습니다

  • 원하는 각 리소스 엔드포인트마다 (알림 채널)을 설정합니다. 있습니다.

    채널은 알림의 라우팅 정보를 지정합니다. 메시지를 보낼 수 있습니다 채널 설정 과정에서 알림을 받을 수 있습니다. 채널의 리소스가 변경될 때마다 Google Drive API가 알림 메시지를 POST로 전송합니다. 해당 URL에 요청을 보냅니다.

현재 Google Drive API는 files 및 changes 메서드

알림 채널 만들기

푸시 알림을 요청하려면 알림 채널을 설정해야 합니다. 모니터링하려는 각 리소스에 대한 유지보수를 설정합니다 알림 채널을 설정한 후 Google Drive API는 감시된 리소스가 발견되면 애플리케이션에 이를 알립니다. 있습니다.

감시 요청 만들기

각 시청 가능한 Google Drive API 리소스에는 watch 메서드를 다음 형식의 URI에 추가합니다.

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

알림 채널을 설정할 때 POST 요청을 리소스의 watch 메서드

각 알림 채널은 특정 사용자 및 특정 리소스 또는 리소스 집합일 수 있습니다. watch 요청 현재 사용자가 서비스 계정을 사용하여 이 리소스를 소유하거나 액세스할 권한이 있습니다.

예

다음 코드 샘플은 files.watch 메서드를 사용하여 channels 리소스를 사용하여 단일 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.
}

다음 코드 샘플은 changes.watch 메서드를 사용하여 channels 리소스를 사용하여 모든 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 헤더 모든 메시지를 받게 됩니다.

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

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

    Google Drive API는 유효한 SSL 인증서가 설치된 경우에만 이 HTTPS 주소를 웹 서버에서 실행되는 것입니다 다음 인증서는 유효하지 않습니다.

    • 자체 서명된 인증서
    • 신뢰할 수 없는 출처에서 서명한 인증서
    • 취소된 인증서
    • 대상과 일치하지 않는 주체가 있는 인증서 있습니다.

선택 속성

이러한 선택 입력란을 watch 요청:

  • 임의의 문자열을 지정하는 token 속성 채널 토큰으로 사용할 값입니다. 알림 채널을 사용하면 사용할 수 있습니다 예를 들어 토큰을 사용하여 각 수신 메시지가 애플리케이션 만들기가 실행되는 동안 알림이 스푸핑되어 메일을 올바른 목적지로 라우팅하거나 이 채널의 목적에 따라 신청서를 제출해야 합니다. 최대 길이: 256자(영문 기준)

    토큰은 모든 알림에 HTTP 헤더 X-Goog-Channel-Token개 메시지를 받게 됩니다.

    알림 채널 토큰을 사용하는 경우 다음을 수행하는 것이 좋습니다.

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

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

  • expiration 속성 문자열이 Unix 타임스탬프 Google Drive API를 실행할 날짜와 시간의 (밀리초) 이 알림 채널에 대한 메시지 전송을 중지합니다.

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

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

대답 보기

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: 이 리소스에서 감시 중인 리소스를 식별합니다. 알림 채널.

반환된 정보를 다른 알림 채널에 전달할 수 있습니다. 예를 들어 수신을 중단하고 알림을 받을 수 있습니다.

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

동기화 메시지

리소스를 감시하기 위한 알림 채널을 생성한 후에는 Google Drive API는 sync 메시지를 전송하여 알림이 시작됩니다. X-Goog-Resource-State HTTP 헤더 값은 sync입니다. 네트워크로 인한 문제 타이밍 문제가 있으면 sync 메시지가 수신될 수 있습니다. 이 작업은 watch 메서드 응답을 받기 전에도 계속 발생합니다.

sync 알림은 무시해도 괜찮지만 그렇게 할 수도 있습니다. 사용할 수도 있습니다 예를 들어 X-Goog-Channel-ID 및 호출의 값 X-Goog-Resource-ID개 알림 수신을 중지합니다. 또한 준비를 위해 초기화를 실행하는 sync 알림 확인할 수 있습니다.

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

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 내부 한도에 의해 결정됨 또는 기본값 (더 제한적인 값이 사용됨)입니다. 채널 만료 시간(있는 경우)은 Unix 타임스탬프로 포함됩니다. (밀리초 단위)를 watch 메서드에서 반환한 정보에서 확인할 수 있습니다. 또한 만료일 및 시간이 (사람이 읽을 수 있는 형식으로) 포함된 이 채널에 대해 애플리케이션이 수신하는 알림 메시지를 X-Goog-Channel-Expiration HTTP 헤더.

현재는 알림 채널을 자동으로 갱신할 수 있는 방법이 없습니다. 날짜 만료가 임박한 경우 다음을 호출하여 채널을 새 채널로 대체해야 합니다. watch 메서드를 사용하여 지도 가장자리에 패딩을 추가할 수 있습니다. 항상 그렇듯이 새 채널의 id 속성입니다. 주목할 만한 점은 '겹치는' 두 개의 알림 채널이 확인할 수 있습니다

알림 수신

감시된 리소스가 변경될 때마다 애플리케이션은 알림 메시지가 표시됩니다. Google Drive API는 메시지를 HTTPS POST 요청으로 지정된 URL에 이 알림에 대한 속성 address개 채널을 구독합니다.

알림 메시지 형식 해석

모든 알림 메시지에는 X-Goog- 프리픽스. 일부 알림 유형에는 메일 본문입니다.

헤더

Google Drive API가 수신한 URL에는 다음 HTTP 헤더가 포함됩니다.

헤더 설명
항상 표시
X-Goog-Channel-ID 이 식별을 위해 제공한 UUID 또는 기타 고유한 문자열입니다. 알림 채널.
X-Goog-Message-Number 이 알림의 메시지를 식별하는 정수 채널을 구독합니다. sync 메시지의 값은 항상 1입니다. 메시지 이후 채널의 각 메시지에 대해 숫자가 증가하지만 순차적이지 않습니다.
X-Goog-Resource-ID 감시된 리소스를 식별하는 불투명 값입니다. 이 ID는 안정성이 우수합니다
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 클라이언트 라이브러리를 사용하는 경우 Google Drive API 500, 502, 503 또는 504를 반환합니다. 지수 백오프로 재시도합니다. 다른 모든 반환 상태 코드는 메시지 실패로 간주됩니다.

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 속성은 알림이 자동으로 중지되는 시점을 제어합니다. 다음과 같은 작업을 할 수 있습니다. 사전에 특정 채널의 알림 수신을 중지하도록 선택할 수 있습니다. 다음 위치에서 stop 메서드를 호출하면 만료됩니다. 다음 URI를 사용합니다.

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"
}