154. (Aws/Amazon) [Aws Iot Core] Aws Iot Core Thing 사물 Shadow 상태 정보 조회 GetThingShadow 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 GetThingShadow 는 IoT Thing (사물) 에 대한 Device Shadow (디바이스 섀도우) 상태 정보를 조회(get) 하는 REST API입니다

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


2. AWS IoT GetThingShadow API 는 실제 디바이스의 상태 (reported) 와 사용자가 원하는 상태 (desired) 정보 JSON 문서를 조회할 수 있습니다

  >> GetThingShadow API 를 호출하면 해당 Thing의 최신 섀도우 상태 JSON을 반환합니다. 즉, 디바이스의 마지막 상태 정보를 받아올 수 있습니다.


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

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

  >> thingName (Path) : Thing(사물)의 이름입니다. 필수 입력입니다

  >> shadowName (Query String, 선택) : 명명된 이름의 섀도우를 조회할 때 사용합니다.


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

  >> HTTP/1.1 200
     
     {
      "state": {
        "desired": { ... },
        "reported": { ... },
        "delta": { ... }
      },
      "metadata": { ... },
      "version": 15,
      "timestamp": 1690000000
    }

  >> 에러 상황 : 

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

    - 401 : UnauthorizedException : 권한 부족

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

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

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

    - 429 : ThrottlingException : 요청 제한 초과

    - 500 : InternalFailureException : 서버 내부 오류

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


5. AWS IoT GetThingShadow 사용 파이썬 예시 코드 :

# [AWS IAM 계정 AccessKey, SecretKey 변수 선언]
iamAccessKey = "AK..A6"
iamSecretKey = "mP..5J"
iamRegion = "ap-northeast-2"  # 리전

# [Aws Iot Core 엔드포인트 정보 지정]
endpoint = 'a1..km-ats.iot.ap-northeast-2.amazonaws.com'

# [thing_name 사물 명칭 및 Shadow 지정] 
thing_name = 'T_TWOK_0000000001'
shadow = 'common'


# [Http 호출 정보 생성]
host = endpoint

# DescribeThing: GET /things/{thingName}
path = f"/things/{quote(thing_name, safe='')}/shadow?name={quote(shadow, safe='')}"

url = f"https://{host}{path}"


# [AWSRequest 객체 생성]
req = AWSRequest(method='GET', url=url)


# [SigV4 서명 정보 추가]    
auth = SigV4Auth(
  credentials=botocore.credentials.Credentials(
      iamAccessKey, iamSecretKey
  ),
  service_name='iotdevicegateway', # ✅ IoT Data Plane API (예: GetThingShadow, MQTT 연결, Shadow REST API) 는 서비스 이름 iotdevicegateway 입니다
  region_name=iamRegion
)
auth.add_auth(req)


# [req 정보 확인]
print(f"DLOG = Http Request : {req}")

prepared = req.prepare()


# ✅ [Http 요청 수행]      
conn = HTTPSConnection(host, timeout=10)
conn.request("GET", path, headers=dict(prepared.headers))
resp = conn.getresponse()
data = resp.read().decode()
conn.close()


# [resp 정보 확인]
print(f"DLOG = Http Response : {data}")

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






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

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 페이로드 JSON 조회 수행 - getThingShadow

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


[AWS] [Lambda] 런타임 Python 3.13 - boto3 모듈 사용해 SigV4Auth 서명 및 GetThingShadow 확인

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

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

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/3631

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

---