157. (Aws/Amazon) [Aws Iot Core] Aws Iot Core 사물에 생성된 Shadow 목록 조회 ListNamedShadowsForThing 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 ListNamedShadowsForThing 는 AWS IoT Core의 디바이스 섀도우 (Device Shadow) API 중 하나로, 특정 IoT Thing (사물) 에 대해 명명된 섀도우 (Named Shadow) 들의 이름 목록을 반환합니다

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


2. AWS IoT ListNamedShadowsForThing API 를 통해 특정 사물 Thing 에 어떤 섀도우들이 있는지 리스트로 확인할 수 있습니다


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

  >> GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize HTTP/1.1

  >> thingName : 목록을 조회하려는 Thing(사물)의 이름 (필수)

  >> nextToken : 페이징된 결과에서 다음 페이지를 받기 위한 토큰 (선택)

  >> pageSize : 한 번에 반환할 섀도우 이름 최대 개수 (선택, 1–100)


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

  >> HTTP/1.1 200
    Content-type: application/json

    {
      "nextToken": "string",
      "results": [ "string" ],
      "timestamp": number
    }

  >> results : Named Shadow 이름들의 배열 (문자열 리스트)

  >> nextToken : 다음 결과 페이지를 요청할 때 사용할 토큰 (null이면 끝)

    - 만약 Thing에 많은 Named Shadow가 있는 경우, nextToken을 이용해 이어서 조회할 수 있습니다

  >> timestamp : 응답이 생성된 시각 (Epoch 기준)

  >> 예시 응답 JSON : 

  {
    "results": ["shadow1", "shadow2"],
    "nextToken": "eyJ2IjoiMSJ9...",
    "timestamp": 169XXXXXXX
  }


5. AWS IoT ListNamedShadowsForThing 응답 에러 코드 정리 : 

  >> 400 : InvalidRequestException : 요청 형식이 잘못됨

  >> 401 : UnauthorizedException : 권한 없음

  >> 404 : ResourceNotFoundException : Thing이 존재하지 않음

  >> 429 : ThrottlingException : 요청 제한 초과

  >> 500 : InternalFailureException : 내부 서버 오류

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


6. AWS IoT ListNamedShadowsForThing 를 호출하기 위한 주의사항 : 

  >> ListNamedShadowsForThing API를 호출하려면 AWS IAM 정책에서 iot:ListNamedShadowsForThing 액션에 대한 허용 권한이 필요합니다

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": "iot:ListNamedShadowsForThing",
        "Resource": "arn:aws:iot:us-east-1:123456789012:thing/MyThing"
      }
    ]
  }


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

  <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 endPoint = 'a1..km-ats.iot.ap-northeast-2.amazonaws.com'; // [AWS Iot Core 엔드포인트]
  const region = 'ap-northeast-2'; // [AWS 리전]
  const accessKeyId = 'AK..A6'; // [IAM 액세스 키]
  const secretAccessKey = 'mP..5J'; // [IAM 시크릿 키]
  const thingName = 'TOWK123'; // [사물 명칭]

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

  window.onload = async function() {

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


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


    // -----------------------------------------
    // [listNamedShadowsForThing 요청 params 생성]

    // -----------------------------------------
    const params = {              
      thingName: thingName,
      pageSize: 100   // 👈 한 번에 100개 가져오기 (1~100까지 설정 가능)
      //, nextToken: nextToken // 다음 페이지 토큰
    }; 


    // -----------------------------------------
    // [listNamedShadowsForThing 사용해 특정 Thing 에 생성 된 Shadow 리스트 조회]
    // -----------------------------------------
    awsClient.listNamedShadowsForThing(params, (err, data) => {
      if (err) {
        console.error("[listNamedShadowsForThing] : [Error] : ", err);

      } else {
        console.log("[listNamedShadowsForThing] : [Success] : ", JSON.stringify(data));

        // -----------------------------------------
        // results Shadow 리스트 파싱
        // -----------------------------------------
        // {"results":["firmware","control"],"timestamp":1761455875}
        // -----------------------------------------
        const results = data.results;

      }

    });

  };

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

  </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 사물에 생성 된 Shadow 목록 리스트 조회 - listNamedShadowsForThing

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


[Aws Iot Core] 하나의 Thing 사물에 생성 가능 한 Named Shadow 개수 정리 - ListNamedShadowsForThing

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

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

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/3631

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

---