156. (Aws/Amazon) [Aws Iot Core] Aws Iot Core Thing 사물 Shadow 업데이트 요청 UpdateThingShadow API 설명 정리

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

 

---

[설명 정리]

​

// --------------------------------------------------------------------------------------
[개발 및 환경]
// --------------------------------------------------------------------------------------

- 인프라 : Aws / Amazon Web Services


- 기술 구분 : Aws / Aws Iot Core / MQTT


- 사전) Aws Iot Core 간단 설명 : 

  >> AWS IoT 는 IoT 디바이스를 다른 디바이스 및 AWS 클라우드 서비스에 연결하는 클라우드 서비스를 제공합니다.

  >> 디바이스가에 연결할 수 있는 경우 AWS IoT는 AWS 가 제공하는 클라우드 서비스에 디바이스를 AWS IoT 연결할 수 있습니다.

  >> AWS IoT Core 메시지 브로커는 MQTT 및 MQTT over WSS 프로토콜을 사용하여 메시지를 게시하고 구독하는 디바이스 및 클라이언트를 지원합니다. 
  
    - HTTPS 프로토콜을 사용하여 메시지를 게시하는 디바이스와 클라이언트도 지원합니다.


- 사전) MQTT (Message Queuing Telemetry Transport) 간단 설명 : 

  >> MQTT 는 경량 메시지 프로토콜로, 주로 IoT(사물인터넷) 환경에서 사용됩니다

  >> MQTT 목적 : 제한된 네트워크 환경(저속, 불안정)에서 효율적으로 메시지를 주고받기 위해 설계

  >> MQTT 기반 : TCP/IP 위에서 동작

  >> MQTT 패턴 : Publish/Subscribe 모델을 사용

    - Publisher : 메시지를 발행하는 클라이언트

    - Subscriber : 특정 주제(topic)를 구독하는 클라이언트

    - Broker: 메시지를 중개하는 서버 (예: Mosquitto)

  >> MQTT 주요 특징 : 

    - 경량성 : 헤더가 매우 작음(2바이트부터 시작)

    - QoS (Quality of Service) : 
      $ QoS 0: 최대 한 번 전달(보장 없음)
      $ QoS 1: 최소 한 번 전달(중복 가능)
      $ QoS 2: 정확히 한 번 전달(가장 안전)

    - 지속 연결 : KeepAlive로 연결 상태 유지

    - Last Will and Testament (LWT) : 클라이언트 비정상 종료 시 브로커가 메시지 발행

    - 토픽 기반 라우팅 : 계층적 구조(/home/temperature 등)

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[설 명]
// --------------------------------------------------------------------------------------

1. AWS IoT UpdateThingShadow 는 지정한 Thing (사물) 의 디바이스 섀도우 (Device Shadow) 상태 정보를 생성 또는 갱신 (update) 하는 REST API입니다

  >> AWS 사이트 : https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html


2. AWS IoT UpdateThingShadow API 를 통해 디바이스 또는 애플리케이션이 현재 상태를 보내 섀도우 문서를 업데이트하거나 새로운 섀도우를 생성할 수 있게 합니다

  >> 디바이스 섀도우는 AWS IoT가 사물의 상태 정보를 JSON 문서로 저장하는 기능이며, 이를 통해 클라우드와 실제 디바이스 상태를 동기화할 수 있습니다


3. AWS IoT UpdateThingShadow API 요청 형식 및 주요 매개변수

  >> POST /things/thingName/shadow?name=shadowName HTTP/1.1

  >> thingName (경로 매개변수, 필수) : 업데이트할 Thing(사물)의 이름입니다 (최대 128자, [a-zA-Z0-9:_-]+ 패턴을 따릅니다)

  >> shadowName (쿼리 매개변수, 선택) : 명명된(named) 섀도우를 사용하는 경우 지정합니다 (최대 64자, [$a-zA-Z0-9:_-]+ 패턴을 따릅니다)

  >> 요청 본문 (payload) : JSON 형식 섀도우 상태 문서입니다. state 객체를 포함하여, desired 및/또는 reported 상태를 지정할 수 있습니다.

    {
      "state": {
        "desired": {
          "temperature": 22,
          "mode": "cool"
        }
      }
    }


