이 페이지는 Cloud Translation API를 통해 번역되었습니다.

푸시 알림

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

개요

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

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

수신 URL 또는 '웹훅' 설정 콜백 수신자입니다.
리소스가 변경될 때 트리거되는 API 알림 메시지를 처리하는 HTTPS 서버입니다.
모니터링하려는 각 리소스 엔드포인트에 대해 (알림 채널)을 설정합니다.
채널은 알림의 라우팅 정보를 지정합니다. 메시지를 보낼 수 있습니다 채널 설정 과정에서 알림을 받을 수 있습니다. 채널의 리소스가 변경될 때마다 Admin SDK API는 해당 URL에 POST 요청으로 알림 메시지를 전송합니다.

현재 Admin SDK API는 Activities 리소스를 사용합니다.

알림 채널 만들기

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

보기 요청

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

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

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

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

예

활동 리소스에 대한 모든 감시 요청의 일반적인 형식은 다음과 같습니다.

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
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 channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

userKey, applicationName, eventName, filters 매개변수를 사용하여 특정 이벤트, 사용자 또는 애플리케이션의 알림만 수신할 수 있습니다.

참고: 다음 예에서는 명확성을 위해 요청 본문을 생략합니다.

모든 관리자 활동을 확인합니다.

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

모든 문서 활동 확인:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

특정 사용자의 관리자 활동을 확인합니다.

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

사용자 비밀번호 변경과 같은 특정 이벤트를 확인합니다.

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

특정 문서의 변경사항을 확인합니다.

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

필수 속성

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

이 속성을 고유하게 식별하는 id 속성 문자열입니다. 새 알림 채널을 생성합니다. 이때 범용 고유 식별자 (UUID) 또는 이와 유사한 고유 문자열입니다. 최대 길이: 64자(영문 기준)

설정한 ID 값은 모든 알림의 X-Goog-Channel-Id HTTP 헤더 모든 메시지를 받게 됩니다.
값으로 설정된 type 속성 문자열 web_hook입니다.
이 알림 채널의 알림을 리슨하고 응답하는 URL로 설정된 address 속성 문자열입니다. 이것은 웹훅을 설정하고, HTTPS를 사용해야 합니다.

Admin SDK API는 웹 서버에 유효한 SSL 인증서가 설치된 경우에만 이 HTTPS 주소로 알림을 보낼 수 있습니다. 다음 인증서는 유효하지 않습니다.
- 자체 서명된 인증서
- 신뢰할 수 없는 출처에서 서명한 인증서
- 취소된 인증서
- 대상 호스트 이름과 일치하지 않는 주체가 있는 인증서

선택 속성

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

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

알림 채널 토큰을 사용하는 경우 다음을 수행하는 것이 좋습니다.
- URL 쿼리와 같은 확장 가능한 인코딩 형식 사용 매개변수입니다. 예: forwardTo=hr&createdBy=mobile
- OAuth 토큰과 같은 민감한 정보는 포함하지 마세요.
참고: 매우 민감한 데이터를 전송해야 하는 경우 토큰에 추가하기 전에 암호화해야 합니다.
expiration 속성 문자열이 Unix 타임스탬프 (밀리초 단위) Admin SDK API를 이 알림 채널에 대한 메시지 전송을 중지합니다.

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

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: Admin SDK API의 경우 최대 만료 시간은 21,600초 만약 요청에 포함된 expiration 속성, 만료 시간 시간은 21,600초로 기본 설정됩니다. 나타냅니다.

요청에 관한 자세한 내용은 watch 메서드를 참조하세요. (API 참조의 Activities 리소스)

대답 보기

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도 반환된 정보에 포함됩니다.

참고: resourceId 속성은 리소스의 안정적이고 버전과 무관한 식별자입니다. 이 resourceUri 속성은 감시된 동영상의 표준 URI입니다. 현재 API 버전의 컨텍스트에 배치되므로 버전별로 다릅니다

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

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

동기화 메시지

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

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

현재는 알림 채널을 자동으로 갱신할 수 있는 방법이 없습니다. 채널의 만료일이 가까워지면 watch 메서드를 호출하여 새 채널로 교체해야 합니다. 항상 새 채널의 id 속성에 고유한 값을 사용해야 합니다. 주목할 만한 점은 '겹치는' 두 개의 알림 채널이 확인할 수 있습니다

알림 수신

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

참고: 알림 전달 HTTPS 요청 사용자 에이전트를 APIs-Google로 지정하고 robots.txt를 준수 지시어를 사용할 수 있습니다. API Google 사용자 에이전트

알림 메시지 형식 해석

모든 알림 메시지에는 X-Goog- 접두사가 있는 HTTP 헤더 세트가 포함됩니다. 일부 알림 유형에는 메일 본문입니다.

