기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 디바이스 섀도우 REST API
섀도우는 상태 정보 업데이트를 위해 다음 URI를 노출시킵니다.
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
엔드포인트는에 고유합니다 AWS 계정. 엔드포인트를 찾으려면 다음을 수행할 수 있습니다.
+ AWS CLI에서 [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) 명령을 사용합니다.
+ AWS IoT 콘솔 설정을 사용합니다. **설정(Settings)**에서 **사용자 지정 엔드포인트(Custom endpoint)** 아래에 엔드포인트가 나열됩니다.
+ AWS IoT 콘솔 사물 세부 정보 페이지를 사용합니다. 콘솔에서:
1. **관리(Manage)**를 열고 **관리(Manage)** 아래에서 **사물(Things)**을 선택합니다.
1. 사물 목록에서 엔드포인트 URI를 가져올 항목을 선택합니다.
1. **디바이스 섀도우(Device Shadows)** 탭을 선택하고 섀도우를 선택합니다. **디바이스 섀도우 세부 정보** 페이지의 **디바이스 섀도우 URL** 섹션에서 엔드포인트 URI를 볼 수 있습니다.
엔드포인트의 형식은 다음과 같습니다.
```
identifier.iot.region.amazonaws.com
```
섀도우 REST API는 [디바이스 통신 프로토콜](protocols.md)에서 설명한 것과 동일한 HTTPS 프로토콜/포트 매핑을 따릅니다.
**참고**
API를 사용하려면 `iotdevicegateway`를 인증을 위한 서비스 이름으로 사용해야 합니다. 자세한 내용은 [IoTDataPlane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html)을 참조하세요.
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
API를 사용하여 API의 쿼리 파라미터의 일부로 `name=shadowName`을 제공하여 명명된 섀도우를 생성할 수도 있습니다.
## GetThingShadow
지정된 사물의 섀도우를 가져옵니다.
응답 상태 문서는 `desired` 상태와 `reported` 상태 간 델타를 포함합니다.
**요청**
요청은 표준 HTTP 헤더와 다음 URI를 포함합니다.
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
명명되지 않은(클래식) 섀도우에는 `name` 쿼리 파라미터가 필요하지 않습니다.
**응답**
성공 시, 응답은 표준 HTTP 헤더와 다음 코드 및 본문을 포함합니다.
```
HTTP 200
Response Body: response state document
```
자세한 내용은 [응답 상태 문서 예제](device-shadow-document.md#device-shadow-example-response-json) 섹션을 참조하세요.
**권한 부여**
섀도우를 검색하려면 호출자가 `iot:GetThingShadow` 작업을 수행하도록 허용하는 정책이 필요합니다. 디바이스 섀도우 서비스는 두 가지 인증 양식, 즉 IAM 자격 증명을 사용하는 서명 버전 4 또는 클라이언트 인증서를 사용하는 TLS 상호 인증을 수용합니다.
다음은 호출자가 디바이스 섀도우를 검색하도록 허용하는 정책 예제입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
지정된 사물의 섀도우를 업데이트합니다.
업데이트는 요청 상태 문서에 지정된 필드에만 영향을 미칩니다. 디바이스 섀도우에서 `null` 값의 필드가 모두 제거됩니다.
**요청**
요청은 표준 HTTP 헤더와 다음 URI 및 본문을 포함합니다.
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
명명되지 않은(클래식) 섀도우에는 `name` 쿼리 파라미터가 필요하지 않습니다.
자세한 내용은 [요청 상태 문서 예제](device-shadow-document.md#device-shadow-example-request-json) 섹션을 참조하세요.
**응답**
성공 시, 응답은 표준 HTTP 헤더와 다음 코드 및 본문을 포함합니다.
```
HTTP 200
Response body: response state document
```
자세한 내용은 [응답 상태 문서 예제](device-shadow-document.md#device-shadow-example-response-json) 섹션을 참조하세요.
**권한 부여**
섀도우를 업데이트하려면 호출자가 `iot:UpdateThingShadow` 작업을 수행하도록 허용하는 정책이 필요합니다. 디바이스 섀도우 서비스는 두 가지 인증 양식, 즉 IAM 자격 증명을 사용하는 서명 버전 4 또는 클라이언트 인증서를 사용하는 TLS 상호 인증을 수용합니다.
다음은 호출자가 디바이스 섀도우를 업데이트하도록 허용하는 정책 예제입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
지정된 사물의 섀도를 삭제합니다.
**요청**
요청은 표준 HTTP 헤더와 다음 URI를 포함합니다.
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
명명되지 않은(클래식) 섀도우에는 `name` 쿼리 파라미터가 필요하지 않습니다.
**응답**
성공 시, 응답은 표준 HTTP 헤더와 다음 코드 및 본문을 포함합니다.
```
HTTP 200
Response body: Empty response state document
```
섀도우를 삭제해도 버전 번호가 0으로 재설정되지는 않습니다.
**권한 부여**
디바이스 섀도우를 삭제하려면 호출자가 `iot:DeleteThingShadow` 작업을 수행하도록 허용하는 정책이 필요합니다. 디바이스 섀도우 서비스는 두 가지 인증 양식, 즉 IAM 자격 증명을 사용하는 서명 버전 4 또는 클라이언트 인증서를 사용하는 TLS 상호 인증을 수용합니다.
다음은 호출자가 디바이스 섀도우를 삭제하도록 허용하는 정책 예제입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
지정한 사물에 대한 섀도우를 나열합니다.
**요청**
요청은 표준 HTTP 헤더와 다음 URI를 포함합니다.
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
다음 결과 집합을 가져오기 위한 토큰입니다.
이 값은 페이징된 결과에서 반환되며 다음 페이지를 반환하는 호출에 사용됩니다.
pageSize
각 호출에서 반환할 섀도우 이름의 수입니다. 또한 `nextToken` 단원도 참조하세요.
thingName
명명된 섀도우를 나열할 사물의 이름입니다.
**응답**
성공 시, 응답은 표준 HTTP 헤더와 다음 코드 및 [섀도우 이름 목록 응답 문서](device-shadow-document.md#device-shadow-list-json)를 포함합니다.
**참고**
명명되지 않은(클래식) 섀도우는 이 목록에 나타나지 않습니다. 클래식 섀도우만 있거나 지정한 `thingName`이 없는 경우 응답은 빈 목록입니다.
```
HTTP 200
Response body: Shadow name list document
```
**권한 부여**
디바이스 섀도우 목록을 표시하려면 호출자가 `iot:ListNamedShadowsForThing` 작업을 수행하도록 허용하는 정책이 필요합니다. 디바이스 섀도우 서비스는 두 가지 인증 양식, 즉 IAM 자격 증명을 사용하는 서명 버전 4 또는 클라이언트 인증서를 사용하는 TLS 상호 인증을 수용합니다.
다음은 호출자가 사물의 명명된 섀도우를 나열하도록 허용하는 정책 예제입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```