4. AWS IoT UpdateThingShadow 응답 본문 예시 구문   

  >> HTTP/1.1 200
     payload

  >> 성공하면 HTTP 200 상태 코드와 함께 JSON 형태의 최신 섀도우 문서(payload) 를 응답 본문으로 반환합니다

  >> 에러 상황 : 

    - ConflictException : 요청에 포함된 버전(version) 이 현재 섀도우 문서의 버전과 일치하지 않을 때 발생 (버전 충돌)

    - InvalidRequestException : 요청 형식이나 내용이 유효하지 않을 때

    - RequestEntityTooLargeException : 페이로드 크기가 허용 최대를 초과했을 때

    - UnauthorizedException : 해당 작업에 대한 권한이 없을 때

    - ThrottlingException : 요청 속도 제한 초과

    - ServiceUnavailableException : 서비스가 일시적으로 이용 불가일 때

    - InternalFailureException : 내부 서버 오류

    - MethodNotAllowedException : HTTP 메서드/URI 조합이 지원되지 않을 때

    - UnsupportedDocumentEncodingException : 요청 문서 인코딩이 지원되지 않을 때


5. AWS IoT UpdateThingShadow 사용 자바스크립트 예시 코드 :

  <script src="https://sdk.amazonaws.com/js/aws-sdk-2.1416.0.min.js"></script>
  <script src="https://unpkg.com/aws-iot-device-sdk/browser/aws-iot-sdk-browser-bundle.js"></script>


  <script>

  // ---------------------------------------------------

  const region = 'ap-northeast-2'; // [AWS 리전]

  const endPoint = 'a1..km-ats.iot.ap-northeast-2.amazonaws.com'; // [AWS Iot Core 엔드포인트]
  const accessKey = 'AK..A6'; // [IAM 액세스 키]
  const secretKey = 'mP..5J'; // [IAM 시크릿 키]

  const thingName = 'TWOK_0000000001'; // [사물 명칭]
  const shadowName = 'control'; // [Shadow 명칭]

  // ---------------------------------------------------

  window.onload = async function() {

    // -----------------------------------------
    // [AWS.config 지정]
    // -----------------------------------------
    AWS.config.update({              
      accessKeyId: accessKeyId,
      secretAccessKey: secretAccessKey
    });


    // -----------------------------------------
    // [AWS.IotData 객체 생성]
    // -----------------------------------------
    const awsClient = new AWS.IotData({
      endpoint: endPoint,
      region: region
    });


    // -----------------------------------------
    // [Publish 수행 Json 페이로드 생성]
    // -----------------------------------------
    const params = {              
      thingName: thingName, 
      shadowName: shadowName, 
      payload: JSON.stringify({ // Publish 요청 JSON 페이로드 정의
        state: {
          desired: { // Client Publish 페이로드 작성
            color: 'blue' // Key : color / Value : blue
          }
        }
      })
    }; 


    // -----------------------------------------
    // [updateThingShadow 사용해 publish 요청 수행]
    // -----------------------------------------
    awsClient.updateThingShadow(params, (err, data) => {
      if (err) {
        console.error("[updateThingShadow] : [Error] : ", err);

      } else {
        console.log("[updateThingShadow] : [Success]");
      }

    });

  };

  // ---------------------------------------------------

  </script>

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[참고 사이트]
// --------------------------------------------------------------------------------------

MQTT (Message Queueing Telemetry Transport) 통신 설명

https://kkh0977.tistory.com/3631

https://blog.naver.com/kkh0977/222971771381?trackingCode=blog_bloghome_searchlist


[투케이 학습] : AWS IoT Shadow (섀도우) 개념 학습

https://blog.naver.com/kkh0977/223144838475?trackingCode=blog_bloghome_searchlist


자바스크립트 AWS Iot Core 특정 Thing 사물에 publish 메시지 전송 수행 - updateThingShadow

https://blog.naver.com/kkh0977/224009266181?trackingCode=blog_bloghome_searchlist


자바스크립트 aws4fetch 사용해 AWS4Signer 헤더 생성 및 UpdateThingShadow 사물 Shadow 생성 및 업데이트 요청

https://blog.naver.com/kkh0977/224069737149?trackingCode=blog_bloghome_searchlist

// --------------------------------------------------------------------------------------

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/3631

150. [IT 기술] MQTT (Message Queueing Telemetry Transport) 통신 설명

---