푸시 알림

필수 속성

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

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

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

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

• 이 알림 채널의 알림을 리슨하고 응답하는 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 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입니다. 이 채널의 후속 알림마다 메시지 번호가 이전 번호보다 크지만 메시지 번호는 순차적이지 않습니다.

알림 채널 갱신

알림 채널에는 만료 시간이 있을 수 있으며 이 값은 요청 또는 Admin SDK API 내부 제한 또는 기본값에 따라 결정됩니다 (더 제한적인 값이 사용됨). 채널의 만료 시간(있는 경우)은 watch 메서드에서 반환하는 정보에 유닉스 타임스탬프(밀리초)로 포함됩니다. 또한 만료일과 시간은 애플리케이션이 이 채널에 대해 수신하는 모든 알림 메시지의 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 메서드와 동일합니다. 각 애플리케이션에는 고유한 이벤트가 있습니다.

• admin
• 캘린더
• 드라이브
• 그룹
• login
• mobile
• saml
• 토큰
• user_accounts