기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 디바이스 섀도우 서비스 문서
<a name="device-shadow-document"></a>

디바이스 섀도우 서비스는 JSON 사양의 모든 규칙을 준수합니다. 값, 객체 및 배열이 디바이스 섀도우 문서에 저장됩니다.

**Topics**
+ [섀도우 문서 예제](#device-shadow-document-syntax)
+ [문서 속성](#document-structure)
+ [델타 상태](#delta-state)
+ [섀도우 문서 버전 관리](#versioning)
+ [섀도우 문서의 클라이언트 토큰](#client-token)
+ [빈 섀도우 문서 속성](#device-shadow-empty-fields)
+ [섀도우 문서의 배열 값](#device-shadow-arrays)

## 섀도우 문서 예제
<a name="device-shadow-document-syntax"></a><a name="device-shadow-example"></a>

디바이스 섀도우 서비스는 [REST API](device-shadow-rest-api.md) 또는 [MQTT Pub/Sub 메시지](device-shadow-mqtt.md)를 사용한 UPDATE, GET 및 DELETE 작업에서 다음 문서를 사용합니다.

**Topics**
+ [요청 상태 문서](#device-shadow-example-request-json)
+ [응답 상태 문서](#device-shadow-example-response-json)
+ [오류 응답 문서](#device-shadow-example-error-json)
+ [섀도우 이름 목록 응답 문서](#device-shadow-list-json)

### 요청 상태 문서
<a name="device-shadow-example-request-json"></a>

요청 상태 문서의 형식은 다음과 같습니다.

```
{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}
```
+ `state` — 업데이트는 지정된 필드에만 영향을 미칩니다. 일반적으로 `desired` 또는 `reported` 속성 중 하나를 사용하지만 동일한 요청에서는 둘 다 사용하지는 않습니다.
  + `desired` — 디바이스에서 업데이트하도록 요청된 상태 속성 및 값입니다.
  + `reported` — 디바이스에서 보고한 상태 속성 및 값입니다.
+ `clientToken` — 사용할 경우, 클라이언트 토큰으로 요청과 해당 응답을 일치시킬 수 있습니다.
+ `version` — 사용할 경우, 디바이스 섀도우 서비스는 지정된 버전이 서비스가 보유하는 최신 버전과 일치하는 경우에만 업데이트를 처리합니다.

### 응답 상태 문서
<a name="device-shadow-example-response-json"></a>

응답 상태 문서의 형식은 응답 유형에 따라 다음과 같습니다.

#### /accepted response state document
<a name="device-shadow-example-response-json-accepted"></a>

```
{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}
```

#### /delta response state document
<a name="device-shadow-example-response-json-delta"></a>

```
{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
    },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}
```

#### /documents response state document
<a name="device-shadow-example-response-json-documents"></a>

```
{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}
```

#### 응답 상태 문서 속성
<a name="device-shadow-example-response-json-properties"></a>
+ `previous` — 성공적으로 업데이트되면 업데이트 전 객체의 `state`를 포함합니다.
+ `current` — 성공적으로 업데이트되면 업데이트 후 객체의 `state`를 포함합니다.
+ `state`
  + `reported` — 사물이 `reported` 섹션의 데이터를 보고하고 요청 상태 문서에 있는 필드만 포함하는 경우에만 존재합니다.
  + `desired` — 디바이스가 `desired` 섹션의 데이터를 보고하고 요청 상태 문서에 있는 필드만 포함하는 경우에만 존재합니다.
+ `metadata` — 언제 상태가 업데이트되었는지 확인할 수 있도록 `desired` 및 `reported` 섹션의 각 속성에 대한 타임스탬프를 포함합니다.
+ `timestamp` - 응답이 생성된 Epoch 날짜 및 시간입니다 AWS IoT.
+ `clientToken` — 유효한 JSON을 `/update` 주제에 게시할 때 클라이언트 토큰이 사용된 경우에만 존재합니다.
+ `version` — AWS IoT에서 공유되는 디바이스 섀도우에 대한 문서의 현재 버전입니다. 현재 버전은 이전 문서 버전보다 1이 증가합니다.

### 오류 응답 문서
<a name="device-shadow-example-error-json"></a>

오류 응답 문서의 형식은 다음과 같습니다.

```
{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}
```
+ `code` — 오류 유형을 나타내는 HTTP 응답 코드입니다.
+ `message` — 추가 정보를 제공하는 텍스트 메시지입니다.
+ `timestamp` - 응답이 생성된 날짜와 시간입니다 AWS IoT. 이 속성은 모든 오류 응답 문서에 존재하지 않습니다.
+ `clientToken` — 게시된 메시지에 클라이언트 토큰이 사용된 경우에만 존재합니다.

자세한 내용은 [디바이스 섀도우 오류 메시지](device-shadow-error-messages.md) 단원을 참조하세요.

### 섀도우 이름 목록 응답 문서
<a name="device-shadow-list-json"></a>

섀도우 이름 목록 응답 문서의 형식은 다음과 같습니다.

```
{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}
```
+ `results` — 섀도우 이름의 배열입니다.
+ `nextToken` — 시퀀스의 다음 페이지를 가져오기 위해 페이징된 요청에 사용할 토큰 값입니다. 반환할 섀도우 이름이 더 이상 없는 경우에는 이 속성이 존재하지 않습니다.
+ `timestamp` - 응답이 생성된 날짜와 시간입니다 AWS IoT.

## 문서 속성
<a name="document-structure"></a>

디바이스 섀도우 문서의 속성은 다음과 같습니다.

`state`  <a name="state"></a>  
`desired`  <a name="desired"></a>
디바이스의 원하는 상태입니다. 앱은 문서의 이 부분에 기록하여, 디바이스와 연결할 필요 없이 디바이스의 상태를 직접 업데이트할 수 있습니다.  
`reported`  <a name="reported"></a>
디바이스의 보고된 상태입니다. 디바이스는 문서의 이 부분을 기록하여 새 상태를 보고합니다. 앱은 문서의 이 부분을 읽어 디바이스의 마지막 보고 상태를 확인합니다.

`metadata`  <a name="metadata"></a>
문서의 `state` 섹션에 저장된 데이터에 대한 정보입니다. 여기에는 `state` 섹션의 각 속성에 대한 Epoch 시간 형식의 타임스탬프가 포함되는데, 이를 통해 각 속성이 업데이트된 시간을 알 수 있습니다.  
메타데이터는 서비스 제한 또는 요금에 대한 문서 크기에 도움이 되지 않습니다. 자세한 내용은 [AWS IoT 서비스 한도](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot) 단원을 참조하세요.

`timestamp`  <a name="timestamp"></a>
메시지가 전송된 시기를 나타냅니다 AWS IoT. 메시지 내 타임스탬프와 `desired` 또는 `reported` 섹션의 개별 속성에 대한 타임스탬프를 사용하면 디바이스에 내장 클록이 없어도 디바이스에서 속성의 사용 기간을 확인할 수 있습니다.

`clientToken`  <a name="clientToken"></a>
MQTT 환경에서 응답을 요청에 연결할 수 있는 디바이스 고유 문자열입니다.

`version`  <a name="version"></a>
문서 버전입니다. 문서가 업데이트될 때마다 이 버전 번호가 증가합니다. 업데이트되는 문서의 버전이 최신인지 확인하는 데 사용됩니다.

자세한 내용은 [섀도우 문서 예제](#device-shadow-document-syntax) 단원을 참조하세요.

## 델타 상태
<a name="delta-state"></a><a name="observing-state-changes"></a>

델타 상태는 `desired` 상태와 `reported` 상태 간 차이를 포함하는 가상의 상태 유형입니다. `desired` 섹션에는 있지만 `reported` 섹션에는 없는 필드가 델타에 포함됩니다. `reported` 섹션에는 있고 `desired` 섹션에는 없는 필드는 델타에 포함되지 않습니다. 델타는 메타데이터를 포함하며, 해당 값은 `desired` 필드 내 메타데이터와 동일합니다. 다음 예를 참조하세요.

```
{
  "state": {
    "desired": {
      "color": "RED",
      "state": "STOP"
    },
    "reported": {
      "color": "GREEN",
      "engine": "ON"
    },
    "delta": {
      "color": "RED",
      "state": "STOP"
    }
  },
  "metadata": {
    "desired": {
      "color": {
        "timestamp": 12345
      },
      "state": {
        "timestamp": 12345
      }
      },
      "reported": {
        "color": {
          "timestamp": 12345
        },
        "engine": {
          "timestamp": 12345
        }
      },
      "delta": {
        "color": {
          "timestamp": 12345
        },
        "state": {
          "timestamp": 12345
        }
      }
    },
    "version": 17,
    "timestamp": 123456789
  }
}
```

중첩된 객체가 다를 경우 델타는 루트까지의 전체 경로를 포함합니다.

```
{
  "state": {
    "desired": {
      "lights": {
        "color": {
          "r": 255,
          "g": 255,
          "b": 255
        }
      }
    },
    "reported": {
      "lights": {
        "color": {
          "r": 255,
          "g": 0,
          "b": 255
        }
      }
    },
    "delta": {
      "lights": {
        "color": {
          "g": 255
        }
      }
    }
  },
  "version": 18,
  "timestamp": 123456789
}
```

디바이스 섀도우 서비스는 `desired` 상태의 각 필드를 `reported` 상태와 비교하여 델타를 계산합니다.

배열은 값처럼 취급됩니다. `desired` 섹션의 한 배열이 `reported` 섹션의 배열과 일치하지 않을 경우 원하는 배열 전체가 델타로 복사됩니다.

## 섀도우 문서 버전 관리
<a name="versioning"></a>

디바이스 섀도우 서비스는 요청과 응답의 모든 업데이트 메시지에 대한 버전 관리를 지원합니다. 즉, 섀도우가 업데이트될 때마다 JSON 문서의 버전이 증가합니다. 이를 통해 2가지가 보장됩니다.
+ 클라이언트가 구 버전을 사용하여 섀도우를 덮어쓰려 할 경우 오류 응답을 받을 수 있습니다. 클라이언트에 디바이스 섀도우를 업데이트하기 전에 재동기화해야 한다는 알림이 제공됩니다.
+ 수신된 메시지가 클라이언트에 저장된 것보다 낮은 버전일 경우 클라이언트는 메시지에 대한 작업을 수행하지 않기로 결정할 수 있습니다.

클라이언트는 섀도우 문서에 버전을 포함하지 않음으로써 버전 일치를 무시할 수 있습니다.

## 섀도우 문서의 클라이언트 토큰
<a name="client-token"></a>

클라이언트 토큰을 MQTT 기반 메시징과 함께 사용하여 요청 및 요청 응답에 동일한 클라이언트 토큰이 포함되었는지 확인할 수 있습니다. 이는 응답과 요청이 연결되도록 합니다.

**참고**  
클라이언트 토큰은 64바이트보다 길면 안 됩니다. 클라이언트 토큰이 64바이트보다 길면 400(잘못된 요청) 응답과 *잘못된 클라이언트 토큰* 오류 메시지가 표시됩니다.

## 빈 섀도우 문서 속성
<a name="device-shadow-empty-fields"></a>

섀도우 문서의 `reported` 및 `desired` 속성은 비어 있거나 현재 섀도우 상태에 적용되지 않을 경우 생략할 수 있습니다. 예를 들어 섀도우 문서는 원하는 상태가 있을 경우에만 `desired` 속성을 포함합니다. 예를 들어 다음은 유효한 상태 문서이지만 `desired` 속성이 없습니다.

```
{
    "reported" : { "temp": 55 }
}
```

`reported` 속성은 디바이스에 의해 섀도우가 업데이트되지 않은 경우와 같이 비어 있을 수도 있습니다.

```
{
    "desired" : { "color" : "RED" }
}
```

업데이트로 인해 `desired` 또는 `reported` 속성이 null이 될 경우 해당 속성이 문서에서 제거됩니다. 다음은 `null`로 설정하여 `desired` 속성을 제거하는 방법을 보여줍니다. 예를 들어 디바이스가 상태를 업데이트할 때 이 작업을 수행할 수 있습니다.

```
{ 
    "state": {
        "reported": {
            "color": "red" 
        }, 
        "desired": null 
    } 
}
```

섀도우 문서에는 `desired` 또는 `reported` 속성이 없을 수도 있으므로 섀도우 문서를 비워 둘 수 있습니다. 비어 있지만 유효한 섀도우 문서의 예입니다.

```
{
}
```

## 섀도우 문서의 배열 값
<a name="device-shadow-arrays"></a>

섀도우는 배열을 지원하지만, 배열에 대한 업데이트가 전체 배열을 대체한다는 점에서 배열을 일반적인 값으로 취급합니다. 배열을 일부만 업데이트할 수는 없습니다.

Initial state:

```
{
    "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```

업데이트:

```
{
    "desired" : { "colors" : ["RED"] }
}
```

최종 상태:

```
{
    "desired" : { "colors" : ["RED"] }
}
```

배열은 null 값을 가질 수 없습니다. 예를 들어 다음 배열은 유효하지 않으므로 거부됩니다.

```
{
    "desired" : { 
        "colors" : [ null, "RED", "GREEN" ]
    }
}
```