섀도우와의 상호 작용 - AWS IoT Core
프로토콜 지원상태 요청 및 보고섀도우 업데이트섀도우 문서 검색섀도우 데이터 삭제

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

섀도우와의 상호 작용

이 주제에서는 섀도우 작업을 위해 AWS IoT 에서 제공하는 세 가지 메서드와 관련된 메시지에 대해 설명합니다. 이러한 메서드는 다음과 같습니다.

UPDATE

섀도우가 없는 경우 섀도우를 생성하거나, 메시지 본문에 제공된 상태 정보로 기존 섀도우의 콘텐츠를 업데이트합니다. AWS IoT 는 각 업데이트와 함께 타임스탬프를 기록하여 상태가 마지막으로 업데이트된 시점을 나타냅니다. 섀도우의 상태가 변경되면 와 상태의 차이를 포함하여 모든 MQTT 구독자에게 /delta 메시지를 AWS IoT 보냅니다. desired reported /delta 메시지를 수신한 디바이스 또는 앱은 차이에 따라 작업을 수행할 수 있습니다. 예를 들어 디바이스가 원하는 상태로 업데이트할 수도 있고, 앱이 디바이스의 상태 변경을 반영하도록 UI를 업데이트할 수도 있습니다.

GET

메타데이터를 포함하여 섀도우의 전체 상태가 포함된 현재 섀도우 문서를 검색합니다.

DELETE

디바이스 섀도우와 해당 콘텐츠를 삭제합니다.

삭제된 디바이스 섀도우 문서는 복원할 수 없지만 삭제된 디바이스 섀도우 문서의 이름으로 새 디바이스 섀도우를 생성할 수 있습니다. 지난 48시간 이내에 삭제된 것과 동일한 이름의 디바이스 섀도우 문서를 생성하는 경우 새 디바이스 섀도우 문서의 버전 번호는 삭제된 문서의 버전 번호를 따릅니다. 디바이스 섀도우 문서가 48시간 이상 삭제된 경우 동일한 이름을 가진 새 디바이스 섀도우 문서의 버전 번호는 0이 됩니다.

프로토콜 지원

AWS IoT HTTPS 프로토콜을 통한 MQTT 및 REST API를 지원하여 섀도우와 상호 작용할 수 있습니다. AWS IoT MQTT 게시 및 구독 작업에 대한 예약된 요청 및 응답 주제 세트를 제공합니다. 기기와 앱은 요청 AWS IoT 처리 방식에 대한 정보를 제공하는 요청 주제를 게시하기 전에 응답 주제를 구독해야 합니다. 자세한 내용은 디바이스 섀도우 MQTT 주제 및 디바이스 섀도우 REST API 단원을 참조하세요.

상태 요청 및 보고

AWS IoT 및 섀도우를 사용하여 IoT 솔루션을 설계할 때는 변경을 요청할 앱 또는 장치와 이를 구현할 앱 또는 장치를 결정해야 합니다. 일반적으로 디바이스는 변경 사항을 구현하고 섀도우에 다시 보고하며, 앱과 서비스는 섀도우에 응답하고 변경을 요청합니다. 솔루션은 다를 수 있지만 이 주제의 예에서는 클라이언트 앱 또는 서비스가 섀도우의 변경을 요청하고 디바이스가 변경을 수행하며 이를 섀도우에 다시 보고한다고 가정합니다.

섀도우 업데이트

앱이나 서비스는 UpdateThingShadow API를 사용하거나 /update 주제에 게시하여 섀도우의 상태를 업데이트할 수 있습니다. 업데이트는 요청에 지정된 필드에만 영향을 미칩니다.

클라이언트가 상태 변경을 요청할 때 섀도우 업데이트

클라이언트가 MQTT 프로토콜을 사용하여 섀도우의 상태 변경을 요청하는 경우

  1. 클라이언트가 변경할 속성을 식별할 수 있도록 현재 섀도우 문서가 있어야 합니다. 현재 섀도우 문서를 가져오는 방법은 /get 작업을 참조하세요.

  2. 클라이언트는 다음 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

  3. 클라이언트는 원하는 섀도우 상태를 포함하는 상태 문서와 함께 $aws/things/thingName/shadow/name/shadowName/update 요청 주제를 게시합니다. 변경할 속성만 문서에 포함시켜야 합니다. 다음은 원하는 상태의 문서에 대한 예입니다.

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. 업데이트 요청이 유효하면 섀도우에서 원하는 상태를 AWS IoT 업데이트하고 다음 주제에 대한 메시지를 게시합니다.

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    /update/accepted 메시지에는 /accepted response state document 섀도우 문서가 포함되어 있으며 /update/delta 메시지에는 /delta response state document 섀도우 문서가 포함되어 있습니다.

  5. 업데이트 요청이 유효하지 않은 경우 오류를 설명하는 오류 응답 문서 섀도우 문서와 함께 $aws/things/thingName/shadow/name/shadowName/update/rejected 주제가 포함된 메시지를 AWS IoT 게시합니다.

