디바이스 섀도우 서비스 문서 - AWS IoT Core
섀도우 문서 예제문서 속성델타 상태섀도우 문서 버전 관리섀도우 문서의 클라이언트 토큰빈 섀도우 문서 속성섀도우 문서의 배열 값

디바이스 섀도우 서비스 문서

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

섀도우 문서 예제

디바이스 섀도우 서비스는 REST API 또는 MQTT Pub/Sub 메시지를 사용한 UPDATE, GET 및 DELETE 작업에서 다음 문서를 사용합니다.

요청 상태 문서

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

{
    "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 — 사용할 경우, 디바이스 섀도우 서비스는 지정된 버전이 서비스가 보유하는 최신 버전과 일치하는 경우에만 업데이트를 처리합니다.

응답 상태 문서

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

/accepted response state document

{
    "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

{
    "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

{
  "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"
}

응답 상태 문서 속성

  • previous — 성공적으로 업데이트되면 업데이트 전 객체의 state를 포함합니다.

  • current — 성공적으로 업데이트되면 업데이트 후 객체의 state를 포함합니다.

  • state

    • reported — 사물이 reported 섹션의 데이터를 보고하고 요청 상태 문서에 있는 필드만 포함하는 경우에만 존재합니다.

    • desired — 디바이스가 desired 섹션의 데이터를 보고하고 요청 상태 문서에 있는 필드만 포함하는 경우에만 존재합니다.

    • delta — desired 데이터가 섀도우의 현재 reported 데이터와 다른 경우에만 존재합니다.

  • metadata — 언제 상태가 업데이트되었는지 확인할 수 있도록 desired 및 reported 섹션의 각 속성에 대한 타임스탬프를 포함합니다.

  • timestamp — AWS IoT에 의해 응답이 생성된 epoch 기준 날짜 및 시간입니다.

  • clientToken — 유효한 JSON을 /update 주제에 게시할 때 클라이언트 토큰이 사용된 경우에만 존재합니다.

  • version — AWS IoT에서 공유되는 디바이스 섀도우에 대한 문서의 현재 버전입니다. 현재 버전은 이전 문서 버전보다 1이 증가합니다.

오류 응답 문서

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

{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

  • code — 오류 유형을 나타내는 HTTP 응답 코드입니다.

  • message — 추가 정보를 제공하는 텍스트 메시지입니다.

  • timestamp — AWS IoT에 의해 응답이 생성된 날짜 및 시간입니다. 이 속성은 모든 오류 응답 문서에 존재하지 않습니다.

  • clientToken — 게시된 메시지에 클라이언트 토큰이 사용된 경우에만 존재합니다.

자세한 내용은 디바이스 섀도우 오류 메시지 단원을 참조하세요.

섀도우 이름 목록 응답 문서

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

{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}

  • results — 섀도우 이름의 배열입니다.

  • nextToken — 시퀀스의 다음 페이지를 가져오기 위해 페이징된 요청에 사용할 토큰 값입니다. 반환할 섀도우 이름이 더 이상 없는 경우에는 이 속성이 존재하지 않습니다.

  • timestamp — AWS IoT에 의해 응답이 생성된 날짜 및 시간입니다.

문서 속성

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

state
desired

디바이스의 원하는 상태입니다. 앱은 문서의 이 부분에 기록하여, 디바이스와 연결할 필요 없이 디바이스의 상태를 직접 업데이트할 수 있습니다.

reported

디바이스의 보고된 상태입니다. 디바이스는 문서의 이 부분을 기록하여 새 상태를 보고합니다. 앱은 문서의 이 부분을 읽어 디바이스의 마지막 보고 상태를 확인합니다.

metadata

문서의 state 섹션에 저장된 데이터에 대한 정보입니다. 여기에는 state 섹션의 각 속성에 대한 Epoch 시간 형식의 타임스탬프가 포함되는데, 이를 통해 각 속성이 업데이트된 시간을 알 수 있습니다.

참고

메타데이터는 서비스 제한 또는 요금에 대한 문서 크기에 도움이 되지 않습니다. 자세한 내용은 AWS IoT 서비스 한도 단원을 참조하세요.

timestamp

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

clientToken

MQTT 환경에서 응답을 요청에 연결할 수 있는 디바이스 고유 문자열입니다.

version

문서 버전입니다. 문서가 업데이트될 때마다 이 버전 번호가 증가합니다. 업데이트되는 문서의 버전이 최신인지 확인하는 데 사용됩니다.

자세한 내용은 섀도우 문서 예제 단원을 참조하세요.

델타 상태

델타 상태는 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 섹션의 배열과 일치하지 않을 경우 원하는 배열 전체가 델타로 복사됩니다.

섀도우 문서 버전 관리

디바이스 섀도우 서비스는 요청과 응답의 모든 업데이트 메시지에 대한 버전 관리를 지원합니다. 즉, 섀도우가 업데이트될 때마다 JSON 문서의 버전이 증가합니다. 이를 통해 2가지가 보장됩니다.

  • 클라이언트가 구 버전을 사용하여 섀도우를 덮어쓰려 할 경우 오류 응답을 받을 수 있습니다. 클라이언트에 디바이스 섀도우를 업데이트하기 전에 재동기화해야 한다는 알림이 제공됩니다.

  • 수신된 메시지가 클라이언트에 저장된 것보다 낮은 버전일 경우 클라이언트는 메시지에 대한 작업을 수행하지 않기로 결정할 수 있습니다.

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

섀도우 문서의 클라이언트 토큰

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

참고

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

빈 섀도우 문서 속성

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

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

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

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

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

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

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

{
}

섀도우 문서의 배열 값

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

Initial state:

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

업데이트:

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

최종 상태:

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

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

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