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