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