디바이스 섀도우 REST API - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

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

디바이스 섀도우 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 콘솔 사물 세부 정보 페이지를 사용합니다. 콘솔에서:

    1. 관리(Manage)를 열고 관리(Manage) 아래에서 사물(Things)을 선택합니다.

    2. 사물 목록에서 엔드포인트 URI를 가져올 항목을 선택합니다.

    3. 디바이스 섀도우(Device Shadows) 탭을 선택하고 섀도우를 선택합니다. 디바이스 섀도우 세부 정보 페이지의 디바이스 섀도우 URL 섹션에서 엔드포인트 URI를 볼 수 있습니다.

엔드포인트의 형식은 다음과 같습니다.

identifier.iot.region.amazonaws.com

섀도우 REST API는 디바이스 통신 프로토콜에서 설명한 것과 동일한 HTTPS 프로토콜/포트 매핑을 따릅니다.

참고

API를 사용하려면 iotdevicegateway를 인증을 위한 서비스 이름으로 사용해야 합니다. 자세한 내용은 IoTDataPlane을 참조하세요.

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 상호 인증을 수용합니다.

다음은 호출자가 디바이스 섀도우를 검색하도록 허용하는 정책 예제입니다.

JSON
{
  "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 상호 인증을 수용합니다.

다음은 호출자가 디바이스 섀도우를 업데이트하도록 허용하는 정책 예제입니다.

JSON
{
  "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 상호 인증을 수용합니다.

다음은 호출자가 디바이스 섀도우를 삭제하도록 허용하는 정책 예제입니다.

JSON
{
  "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 상호 인증을 수용합니다.

다음은 호출자가 사물의 명명된 섀도우를 나열하도록 허용하는 정책 예제입니다.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:ListNamedShadowsForThing",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}