푸시 알림

필수 속성

watch 요청마다 다음을 제공해야 합니다.

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

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

• type 속성 문자열이 web_hook 값으로 설정되었습니다.

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

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

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

선택 속성

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

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

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

  알림 채널 토큰을 사용하는 경우 다음 안내를 따르는 것이 좋습니다.

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

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

• Admin SDK API에서 이 알림 채널의 메시지 전송을 중지할 날짜와 시간을 Unix 타임스탬프(밀리초)로 설정한 expiration 속성 문자열입니다.

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

시계 응답

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

응답에 대한 자세한 내용은 API 참조의 활동 리소스에 관한 watch 메서드를 참고하세요.

메일 동기화

리소스를 보기 위해 새 알림 채널을 만든 후 Admin SDK API가 sync 메시지를 전송하여 알림이 시작되었음을 나타냅니다. 이러한 메시지의 X-Goog-Resource-State HTTP 헤더 값은 sync입니다. 네트워크 타이밍 문제로 인해 watch 메서드 응답을 수신하기 전이라도 sync 메시지를 수신할 수 있습니다.

sync 알림을 무시해도 괜찮지만, 알림을 사용할 수도 있습니다. 예를 들어 채널을 유지하지 않으려면 호출에서 X-Goog-Channel-ID 및 X-Goog-Resource-ID 값을 사용하여 알림 수신을 중지하면 됩니다. sync 알림을 사용하여 초기화를 수행하면 향후 이벤트를 준비할 수도 있습니다.

다음은 Admin SDK 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 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입니다. 이 채널의 후속 알림마다 메시지 번호가 이전 알림보다 크지만 메시지 번호는 순차적으로 표시되지 않습니다.

알림 채널 갱신

알림 채널은 만료 시간을 가질 수 있으며, 요청 또는 Admin SDK API 내부 한도 또는 기본값에 따라 결정됩니다 (더 제한적인 값이 사용됨). 채널의 만료 시간이 있는 경우 watch 메서드가 반환하는 정보에 Unix 타임스탬프 (ms)로 포함됩니다. 또한 만료 날짜와 시간은 애플리케이션이 이 채널을 위해 수신하는 모든 알림 메시지에 X-Goog-Channel-Expiration HTTP 헤더에서 (사람이 읽을 수 있는 형식) 포함됩니다.

현재 알림 채널을 자동으로 갱신하는 방법은 없습니다. 채널 만료에 가까워지면 watch 메서드를 호출하여 새 채널을 만들어야 합니다. 항상 그렇듯이 새 채널의 id 속성에 고유한 값을 사용해야 합니다. 동일한 리소스의 두 알림 채널이 활성 상태일 때 '겹치는' 기간이 있을 수 있습니다.

알림 메시지 형식 이해하기

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

활동 알림 메시지의 요청 본문에는 다음 정보가 포함됩니다.

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

알림에 응답하기

성공을 나타내기 위해 200, 201, 202, 204 또는 102 상태 코드를 반환할 수 있습니다.

서비스에서 Google API 클라이언트 라이브러리를 사용하고 500, 502, 503 또는 504를 반환하면 Admin SDK API가 지수 백오프로 다시 시도합니다. 그 밖의 모든 반품 상태 코드는 메시지 실패로 간주됩니다.

Admin SDK API 알림 이벤트 이해

이 섹션에서는 Admin SDK API로 푸시 알림을 사용할 때 받을 수 있는 알림 메시지에 관해 자세히 설명합니다.

Reports API 푸시 알림에는 동기화 메시지와 이벤트 알림이라는 두 가지 유형의 메시지가 포함됩니다. 메시지 유형은 X-Goog-Resource-State HTTP 헤더에 표시됩니다. 이벤트 알림에 사용할 수 있는 값은 activities.list 메서드와 동일합니다. 각 애플리케이션에는 고유한 이벤트가 있습니다.

• 관리자
• 캘린더
• 드라이브
• 그룹
• login
• 모바일
• saml
• 토큰
• 사용자 계정