헤더

Admin SDK 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` 또는 이벤트 이름입니다.
`X-Goog-Resource-URI`	감시된 리소스의 API 버전별 식별자입니다.
가끔 발생
`X-Goog-Channel-Expiration`	알림 채널 만료 날짜 및 시간으로 사람이 읽을 수 있는 형식입니다. 정의된 경우에만 존재합니다.
`X-Goog-Channel-Token`	애플리케이션에서 설정했으며 알림 소스를 확인하는 데 사용할 수 있는 알림 채널 토큰입니다. 정의된 경우에만 표시됩니다.

활동에 대한 알림 메시지의 요청 본문에 포함되는 정보는 다음과 같습니다.

속성	설명
`kind`	이 객체를 활동 리소스로 식별합니다. 값은 고정 문자열 '`admin#reports#activity`'입니다.
`id`	활동 레코드의 고유 식별자입니다.
`id.time`	활동이 발생한 시간입니다. 값은 ISO 8601 날짜 및 시간 형식입니다. 시간 는 완전한 날짜와 시간, 분, 초를 YYYY-MM-DDThh:mm:ssTZD 형식으로 더한 값입니다. 예: 2010-04-05T17:30:04+01:00
`id.uniqueQualifier`	여러 이벤트의 시간이 동일한 경우 고유한 한정자입니다.
`id.applicationName`	이벤트가 속한 애플리케이션 이름입니다. 가능한 값은 다음과 같습니다. <ph type="x-smartling-placeholder"> </ph> admin 캘린더 drive 그룹 groups_enterprise login mobile saml 토큰 user_accounts
`id.customerId`	Google Workspace 계정의 고유 식별자입니다.
`actor`	작업을 수행하는 사용자입니다.
`actor.callerType`	보고서에 나열된 활동을 수행한 작성자 유형입니다. 이 버전의 API에서 `callerType`는 보고서에 나열된 작업을 실행한 `USER` 또는 OAuth 2LO 항목 요청입니다.
`actor.email`	활동이 보고되는 사용자의 기본 이메일 주소입니다.
`actor.profileId`	사용자의 고유한 Google Workspace 프로필 ID입니다.
`ownerDomain`	관리 콘솔 또는 Docs 애플리케이션의 문서 소유자의 도메인입니다. 보고서의 이벤트의 영향을 받는 도메인입니다.
`ipAddress`	작업을 실행하는 사용자의 IP 주소입니다. 이는 Google Workspace에 로그인할 때 사용자의 인터넷 프로토콜 (IP) 주소로, 사용자의 실제 위치가 반영되거나 반영되지 않을 수 있습니다. 예를 들어 IP 주소는 사용자의 프록시 서버 주소 또는 가상 사설망 (VPN) 주소일 수 있습니다. 이 API는 IPv4 및 IPv6를 지원합니다.
`events[]`	보고서의 활동 이벤트
`events[].type`	이벤트 유형입니다. 관리자가 변경하는 Google Workspace 서비스 또는 기능은 `eventName` 속성을 사용하여 이벤트를 식별하는 `type` 속성에서 식별됩니다.
`events[].name`	이벤트 이름입니다. API가 보고하는 활동의 특정 이름입니다. 각 `eventName`는 API가 이벤트 유형으로 구성하는 특정 Google Workspace 서비스 또는 기능과 관련이 있습니다. 일반적으로 `eventName` 요청 매개변수의 경우 다음을 따르세요. `eventName`를 지정하지 않으면 보고서는 `eventName`의 가능한 모든 인스턴스를 반환합니다. `eventName`를 요청하면 API 응답은 `eventName`가 포함된 모든 활동을 반환합니다. 반환된 활동에는 요청된 속성 외에도 다른 `eventName` 속성이 있을 수 있습니다.
`events[].parameters[]`	다양한 애플리케이션의 매개변수 값 쌍
`events[].parameters[].name`	매개변수의 이름입니다.
`events[].parameters[].value`	매개변수의 문자열 값입니다.
`events[].parameters[].intValue`	매개변수의 정수 값입니다.
`events[].parameters[].boolValue`	매개변수의 부울 값입니다.

예

활동 리소스 이벤트의 알림 메시지는 일반적으로 다음과 같은 형식입니다.

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 메서드와 동일합니다. 각 애플리케이션에는 고유한 이벤트가 있습니다.

알림 중지

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

https://www.googleapis.com/admin/reports_v1/channels/stop

이 방법을 사용하려면 최소한 채널의 id 및 resourceId 속성 참조하세요. Admin SDK API에 여러 유형의 watch 메서드가 있는 경우 이 메서드는 하나 밖에 없습니다. stop 메서드를 사용하여 지도 가장자리에 패딩을 추가할 수 있습니다.

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

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

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

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

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