이벤트

이벤트는 비동기식이며 Google Cloud Pub/Sub에서 관리합니다( Project당 하나의 주제). 이벤트는 모든 기기와 구조에 업데이트를 제공하며, 사용자가 액세스 토큰을 취소하지 않고 이벤트 메시지가 만료되지 않는 한 이벤트 수신이 보장됩니다.

이벤트 사용 설정

이벤트는 SDM API의 선택적 기능입니다. 이벤트를 사용 설정하는 방법은 이벤트 사용 설정을 참고하세요. Project

Google Cloud Pub/Sub

Pub/Sub의 작동 방식에 관한 자세한 내용은 Google Cloud Pub/Sub 문서를 참고하세요. 구체적인 방법은 다음과 같습니다.

방법 가이드를 통해 Pub/Sub의 기본사항을 알아봅니다.
인증 작동 방식을 이해합니다.
제공된 클라이언트 라이브러리 를 선택하거나 직접 작성하고 REST/HTTP 또는 gRPC API 표면을 사용합니다.

이벤트 구독

2025년 1월 이전에 이벤트가 사용 설정된 경우 다음과 같은 형식으로 Project ID에 관한 주제가 제공되었습니다. Project

projects/gcp-project-name/subscriptions/topic-id

2025년 1월 이후에 생성된 프로젝트는 Pub/Sub 주제를 자체 호스팅해야 하며 자체 주제 ID를 제공해야 합니다. 자세한 내용은 주제 만들기 를 참고하세요.

이벤트를 수신하려면 사용 사례에 따라 해당 주제에 대한 pull 또는 push 구독을 만듭니다. SDM 주제에 대한 여러 구독이 지원됩니다. 자세한 내용은 구독 관리를 참고하세요.

이벤트 시작

Pub/Sub 구독이 생성된 후 처음으로 이벤트를 시작하려면 일회성 트리거로 devices.list API 호출을 합니다. 이 호출 후 모든 구조 및 기기의 이벤트가 게시됩니다.

예시는 빠른 시작 가이드의 승인 페이지를 참고하세요.

이벤트 순서

Pub/Sub는 이벤트의 순서 지정된 전송을 보장하지 않으며 이벤트의 수신 순서가 이벤트가 실제로 발생한 순서와 일치하지 않을 수 있습니다. timestamp 필드를 사용하여 이벤트 순서를 조정합니다. 이벤트는 개별적으로 또는 단일 이벤트 메시지로 결합되어 도착할 수도 있습니다.

자세한 내용은 메시지 순서 지정을 참고하세요.

사용자 ID

구현이 구조 또는 기기가 아닌 사용자를 기반으로 하는 경우 이벤트 페이로드의 userID 필드를 사용하여 리소스와 이벤트를 상호 연결합니다. 이 필드는 특정 사용자를 나타내는 난독화된 ID입니다.

userID는 각 API 호출의 HTTP 응답 헤더에서도 사용할 수 있습니다.

관계 이벤트

관계 이벤트는 리소스의 관계형 업데이트를 나타냅니다. 예를 들어 기기가 구조에 추가되거나 기기가 구조에서 삭제되는 경우입니다.

관계 이벤트에는 세 가지 유형이 있습니다.

CREATED
삭제됨
업데이트됨

관계 이벤트의 페이로드는 다음과 같습니다.

페이로드