클라이언트가 API를 사용하여 섀도우에서 상태 변경을 요청하는 경우

  1. 클라이언트는 요청 상태 문서 상태 문서를 메시지 본문으로 사용하여 UpdateThingShadow API를 호출합니다.

  2. 요청이 유효하면 HTTP 성공 응답 코드와 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 AWS IoT 반환합니다.

    AWS IoT 또한 구독하는 모든 장치 또는 클라이언트를 위해 /delta response state document 섀도우 문서와 함께 MQTT 메시지를 $aws/things/thingName/shadow/name/shadowName/update/delta 주제에 게시합니다.

  3. 요청이 유효하지 않은 경우 HTTP 오류 응답 코드 a를 응답 메시지 오류 응답 문서 본문으로 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

  2. 디바이스는 이 예에서와 같이 현재 상태를 보고하는 $aws/things/thingName/shadow/name/shadowName/update 주제에 메시지를 게시하여 현재 상태를 보고합니다.

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. 업데이트를 AWS IoT 수락하면 /accepted response state document 섀도우 문서와 함께 $aws/things/thingName/shadow/name/shadowName/update/accepted 주제에 메시지를 게시합니다.

  4. 업데이트 요청이 유효하지 않은 경우 오류를 설명하는 오류 응답 문서 섀도우 문서와 함께 $aws/things/thingName/shadow/name/shadowName/update/rejected 주제 메시지를 AWS IoT 게시합니다.

디바이스가 API를 사용하여 섀도우에 현재 상태를 보고하는 경우

  1. 디바이스는 요청 상태 문서 상태 문서를 메시지 본문으로 사용하여 UpdateThingShadow API를 호출합니다.

  2. 요청이 유효하면 섀도우를 AWS IoT 업데이트하고 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 포함하는 HTTP 성공 응답 코드를 반환합니다.

    AWS IoT 또한 구독하는 모든 장치 또는 클라이언트를 위해 /delta response state document 섀도우 문서와 함께 MQTT 메시지를 $aws/things/thingName/shadow/name/shadowName/update/delta 주제에 게시합니다.

  3. 요청이 유효하지 않은 경우 HTTP 오류 응답 코드 a를 응답 메시지 오류 응답 문서 본문으로 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 API를 사용하거나 /get 주제에 대해 구독 및 게시하여 섀도우 문서를 검색할 수 있습니다. 그러면 desired 및 reported 상태 사이의 델타를 포함하여 전체 섀도우 문서가 검색됩니다. 이 작업의 절차는 요청하는 주체가 디바이스인지 클라이언트인지에 관계없이 동일합니다.

MQTT 프로토콜을 사용하여 섀도우 문서를 검색하려면

  1. 디바이스 또는 클라이언트는 섀도우를 업데이트하기 전에 다음 MQTT 주제를 구독해야 합니다.

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. 디바이스나 클라이언트는 메시지 본문이 비어 있는 메시지를 $aws/things/thingName/shadow/name/shadowName/get 주제에 게시합니다.

  3. 요청이 성공하면 메시지 본문에 a를 포함하여 메시지를 $aws/things/thingName/shadow/name/shadowName/get/accepted 주제에 AWS IoT 게시합니다. /accepted response state document

  4. 요청이 유효하지 않은 경우 메시지 AWS IoT 본문에 a를 포함하여 $aws/things/thingName/shadow/name/shadowName/get/rejected 주제에 메시지를 게시합니다. 오류 응답 문서

REST API를 사용하여 섀도우 문서를 검색하려면

  1. 디바이스 또는 클라이언트는 빈 메시지 본문을 사용하여 GetThingShadow API를 호출합니다.

  2. 요청이 유효하면 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 포함하는 HTTP 성공 응답 코드를 AWS IoT 반환합니다.

  3. 요청이 유효하지 않은 경우 HTTP 오류 응답 코드 a를 응답 메시지 오류 응답 문서 본문으로 AWS IoT 반환합니다.

