186. (Aws/Amazon) [Aws Iot Core] AWS 특정 룰엔진 rule 상세 정보 조회 GetTopicRule API 설명 정리

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

 

---

[설명 정리]

​

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

- 인프라 : Aws / Amazon Web Services


- 기술 구분 : Aws / Aws Iot Core / Rules / 룰엔진 / GetTopicRule


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

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

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

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


- 사전) Aws Rule Engine 간략 설명 : 

  >> Rule Engine (룰 엔진) 이란 Aws Iot Core MQTT 메시지를 실시간으로 분석하고, 이를 기반으로 AWS 다양한 서비스와 연동할 수 있는 기능입니다

  >> 룰 엔진에서는 MQTT 메시지를 분석해 AWS 다른 서비스를 호출 하도록 라우팅 처리를 수행합니다

  >> Rule Engine (룰 엔진) 주요 기능 :

    - AWS 서비스 연동 : AWS 다양한 서비스는 DynamoDB, S3, Lambda, SNS, SQS, Kinesis 등으로 데이터 전송

    - 멀티 액션 지원 : 하나의 규칙에서 여러개의 액션을 동시에 실행

    - 메시지 필터링 및 변환 : SQL 기반의 Query 쿼리 언어를 사용하여 데이터 필터링 및 변환

    - 데이터 프로세싱 : JSON 형식의 데이터를 분석하고 변환 및 활용

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






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

1. GetTopicRule 는 AWS IoT Core 의 룰 엔진 (Rules Engine) 에서 특정 룰 (rule) 의 상세 정보를 조회하는 공식 API 입니다.

  >> 특정 룰에 대한 정보를 가져오는 API 입니다


2. GetTopicRule 호출을 통해 해당 룰의 SQL, 액션(actions), 에러 액션, 설명, 생성시간, 활성화 여부 등을 모두 확인할 수 있습니다.


3. GetTopicRule 가 사용 되는 상황 : 

  >> 룰 엔진 SQL을 읽어오고 싶을 때

  >> 룰이 어떤 AWS 서비스(Lambda, DynamoDB, S3, SNS 등)와 연결되어 있는지 알고 싶을 때

  >> 룰이 비활성화되어 있는지 확인할 때

  >> 자동화 시스템에서 현재 룰 구성을 프로그램으로 읽어올 때

  >> 개발/운영에서 룰 구성 변경 전 후 비교할 때


4. ✅ GetTopicRule 호출 시 요청 전문

  >> GET /rules/ruleName HTTP/1.1

  >> ruleName 은 IoT 콘솔에서 보이는 룰 이름입니다.


5. ✅ GetTopicRule 응답 전문

  >> GetTopicRule 응답 JSON 예시 : 

    {
      "ruleArn": "arn:aws:iot:us-west-2:123456789012:rule/MyTestRule",
      "rule": {
        "ruleName": "MyTestRule",
        "sql": "SELECT * FROM 'devices/+/data' WHERE temperature > 30",
        "description": "High temperature rule",
        "createdAt": "2025-07-08T19:56:00Z",
        "actions": [
          {
            "lambda": {
              "functionArn": "arn:aws:lambda:us-west-2:123456789012:function:HighTempHandler"
            }
          },
          {
            "sns": {
              "targetArn": "arn:aws:sns:us-west-2:123456789012:HighTempTopic",
              "roleArn": "arn:aws:iam::123456789012:role/SNSTopicRole",
              "messageFormat": "RAW"
            }
          }
        ],
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "errorAction": {
          "sqs": {
            "roleArn": "arn:aws:iam::123456789012:role/SQSRole",
            "queueUrl": "https://sqs.us-west-2.amazonaws.com/123456789012/RuleErrorQueue",
            "useBase64": false
          }
        }
      }
    }

  >> rule.ruleName : 룰 이름

  >> rule.sql : SQL 문(SELECT … FROM …)

  >> rule.actions : AWS 서비스 액션 목록 (Lambda/SNS/SQS/S3/Kinesis 등)

  >> rule.errorAction : 액션 실패 시 실행되는 에러 핸들링 액션

  >> rule.description : 룰 설명

  >> rule.createdAt : 룰 생성 시간

  >> rule.ruleDisabled : 룰 비활성 여부 (true면 비활성)

  >> rule.awsIotSqlVersion : SQL 문법 버전 (2016-03-23 등)

  >> ruleArn : 이 룰의 고유 ARN


6. ❌ GetTopicRule 호출 주요 에러 발생 코드 : 

  >> ResourceNotFoundException : 존재하지 않는 ruleName을 호출할 때 발생
                
  >> UnauthorizedException : 호출한 IAM 자격에 iot:GetTopicRule 권한이 없음
                
  >> ThrottlingException : 너무 많은 호출을 짧은 시간에 보냈을 때, IoT 제어 플레인 API는 초당 요청량 제한 존재
                
  >> InternalFailureException : AWS IoT 내부 오류
                
  >> InvalidRequestException : 잘못된 ruleName 형식
    

7. GetTopicRule 을 호출 하기 위한 필요 IAM 권한 : 

  >> iot:GetTopicRule


8. ✅ GetTopicRule 호출 자바스크립트 예시 소스 코드 : 

<script src="https://sdk.amazonaws.com/js/aws-sdk-2.1416.0.min.js"></script>

<script>

  // [AWS 인증 변수 선언]        
  const accessKey = 'AK..A6';
  const secretKey = 'mP..5J';
  const region = 'ap-northeast-2';


  window.onload = async function() {

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


    // -----------------------------------------
    // [AWS 객체 생성]
    // -----------------------------------------
    const aws = new AWS.Iot();


    // -----------------------------------------
    // [GetTopicRule 호출 수행]
    // ----------------------------------------- 
    // AWS 참고 사이트 : https://docs.aws.amazon.com/iot/latest/apireference/API_GetTopicRule.html
    // -----------------------------------------
    const param = { // ✅ Request_파라미터
      ruleName: ruleName
    };

    aws.getTopicRule( param , (err, data) => {
      if (err) console.error(err);
      else console.log(JSON.stringify(data));
    });

  };

</script>

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






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

[자바스크립트 AWS Iot Core 룰엔진 리스트 nextToken 사용해 전체 조회 수행 - listTopicRules]

https://kkh0977.tistory.com/8461

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


[Aws Iot Core] 메시지 라우팅 규칙 Rule Engine 룰 엔진 개념 학습

https://kkh0977.tistory.com/8130

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


[Aws Iot Core] Rule Engine 룰 엔진 생성 목록 확인 방법 - 메시지 라우팅 규칙 확인

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

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

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/8461

461. (javaScript) 자바스크립트 AWS Iot Core 룰엔진 리스트 nextToken 사용해 전체 조회 수행 - listTopicRules

---