{
  "eventId" : "e4569d38-8013-46b4-ae24-62e40110f5a0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

관계 이벤트에서 object는 이벤트를 트리거한 리소스이고 subject는 이제 object와 관계를 맺은 리소스입니다. 위의 예에서 user 가 이 특정 기기에 대한 액세스 권한을 developer에 부여했으며 이제 user'의 승인된 기기가 승인된 구조와 관련되어 이벤트를 트리거합니다.

subject는 채팅방 또는 구조만 될 수 있습니다. 가 구조를 볼 권한이 없는 경우 a developer 는 항상 비어 있습니다. usersubject

필드

필드	설명	데이터 유형
`eventId`	이벤트의 고유 식별자입니다.	`string` 예: '354536eb-5504-4869-b874-758502f8274a'
`timestamp`	이벤트가 발생한 시간입니다.	`string` 예: '2019-01-01T00:00:01Z'
`relationUpdate`	관계 업데이트에 관한 세부정보가 포함된 객체입니다.	`object`
`userId`	사용자를 나타내는 난독화된 고유 식별자입니다.	`string` 예: 'AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi'

다양한 이벤트 유형과 작동 방식에 관한 자세한 내용은 이벤트를 참고하세요.

예

이벤트 페이로드는 관계 이벤트 유형마다 다릅니다.

CREATED

구조 생성됨

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

기기 생성됨

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

기기 생성됨

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

업데이트됨

기기 이동됨

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

삭제됨

구조 삭제됨

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

기기 삭제됨

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

기기 삭제됨

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

관계 이벤트는 다음과 같은 경우 전송되지 않습니다.

채팅방이 삭제됨

리소스 이벤트

리소스 이벤트는 리소스와 관련된 업데이트를 나타냅니다. 예를 들어 온도 조절기의 모드를 변경하는 것과 같이 특성 필드 값의 변경에 대한 응답일 수 있습니다. 또한 기기 버튼을 누르는 것과 같이 특성 필드를 변경하지 않는 기기 작업을 나타낼 수도 있습니다.

특성 필드 값의 변경에 대한 응답으로 생성된 이벤트에는 기기 GET 호출과 유사한 traits 객체가 포함됩니다.

페이로드

{
  "eventId" : "0efe7b28-4cfd-4f69-90e4-50ee9ee79acc",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

개별 특성 문서를 사용하여 특성 필드 변경 리소스 이벤트의 페이로드 형식을 이해합니다.

특성 필드를 변경하지 않는 기기 작업에 대한 응답으로 생성된 이벤트에도 resourceUpdate 객체가 포함된 페이로드가 있지만 traits 객체 대신 events 객체가 있습니다.

페이로드

{
  "eventId" : "1b3afcc8-a274-4836-9f9a-b8235aa4b0e0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "5IWtUlKhUJ02ni3zMynroMi1bt...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

이러한 유형의 리소스 이벤트는 특정 특성에 정의되어 있습니다. 예를 들어 동작 이벤트는 CameraMotion trait에 정의되어 있습니다. 이러한 유형의 리소스 이벤트의 페이로드 형식을 이해하려면 각 특성의 문서 를 참고하세요.

필드

필드	설명	데이터 유형
`eventId`	이벤트의 고유 식별자입니다.	`string` 예: '1b3afcc8-a274-4836-9f9a-b8235aa4b0e0'
`timestamp`	이벤트가 발생한 시간입니다.	`string` 예: '2019-01-01T00:00:01Z'
`resourceUpdate`	리소스 업데이트에 관한 세부정보가 포함된 객체입니다.	`object`
`userId`	사용자를 나타내는 난독화된 고유 식별자입니다.	`string` 예: 'AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi'
`eventThreadId`	이벤트 스레드의 고유 식별자입니다.	`string` 예: 'd67cd3f7-86a7-425e-8bb3-462f92ec9f59'
`eventThreadState`	이벤트 스레드의 상태입니다.	`string` 값: 'STARTED', 'UPDATED', 'ENDED'
`resourceGroup`	이 이벤트와 유사한 업데이트가 있을 수 있는 리소스를 나타내는 객체입니다. (``resourceUpdate`` 객체에서) 이벤트 자체의 리소스는 항상 이 객체에 표시됩니다.	`object`

다양한 이벤트 유형과 작동 방식에 관한 자세한 내용은 이벤트를 참고하세요.

업데이트 가능한 알림

리소스 이벤트를 기반으로 하는 알림은 Android 또는 iOS와 같은 앱에서 구현할 수 있습니다. 전송되는 알림 수를 줄이기 위해 업데이트 가능한 알림 이라는 기능이 구현될 수 있습니다. 이 기능에서는 동일한 이벤트 스레드의 후속 이벤트를 기반으로 새 정보로 기존 알림이 업데이트됩니다.

업데이트 가능한 알림을 지원하는 이벤트를 선택하고 문서에서 업데이트 가능 으로 태그가 지정됩니다. 이러한 이벤트에는 페이로드에 eventThreadId라는 추가 필드가 있습니다. 이 필드를 사용하여 사용자에게 표시된 기존 알림을 업데이트하기 위해 개별 이벤트를 서로 연결합니다.

이벤트 스레드는 이벤트 세션과 동일하지 않습니다. 이벤트 스레드 는 동일한 스레드의 이전 이벤트에 대한 업데이트된 상태를 식별합니다. 이벤트 세션 은 서로 관련된 별도의 이벤트를 식별하며 지정된 이벤트 세션에 여러 이벤트 스레드가 있을 수 있습니다.

알림을 위해 다양한 유형의 이벤트가 여러 스레드로 그룹화됩니다.

이 스레드 그룹화 및 타이밍 로직은 Google에서 처리하며 언제든지 변경될 수 있습니다. A developer 는 SDM API에서 제공하는 이벤트 스레드 및 세션을 기반으로 알림을 업데이트해야 합니다.

스레드 상태

업데이트 가능한 알림을 지원하는 이벤트에는 해당 시점의 이벤트 스레드 상태를 나타내는 eventThreadState 필드도 있습니다. 이 필드에는 다음과 같은 값이 있습니다.

STARTED — 이벤트 스레드의 첫 번째 이벤트입니다.
UPDATED — 진행 중인 이벤트 스레드의 이벤트입니다. 단일 스레드에 이 상태의 이벤트가 0개 이상 있을 수 있습니다.
ENDED — 이벤트 스레드의 마지막 이벤트로, 스레드 유형에 따라 마지막 UPDATED 이벤트의 중복일 수 있습니다.

이 필드를 사용하여 이벤트 스레드의 진행 상황과 종료 시점을 추적할 수 있습니다.

이벤트 필터링

경우에 따라 기기에서 감지된 이벤트가 SDM Pub/Sub 주제에 게시되지 않도록 필터링될 수 있습니다. 이러한 동작을 이벤트 필터링 이라고 합니다. 이벤트 필터링의 목적은 짧은 시간 내에 너무 많은 유사한 이벤트 메시지를 게시하지 않는 것입니다.

예를 들어 초기 동작 이벤트에 대한 메시지가 SDM 주제에 게시될 수 있습니다. 그 후 동작에 대한 다른 메시지는 설정된 기간이 지나기 전까지 게시되지 않도록 필터링됩니다. 해당 기간이 지나면 해당 이벤트 유형의 이벤트 메시지가 다시 게시될 수 있습니다.

Google Home 앱 (GHA)에서 필터링된 이벤트는 의 이벤트 기록에 계속 표시됩니다. user하지만 이러한 이벤트는 알림 유형이 사용 설정되어 있더라도 앱 알림을 생성하지 않습니다.

각 이벤트 유형에는 Google에서 정의하고 언제든지 변경될 수 있는 자체 이벤트 필터링 로직이 있습니다. 이 이벤트 필터링 로직은 이벤트 스레드 및 세션 로직과 독립적입니다.

서비스 계정

서비스 계정은 SDM API 구독 및 이벤트 메시지를 관리하는 데 권장됩니다. 서비스 계정은 사용자가 아닌 애플리케이션 또는 가상 머신에서 사용되며 고유한 계정 키가 있습니다.

Pub/Sub API의 서비스 계정 승인은 2LO (Two-legged OAuth)를 사용합니다.

2LO 승인 흐름에서 다음을 수행합니다.

서비스 키를 사용하여 액세스 토큰을 요청합니다. developer
developer API 호출에 액세스 토큰을 사용합니다.

Google 2LO 및 설정 방법에 관한 자세한 내용은 서버 간 애플리케이션에 OAuth 2.0 사용을 참고하세요.

승인

서비스 계정은 Pub/Sub API와 함께 사용하도록 승인되어야 합니다.

Google Cloud에서 Cloud Pub/Sub API 를 사용 설정합니다.
서비스 계정 만들기에 설명된 대로 서비스 계정 및 서비스 계정 키를 만듭니다. Pub/Sub 구독자 역할만 부여하는 것이 좋습니다. Pub/Sub API를 사용할 머신에 서비스 계정 키를 다운로드해야 합니다.
이전 단계의 페이지에 있는 안내에 따라 인증 사용자 인증 정보 (서비스 계정 키)를 애플리케이션 코드에 제공하거나 API 액세스를 빠르게 테스트하려면 oauth2l을 사용하여 액세스 토큰을 수동으로 가져옵니다.
Pub/Sub API와 함께 서비스 계정 사용자 인증 정보 또는 액세스 토큰을 사용하여 메시지를 가져오고 확인합니다.project.subscriptions

oauth2l

Google oauth2l은 Go로 작성된 OAuth용 명령줄 도구입니다. Go를 사용하여 Mac 또는 Linux에 설치합니다.

시스템에 Go가 없는 경우 먼저 다운로드하여 설치합니다.
Go가 설치되면 oauth2l을 설치하고 PATH 환경 변수에 위치를 추가합니다.
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

oauth2l을 사용하여 적절한 OAuth 범위로 API의 액세스 토큰을 가져옵니다.

oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

예를 들어 서비스 키가 ~/myServiceKey-eb0a5f900ee3.json에 있는 경우:

oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

사용에 관한 자세한 내용은 oauth2l README를 참고하세요.

Google API 클라이언트 라이브러리

OAuth 2.0을 사용하는 Google API에 사용할 수 있는 여러 클라이언트 라이브러리가 있습니다. 원하는 언어에 관한 자세한 내용은 Google API 클라이언트 라이브러리를 참고하세요.

와 함께 이러한 라이브러리를 사용하는 경우 다음 범위 문자열을 사용합니다. Pub/Sub API

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

오류

이 가이드와 관련하여 다음 오류 코드가 반환될 수 있습니다.

오류 메시지	RPC	문제 해결
카메라 이미지를 더 이상 다운로드할 수 없습니다.	`DEADLINE_EXCEEDED`	이벤트 이미지는 이벤트가 게시된 후 30초 후에 만료됩니다. 만료되기 전에 이미지를 다운로드해야 합니다.
이벤트 ID가 카메라에 속하지 않습니다.	`FAILED_PRECONDITION`	카메라 이벤트에서 반환된 올바른 `eventID`를 사용합니다.

전체 API 오류 코드 목록은 API 오류 코드 참조에서 확인하세요.

이벤트 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이벤트 사용 설정

Google Cloud Pub/Sub

이벤트 구독

이벤트 시작

이벤트 순서

사용자 ID

관계 이벤트

페이로드

필드

예

CREATED

구조 생성됨

기기 생성됨

기기 생성됨

업데이트됨

기기 이동됨

삭제됨

구조 삭제됨

기기 삭제됨

기기 삭제됨

리소스 이벤트

페이로드

페이로드

필드

업데이트 가능한 알림

스레드 상태

이벤트 필터링

서비스 계정

승인

oauth2l

Google API 클라이언트 라이브러리

오류

이벤트