기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
이 주제에서는 섀도우 작업을 위해 AWS IoT 에서 제공하는 세 가지 메서드와 관련된 메시지에 대해 설명합니다. 이러한 메서드는 다음과 같습니다.
UPDATE
-
섀도우가 없는 경우 섀도우를 생성하거나, 메시지 본문에 제공된 상태 정보로 기존 섀도우의 콘텐츠를 업데이트합니다. AWS IoT 는 각 업데이트와 함께 타임스탬프를 기록하여 상태가 마지막으로 업데이트된 시점을 나타냅니다. 섀도우의 상태가 변경되면는
desired
와reported
상태 간의 차이가 있는/delta
메시지를 모든 MQTT 구독자에게 AWS IoT 보냅니다./delta
메시지를 수신한 디바이스 또는 앱은 차이에 따라 작업을 수행할 수 있습니다. 예를 들어 디바이스가 원하는 상태로 업데이트할 수도 있고, 앱이 디바이스의 상태 변경을 반영하도록 UI를 업데이트할 수도 있습니다. GET
-
메타데이터를 포함하여 섀도우의 전체 상태가 포함된 현재 섀도우 문서를 검색합니다.
DELETE
-
디바이스 섀도우와 해당 콘텐츠를 삭제합니다.
삭제된 디바이스 섀도우 문서는 복원할 수 없지만 삭제된 디바이스 섀도우 문서의 이름으로 새 디바이스 섀도우를 생성할 수 있습니다. 지난 48시간 이내에 삭제된 것과 동일한 이름의 디바이스 섀도우 문서를 생성하는 경우 새 디바이스 섀도우 문서의 버전 번호는 삭제된 문서의 버전 번호를 따릅니다. 디바이스 섀도우 문서가 48시간 이상 삭제된 경우 동일한 이름을 가진 새 디바이스 섀도우 문서의 버전 번호는 0이 됩니다.
프로토콜 지원
AWS IoT 는 섀도우와 상호 작용하기 위한 MQTT
상태 요청 및 보고
AWS IoT 및 섀도우를 사용하여 IoT 솔루션을 설계할 때는 변경을 요청할 앱 또는 디바이스와 이를 구현할 앱을 결정해야 합니다. 일반적으로 디바이스는 변경 사항을 구현하고 섀도우에 다시 보고하며, 앱과 서비스는 섀도우에 응답하고 변경을 요청합니다. 솔루션은 다를 수 있지만 이 주제의 예에서는 클라이언트 앱 또는 서비스가 섀도우의 변경을 요청하고 디바이스가 변경을 수행하며 이를 섀도우에 다시 보고한다고 가정합니다.
섀도우 업데이트
앱 또는 서비스는를 사용하거나 /update 주제에 UpdateThingShadow API 게시하여 섀도우의 상태를 업데이트할 수 있습니다. 업데이트는 요청에 지정된 필드에만 영향을 미칩니다.
클라이언트가 상태 변경을 요청할 때 섀도우 업데이트
클라이언트가 MQTT 프로토콜을 사용하여 섀도우의 상태 변경을 요청하는 경우
-
클라이언트가 변경할 속성을 식별할 수 있도록 현재 섀도우 문서가 있어야 합니다. 현재 섀도우 문서를 가져오는 방법은 /get 작업을 참조하세요.
-
클라이언트는 다음 MQTT 주제를 구독합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
클라이언트는 원하는 섀도우 상태를 포함하는 상태 문서와 함께
$aws/things/
요청 주제를 게시합니다. 변경할 속성만 문서에 포함시켜야 합니다. 다음은 원하는 상태의 문서에 대한 예입니다.thingName
/shadow/name/shadowName
/update{ "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } }
-
업데이트 요청이 유효한 경우는 섀도우에서 원하는 상태를 AWS IoT 업데이트하고 다음 주제에 메시지를 게시합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta
/update/accepted
메시지에는 /accepted response state document 섀도우 문서가 포함되어 있으며/update/delta
메시지에는 /delta response state document 섀도우 문서가 포함되어 있습니다. -
-
업데이트 요청이 유효하지 않은 경우는 오류를 설명하는 오류 응답 문서 섀도우 문서가 포함된
$aws/things/
주제가 포함된 메시지를 AWS IoT 게시합니다.thingName
/shadow/name/shadowName
/update/rejected
클라이언트가를 사용하여 섀도우의 상태 변경을 요청하는 경우 API
-
클라이언트는 요청 상태 문서 상태 문서를 메시지 본문으로
UpdateThingShadow
API 사용하여를 호출합니다. -
요청이 유효하면는 HTTP 성공 응답 코드와 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 AWS IoT 반환합니다.
AWS IoT 또한는 메시지를 구독하는 모든 디바이스 또는 클라이언트에 대한 /delta response state document 섀도우 문서와 함께
$aws/things/
주제에 MQTT 메시지를 게시합니다.thingName
/shadow/name/shadowName
/update/delta -
요청이 유효하지 않은 경우는 HTTP 오류 응답 코드를 응답 메시지 본문오류 응답 문서으로 AWS IoT 반환합니다.
디바이스가 /update/delta
주제에 대한 /desired
상태를 수신하면 디바이스에서 원하는 변경을 수행합니다. 그런 다음 /update
주제에 메시지를 전송해 현재 상태를 섀도우에 보고합니다.
디바이스가 현재 상태를 보고할 때 섀도우 업데이트
디바이스가 MQTT 프로토콜을 사용하여 현재 상태를 섀도우에 보고하는 경우
-
디바이스는 섀도우를 업데이트하기 전에 다음 MQTT 주제를 구독해야 합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
디바이스는 이 예에서와 같이 현재 상태를 보고하는
$aws/things/
주제에 메시지를 게시하여 현재 상태를 보고합니다.thingName
/shadow/name/shadowName
/update{ "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } }
-
가 업데이트를 AWS IoT 수락하면 /accepted response state document 섀도우 문서를 사용하여
$aws/things/
주제에 메시지를 게시합니다.thingName
/shadow/name/shadowName
/update/accepted -
업데이트 요청이 유효하지 않은 경우는 오류를 설명하는 오류 응답 문서 섀도우 문서가 포함된
$aws/things/
주제가 포함된 메시지를 AWS IoT 게시합니다.thingName
/shadow/name/shadowName
/update/rejected
디바이스가를 사용하여 섀도우에 현재 상태를 보고하는 경우 API
-
디바이스는 요청 상태 문서 상태 문서를 메시지 본문으로
UpdateThingShadow
API 사용하여를 호출합니다. -
요청이 유효하면는 섀도우를 AWS IoT 업데이트하고 /accepted response state document 섀도우 문서와 함께 HTTP 성공 응답 코드를 응답 메시지 본문으로 반환합니다.
AWS IoT 또한는 메시지를 구독하는 모든 디바이스 또는 클라이언트에 대한 /delta response state document 섀도우 문서와 함께
$aws/things/
주제에 MQTT 메시지를 게시합니다.thingName
/shadow/name/shadowName
/update/delta -
요청이 유효하지 않은 경우는 HTTP 오류 응답 코드를 응답 메시지 본문오류 응답 문서으로 AWS IoT 반환합니다.
낙관적 잠금
상태 문서 버전을 사용하면 업데이트하는 디바이스 섀도우 문서가 최신 버전인지 확인할 수 있습니다. 버전에 업데이트 요청을 제공하면 현재 버전의 상태 문서가 제공된 버전과 일치하지 않는 경우 서비스가 HTTP 409 충돌 응답 코드로 요청을 거부합니다. 충돌 응답 코드는를 ThingShadow
포함하여를 수정API하는 모든 에서도 발생할 수 있습니다DeleteThingShadow
.
예시:
초기 문서:
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
업데이트: (버전이 일치하지 않음, 이 요청이 거부됨)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
결과:
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
업데이트: (버전이 일치함, 이 요청이 수락됨)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
최종 상태:
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
섀도우 문서 검색
를 사용하거나 /get 주제를 구독하고 게시GetThingShadowAPI하여 섀도우 문서를 검색할 수 있습니다. 그러면 desired
및 reported
상태 사이의 델타를 포함하여 전체 섀도우 문서가 검색됩니다. 이 작업의 절차는 요청하는 주체가 디바이스인지 클라이언트인지에 관계없이 동일합니다.
MQTT 프로토콜을 사용하여 섀도우 문서를 검색하려면
-
디바이스 또는 클라이언트는 섀도우를 업데이트하기 전에 다음 MQTT 주제를 구독해야 합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/get/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/get/rejected
-
-
디바이스나 클라이언트는 메시지 본문이 비어 있는 메시지를
$aws/things/
주제에 게시합니다.thingName
/shadow/name/shadowName
/get -
요청이 성공하면는 메시지 본문에가 있는
$aws/things/
주제에 메시지를 AWS IoT 게시/accepted response state document합니다.thingName
/shadow/name/shadowName
/get/accepted -
요청이 유효하지 않은 경우는 메시지 본문에를 사용하여
$aws/things/
주제에 메시지를 AWS IoT 게시오류 응답 문서합니다.thingName
/shadow/name/shadowName
/get/rejected
를 사용하여 섀도우 문서를 검색하려면 REST API
-
디바이스 또는 클라이언트는 빈 메시지 본문
GetThingShadow
API으로를 호출합니다. -
요청이 유효하면 /accepted response state document는 섀도우 문서가 포함된 HTTP 성공 응답 코드를 응답 메시지 본문으로 AWS IoT 반환합니다.
-
요청이 유효하지 않은 경우는 HTTP 오류 응답 코드를 응답 메시지 본문오류 응답 문서으로 AWS IoT 반환합니다.
섀도우 데이터 삭제
섀도우 데이터를 삭제하는 방법에는 두 가지가 있습니다. 섀도우 문서에서 특정 속성을 삭제하거나 섀도우를 완전히 삭제할 수 있습니다.
-
섀도우에서 특정 속성을 삭제하려면 삭제할 속성의 값을
null
로 설정하여 섀도우를 업데이트합니다. 섀도우 문서에서 값이null
인 필드가 제거됩니다. -
전체 섀도우를 삭제하려면 DeleteThingShadow API 또는를 사용하여 /delete 주제에 게시합니다.
참고
섀도를 삭제해도 버전 번호가 0으로 즉시 재설정되지는 않습니다. 48시간 후에 0으로 재설정됩니다.
섀도우 문서에서 속성 삭제
MQTT 프로토콜을 사용하여 섀도우에서 속성을 삭제하려면
-
디바이스 또는 클라이언트가 변경할 속성을 식별할 수 있도록 현재 섀도우 문서가 있어야 합니다. 현재 섀도우 문서를 가져오는 방법은 섀도우 문서 검색 단원을 참조하세요.
-
디바이스 또는 클라이언트는 다음 MQTT 주제를 구독합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected
-
-
디바이스나 클라이언트는 삭제할 섀도우 속성에
null
값을 할당하는 상태 문서와 함께$aws/things/
요청 주제를 게시합니다. 변경할 속성만 문서에 포함시켜야 합니다. 다음은thingName
/shadow/name/shadowName
/updateengine
속성을 삭제하는 문서의 예입니다.{ "state": { "desired": { "engine": null } } }
-
업데이트 요청이 유효한 경우는 섀도우에서 지정된 속성을 AWS IoT 삭제하고 메시지 본문에 /accepted response state document섀도우 문서가 있는
$aws/things/
주제와 함께 메시지를 게시합니다.thingName
/shadow/name/shadowName
/update/accepted -
업데이트 요청이 유효하지 않은 경우는 오류를 설명하는 오류 응답 문서 섀도우 문서가 포함된
$aws/things/
주제가 포함된 메시지를 AWS IoT 게시합니다.thingName
/shadow/name/shadowName
/update/rejected
를 사용하여 섀도우에서 속성을 삭제하려면 REST API
-
디바이스 또는 클라이언트는 삭제할 섀도우의 속성에
null
값을 할당요청 상태 문서하는UpdateThingShadow
API를 사용하여를 호출합니다. 문서에서 삭제할 속성만 포함합니다. 다음은engine
속성을 삭제하는 문서의 예입니다.{ "state": { "desired": { "engine": null } } }
-
요청이 유효하면는 HTTP 성공 응답 코드와 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 AWS IoT 반환합니다.
-
요청이 유효하지 않은 경우는 HTTP 오류 응답 코드를 응답 메시지 본문오류 응답 문서으로 AWS IoT 반환합니다.
섀도우 삭제
다음은 디바이스의 섀도우를 삭제할 때 고려해야 할 몇 가지 사항입니다.
-
디바이스의 섀도우 상태를
null
로 설정해도 섀도우가 삭제되지는 않습니다. 섀도우 버전은 다음 업데이트 시 증가합니다. -
디바이스 섀도우를 삭제해도 사물 객체가 삭제되지는 않습니다. 사물 객체를 삭제해도 해당 디바이스 섀도우는 삭제되지 않습니다.
-
섀도를 삭제해도 버전 번호가 0으로 즉시 재설정되지는 않습니다. 48시간 후에 0으로 재설정됩니다.
MQTT 프로토콜을 사용하여 섀도우를 삭제하려면
-
디바이스 또는 클라이언트는 다음 MQTT 주제를 구독합니다.
-
$aws/things/
thingName
/shadow/name/shadowName
/delete/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/delete/rejected
-
-
디바이스 또는 클라이언트는 빈 메시지 버퍼를 사용하여
$aws/things/
를 게시합니다.thingName
/shadow/name/shadowName
/delete -
삭제 요청이 유효한 경우는 섀도우를 AWS IoT 삭제하고
$aws/things/
주제와 축약된 /accepted response state document 섀도우 문서가 포함된 메시지를 메시지 본문에 게시합니다. 다음은 수락된 삭제 메시지의 예입니다.thingName
/shadow/name/shadowName
/delete/accepted{ "version": 4, "timestamp": 1591057529 }
-
업데이트 요청이 유효하지 않은 경우는 오류를 설명하는 오류 응답 문서 섀도우 문서가 포함된
$aws/things/
주제가 포함된 메시지를 AWS IoT 게시합니다.thingName
/shadow/name/shadowName
/delete/rejected
를 사용하여 섀도우를 삭제하려면 REST API
-
디바이스 또는 클라이언트가 빈 메시지 버퍼
DeleteThingShadow
API로를 호출합니다. -
요청이 유효하면는 메시지 본문에 HTTP 성공 응답 코드와 /accepted response state document 및 축약된 /accepted response state document 섀도우 문서를 AWS IoT 반환합니다. 다음은 수락된 삭제 메시지의 예입니다.
{ "version": 4, "timestamp": 1591057529 }
-
요청이 유효하지 않은 경우는 HTTP 오류 응답 코드를 응답 메시지 본문오류 응답 문서으로 AWS IoT 반환합니다.