155. (Aws/Amazon) [Aws Iot Core] Aws Iot Core Thing 사물 Shadow 삭제 요청 DeleteThingShadow 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 DeleteThingShadow 는 지정된 IoT Thing (사물) 에 대한 Device Shadow (디바이스 섀도우) 문서를 삭제 (delete) 하는 REST API입니다

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


2. AWS IoT DeleteThingShadow API 를 호출하면 해당 사물의 섀도우 내용을 AWS IoT 에서 제거할 수 있습니다

  >> 디바이스 섀도우는 사물의 상태 정보를 JSON 문서로 저장한 것입니다

  >> DeleteThingShadow 호출 시 Thing 의 섀도우 문서를 영구적으로 삭제합니다 (한 번 삭제된 섀도우는 기본적으로 복원할 수 없습니다)


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

  >> DELETE /things/{thingName}/shadow?name={shadowName} HTTP/1.1

  >> thingName (Path) : 삭제하려는 Thing(사물)의 이름입니다. (최소 길이 1, 최대 128자, [a-zA-Z0-9:_-] 패턴이 허용됩니다)

  >> shadowName (Query String, 선택) : 이름이 지정된(separate named) shadow를 삭제할 때 사용합니다. (최소 길이 1, 최대 64자, [$a-zA-Z0-9:_-]+ 패턴이 허용됩니다)


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

  >> HTTP/1.1 200
     payload

  >> 보통 삭제된 문서를 나타내는 최소 정보만 포함됩니다.

  >> 에러 상황 : 

    - 400	: InvalidRequestException : 요청 형식이 잘못되었을 때

    - 401 : UnauthorizedException : 권한 부족

    - 404 ResourceNotFoundException : Thing 또는 Shadow가 존재하지 않을 때

    - 405 : MethodNotAllowedException : 잘못된 HTTP 메서드

    - 415 : UnsupportedDocumentEncodingException : 지원하지 않는 인코딩

    - 429 : ThrottlingException : 요청 제한 초과

    - 500 : InternalFailureException : 서버 내부 오류

    - 503 : ServiceUnavailableException : 서비스 이용 불가


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

  <script type="module">

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

  import aws4 from "https://esm.sh/aws4fetch@1.0.17";

  const { AwsClient } = aws4;

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

  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 시크릿 키]

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

  window.onload = async function() {

    // -----------------------------------------
    // [AwsClient 초기화 수행]
    // -----------------------------------------
    const aws = new AwsClient({
      accessKeyId: accessKey,
      secretAccessKey: secretKey,
      service: "iotdata",
      region: region,
    });


    // -----------------------------------------
    // [fetch API 요청 객체 초기화 수행]
    // -----------------------------------------
    // 참고 사이트 : https://docs.aws.amazon.com/ko_kr/iot/latest/apireference/API_iotdata_DeleteThingShadow.html
    // -----------------------------------------

    const thingName = "TWOK_0000000001";
    const shadowName = "network"; // named shadow가 아닐 경우 생략 가능

    const httpUrl = `https://${endPoint}/things/${thingName}/shadow?name=${shadowName}`;               


    // -----------------------------------------
    // [AbortController 사용해 Fetch 요청 타임 아웃 지정]
    // -----------------------------------------
    const controller = new AbortController();
    const timeoutId = setTimeout(() => {

        controller.abort(); // [Fetch >> catch 부분] : [AbortError: signal is aborted without reason]
        
    }, 15000); 


    // -----------------------------------------
    // [Fetch 요청 수행 실시]
    // -----------------------------------------
    aws.fetch(httpUrl, {
        method: "DELETE",
        signal: controller.signal // [AbortController]
    })
    .then((response) => {

        // [상태 코드 확인]
        if (!response.ok) {
            throw new Error("Http Status Error : " + response.status);
        }

        // [json 형식으로 리턴 반환 설정]
        return response.json(); 
    }) 
    .then((data) => {
        console.log("[Http] : [response] : [http 응답 데이터 확인] : ", JSON.stringify(data));

        // -----------------------------------------
        // [fetch API 응답 결과 확인]
        // -----------------------------------------
        /*
        {"version":1,"timestamp":1762773142}
        */
        // -----------------------------------------

    })
    .catch((error) => {
        console.error("[Http] : [error] : [http 에러 결과 확인] : ", error.message);
    });

  };

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

  </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


자바스크립트 aws4fetch 사용해 AWS4Signer 헤더 생성 및 DeleteThingShadow 특정 Shadow  섀도우 삭제 수행

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

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

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/3631

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

---