이벤트는 비동기식이며 Google Cloud Pub/Sub에 의해 Project이벤트는 모든 기기와 구조에 대한 업데이트를 제공하고 이벤트 수신은 사용자가 액세스 토큰을 취소하지 않고 이벤트 메시지가 만료되었습니다.
이벤트 사용 설정
이벤트는 SDM API의 선택적 기능입니다. 자세한 내용은 이벤트 사용 설정하기 Project에서 알림을 사용 설정하는 방법을 알아보세요.
Google Cloud Pub/Sub
자세한 내용은 Google Cloud Pub/Sub 문서 참조 자세히 알아보겠습니다 특히 다음 항목이 중요합니다.
- Pub/Sub의 기본사항을 알아보고 안내 가이드
- 인증 작동 방식을 이해합니다.
- 제공된 클라이언트 라이브러리 선택 직접 작성하여 REST/HTTP 또는 gRPC API 노출 영역.
이벤트 구독
Project에 이벤트가 사용 설정되면 이와 관련된 주제가 제공됩니다. Project ID는 다음과 같은 형식으로 표시됩니다.
projects/sdm-prod/topics/enterprise-project-id
이벤트를 수신하려면 pull 또는 푸시할 수도 있습니다. 살펴보겠습니다 SDM 주제에 여러 구독이 지원됩니다. 자세한 내용은 자세한 내용은 구독 관리를 참고하세요. 확인할 수 있습니다
이벤트 시작
Pub/Sub 구독이 생성된 후 처음으로 이벤트를 시작하려면
<ph type="x-smartling-placeholder"></ph>
devices.list
일회성 트리거로서의 API 호출 이후 모든 구조 및 기기의 이벤트가 게시됩니다.
호출
예를 보려면 다음을 참조하세요. 빠른 시작의 승인 페이지 가이드.
이벤트 순서
Pub/Sub는 이벤트 전송 순서를 보장하지 않으며 이벤트 수신 순서가
실제로 이벤트가 발생한 순서대로 표시됩니다. timestamp
사용
이벤트 순서를 조정하는 데 도움이 됩니다. 이벤트는 개별적으로 또는 결합되어 도착할 수도 있습니다.
단일 이벤트 메시지로 변환합니다.
자세한 내용은 메시지 순서 지정.
사용자 ID
구조나 기기가 아닌 사용자를 기반으로 구현되는 경우
이벤트와 이벤트를 연관시키기 위한 이벤트 페이로드의 userID
필드 이 필드는
특정 사용자를 나타내는 난독화된 ID입니다.
userID
는 각 API 호출의 HTTP 응답 헤더에서도 사용할 수 있습니다.
관계 이벤트
관계 이벤트는 리소스의 관계형 업데이트를 나타냅니다. 예를 들어 기기가 또는 기기가 구조에서 삭제되는 경우입니다.
관계 이벤트에는 세 가지 유형이 있습니다.
- 생성됨
- DELETED
- 업데이트됨
관계 이벤트의 페이로드는 다음과 같습니다.
페이로드
{ "eventId" : "8a269c64-78bf-438a-a5da-fcdb80f9c89f", "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 이 특정 기기에 대한 액세스 권한을
developeruser님의 승인된 기기가 이제 승인된 기기와 연결됩니다.
이벤트를 트리거하는 역할을 합니다.
subject
는 방 또는 구조일 수만 있습니다. a developer 다음에
user의 구조를 볼 수 있는 권한이 있는 경우 subject
는 항상
비어 있습니다.
필드
필드 | 설명 | 데이터 유형 |
---|---|---|
eventId |
이벤트의 고유 식별자입니다. | string 예: '7f08e80c-3ae5-457f-b2bc-436358873937' |
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" }
DELETED
집이 삭제되었습니다.
"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" }
다음과 같은 경우 관계 이벤트가 전송되지 않습니다.
- 방이 삭제됨
리소스 이벤트
리소스 이벤트는 리소스와 관련된 업데이트를 나타냅니다. 변화에 대한 대응으로 사용할 수 있음 값을 설정합니다(예: 온도 조절기의 모드 변경). 기기 작업을 나타낼 수도 있습니다. 기기 버튼 누르기와 같은 트레잇 필드를 변경하지 않습니다.
트레잇 필드 값의 변경에 대한 응답으로 생성된 이벤트에는
traits
객체입니다.
페이로드
{
"eventId" : "5b49cdcd-c63f-4989-8f39-c9fad1833452",
"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
객체가 있는 페이로드를 events
객체로
traits
객체 대신 다음과 같이 하면 됩니다.
페이로드
{ "eventId" : "5c377e32-acff-4a19-886f-760011858e96",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "gH14hTWnh76TXhQvPYBEB-IEDH...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
이러한 유형의 리소스 이벤트는 특정 트레잇으로 정의됩니다. 예를 들어 모션 이벤트는 다음에 정의되어 있습니다. CameraMotion trait. 각 트레잇의 문서 보기 이러한 유형의 리소스 이벤트의 페이로드 형식을 이해하는 것이 중요합니다.
필드
필드 | 설명 | 데이터 유형 |
---|---|---|
eventId |
이벤트의 고유 식별자입니다. | string 예: '5c377e32-acff-4a19-886f-760011858e96' |
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에서 처리하며 언제든지 변경할 수 있습니다. developer 는 SDM API에서 제공하는 이벤트 스레드 및 세션입니다.
스레드 상태
업데이트 가능한 알림을 지원하는 이벤트에는 eventThreadState
도 있습니다.
해당 시점에 이벤트 스레드의 상태를 나타내는 필드입니다. 이
필드의 값은 다음과 같습니다.
- STARTED — 이벤트 스레드의 첫 번째 이벤트입니다.
- UPDATED — 진행 중인 이벤트 스레드의 이벤트입니다. 단일 스레드에 이 상태의 이벤트가 0개 이상 있을 수 있습니다.
- ENDED — 이벤트 스레드의 마지막 이벤트로, 스레드 유형에 따라 마지막 UPDATED 이벤트와 중복될 수 있습니다.
이 필드는 이벤트 스레드의 진행 상황과 종료됨
이벤트 필터링
경우에 따라 기기에서 감지된 이벤트가 게시에서 제외될 수 있습니다. 설계하는 방법을 살펴보겠습니다 이 동작 이벤트 필터링이라고 합니다. 이벤트 필터링의 목적은 짧은 시간에 유사한 이벤트 메시지를 너무 많이 게시함
예를 들어 메시지가 SDM 주제에 게시될 수 있습니다. 를 사용합니다. 기타 이후 모션에 대한 메시지는 일정 기간이 경과할 때까지 게시에서 필터링됩니다. 이 기간이 지나면 시간이 지나면 해당 이벤트 유형에 대한 이벤트 메시지가 다시 게시될 수 있습니다.
Google Home 앱 (GHA)에서 이전에 발생한 이벤트가 user의 이벤트 내역에는 계속 표시됩니다. 그러나 이러한 이벤트는 앱 알림을 생성하지 않습니다 (알림 유형이 사용)
각 이벤트 유형에는 언제든지 변경될 수 있습니다. 이 이벤트 필터링 로직은 이벤트 스레드 및 세션 로직과 독립적으로 작동합니다.
서비스 계정
SDM API 관리에 서비스 계정을 사용하는 것이 좋습니다. 구독 및 이벤트 메시지 서비스 계정은 애플리케이션 또는 고유하고 고유한 계정 키가 있습니다.
Pub/Sub API의 서비스 계정 승인 사용 Two-legged OAuth (2LO)
2LO 승인 흐름에서 다음을 수행합니다.
- developer 는 서비스 키를 사용하여 액세스 토큰을 요청합니다.
- developer 는 API 호출과 함께 액세스 토큰을 사용합니다.
Google 2LO 및 설정 방법에 대한 자세한 내용은 서버 간 OAuth 2.0 사용하기 애플리케이션으로 이동합니다.
승인
서비스 계정은 Pub/Sub API:
- Cloud Pub/Sub 사용 설정 API Google Cloud의 기타 항목이 여기에 해당합니다
- 다음에 설명된 대로 서비스 계정 및 서비스 계정 키를 만듭니다. 서비스 계정 만들기 Pub/Sub 구독자 역할만 부여하는 것이 좋습니다. 반드시 서비스 계정 키를 Pub/Sub API
- 사용자 인증 정보 (서비스 계정 키)를
이전 애플리케이션의 페이지에 나온 안내에 따라 애플리케이션 코드를
oauth2l
를 사용하여 수동으로 액세스 토큰을 가져옵니다. API 액세스를 신속하게 테스트하고자 할 때 권장됩니다 - 서비스 계정 사용자 인증 정보 또는 액세스 토큰을
Pub/Sub
project.subscriptions
API 확인할 수 있습니다
OAuth2L
Google oauth2l
는 Go로 작성된 OAuth용 명령줄 도구입니다. 다음 기기에 설치:
(Go를 사용하는 Mac 또는 Linux)
- 시스템에 Go가 설치되어 있지 않으면 먼저 다운로드하여 설치하세요.
- Go가 설치되면
oauth2l
를 설치하고 그 위치를PATH
에 추가합니다. 환경 변수: <ph type="x-smartling-placeholder">go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
oauth2l
를 통해 적절한 OAuth 범위:
예를 들어 서비스 키가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
리드미를 참고하세요.
확인할 수 있습니다
Google API 클라이언트 라이브러리
OAuth를 활용하는 Google API에 사용할 수 있는 여러 클라이언트 라이브러리가 있습니다. 2.0. 자세한 내용은 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 오류 코드의 전체 목록입니다.