섀도우 데이터 삭제

섀도우 데이터를 삭제하는 방법에는 두 가지가 있습니다. 섀도우 문서에서 특정 속성을 삭제하거나 섀도우를 완전히 삭제할 수 있습니다.

  • 섀도우에서 특정 속성을 삭제하려면 삭제할 속성의 값을 null로 설정하여 섀도우를 업데이트합니다. 섀도우 문서에서 값이 null인 필드가 제거됩니다.

  • 전체 섀도우를 삭제하려면 DeleteThingShadow API를 사용하거나 /delete 주제에 게시합니다.

참고

섀도우를 삭제해도 버전 번호가 한 번에 0으로 재설정되지는 않습니다. 48시간 후에 0으로 재설정됩니다.

섀도우 문서에서 속성 삭제

MQTT 프로토콜을 사용하여 섀도우에서 속성을 삭제하려면

  1. 디바이스 또는 클라이언트가 변경할 속성을 식별할 수 있도록 현재 섀도우 문서가 있어야 합니다. 현재 섀도우 문서를 가져오는 방법은 섀도우 문서 검색 단원을 참조하세요.

  2. 디바이스 또는 클라이언트는 다음 MQTT 주제를 구독합니다.

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. 디바이스나 클라이언트는 삭제할 섀도우 속성에 null 값을 할당하는 상태 문서와 함께 $aws/things/thingName/shadow/name/shadowName/update 요청 주제를 게시합니다. 변경할 속성만 문서에 포함시켜야 합니다. 다음은 engine 속성을 삭제하는 문서의 예입니다.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. 업데이트 요청이 유효하면 섀도우에서 지정된 속성을 AWS IoT 삭제하고 메시지 본문에 /accepted response state document 섀도우 문서가 포함된 $aws/things/thingName/shadow/name/shadowName/update/accepted 주제가 포함된 메시지를 게시합니다.

  5. 업데이트 요청이 유효하지 않은 경우 오류를 설명하는 오류 응답 문서 섀도우 문서가 포함된 $aws/things/thingName/shadow/name/shadowName/update/rejected 주제와 함께 메시지를 AWS IoT 게시합니다.

REST API를 사용하여 섀도우에서 속성을 삭제하려면

  1. 디바이스 또는 클라이언트는 삭제할 섀도우의 속성에 null 값을 할당하는 요청 상태 문서을 사용하여 UpdateThingShadow API를 호출합니다. 문서에서 삭제할 속성만 포함합니다. 다음은 engine 속성을 삭제하는 문서의 예입니다.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. 요청이 유효하면 HTTP 성공 응답 코드와 /accepted response state document 섀도우 문서를 응답 메시지 본문으로 AWS IoT 반환합니다.

  3. 요청이 유효하지 않은 경우 HTTP 오류 응답 코드 a를 응답 메시지 오류 응답 문서 본문으로 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

  2. 디바이스 또는 클라이언트는 빈 메시지 버퍼를 사용하여 $aws/things/thingName/shadow/name/shadowName/delete를 게시합니다.

  3. 삭제 요청이 유효하면 섀도우를 AWS IoT 삭제하고 메시지 본문에 $aws/things/thingName/shadow/name/shadowName/delete/accepted 주제 및 축약된 /accepted response state document 섀도우 문서가 포함된 메시지를 게시합니다. 다음은 수락된 삭제 메시지의 예입니다.

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. 업데이트 요청이 유효하지 않은 경우 오류를 설명하는 오류 응답 문서 섀도우 문서와 함께 $aws/things/thingName/shadow/name/shadowName/delete/rejected 주제가 포함된 메시지를 AWS IoT 게시합니다.

REST API를 사용하여 섀도우를 삭제하려면

  1. 디바이스 또는 클라이언트는 빈 메시지 버퍼를 사용하여 DeleteThingShadow API를 호출합니다.

  2. 요청이 유효하면 HTTP 성공 응답 코드와 함께 메시지 본문의 섀도우 문서 /accepted response state document 및 축약된 /accepted response state document 섀도우 문서를 AWS IoT 반환합니다. 다음은 수락된 삭제 메시지의 예입니다.

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. 요청이 유효하지 않은 경우 HTTP 오류 응답 코드 an을 응답 메시지 오류 응답 문서 본문으로 AWS IoT 반환합니다.