기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS IoT SQL 참조
에서 AWS IoT규칙은 SQL과 유사한 구문을 사용하여 정의됩니다. SQL 문은 세 유형의 절로 구성됩니다.
**SET**
(선택 사항) SQL 문 및 대체 템플릿 전체에서 재사용할 수 있는 변수를 정의합니다. 표현식을 사용하여 변수에 값을 할당합니다. SELECT 및 WHERE 절과 작업 대체 템플릿에서 이러한 변수를 참조하세요.
SET 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md), [리터럴](iot-sql-literals.md)[Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [변수](iot-sql-set.md#iot-sql-set-usage) 및를 지원합니다[중첩된 객체 쿼리](iot-sql-nested-queries.md).
**SELECT**
(필수 사항) 수신 메시지 페이로드에서 정보를 추출하고 정보 변환을 수행합니다. 사용할 메시지는 FROM 절에서 지정한 [주제 필터](topics.md#topicfilters)에 의해 식별됩니다.
SELECT 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md)[리터럴](iot-sql-literals.md), [Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [대체 템플릿](iot-substitution-templates.md), [변수](iot-sql-set.md#iot-sql-set-usage), [중첩된 객체 쿼리](iot-sql-nested-queries.md)및를 지원합니다[이진 페이로드](binary-payloads.md).
**FROM**
데이터를 추출할 메시지를 식별하는 MQTT 메시지 [주제 필터](topics.md#topicfilters)입니다. 여기에 지정된 주제 필터와 일치하는 MQTT 주제로 전송된 각 메시지가 규칙을 활성화합니다. 메시지 브로커를 통과하는 메시지가 활성화하는 규칙에서는 필수입니다. [기본 수집](iot-basic-ingest.md) 기능을 사용해서만 활성화되는 규칙에서는 선택 사항입니다.
**WHERE**
(선택 사항) 규칙에서 지정된 작업이 수행되었는지 여부를 확인하는 조건부 논리를 추가합니다.
WHERE 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md), [리터럴](iot-sql-literals.md)[Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [변수](iot-sql-set.md#iot-sql-set-usage) 및를 지원합니다[중첩된 객체 쿼리](iot-sql-nested-queries.md).
다음은 SQL 문 예제입니다.
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
다음은 MQTT 메시지(수신 페이로드라고도 함) 예제입니다.
```
{
"color":"red",
"temperature":100
}
```
이 메시지가 `'topic/subtopic'` 주제에 게시될 경우 규칙이 트리거되고 SQL 문이 실행됩니다. `"temperature"` 속성이 50을 초과할 경우 SQL 문이 `color` 속성의 값을 추출합니다. WHERE 절은 조건 `temperature > 50`을 지정합니다. `AS` 키워드는 `"color"` 속성의 이름을 `"rgb"`로 변경합니다. 그 결과(*송신 페이로드*)는 다음과 같습니다.
```
{
"rgb":"red"
}
```
그런 다음 이 데이터가 규칙의 작업으로 전달되고, 작업이 추가 처리를 위해 데이터를 전송합니다. 규칙 작업에 대한 자세한 내용은 [AWS IoT 규칙 작업](iot-rule-actions.md) 섹션을 참조하세요.
**참고**
주석은 현재 AWS IoT SQL 구문에서 지원되지 않습니다.
공백이 포함된 속성 이름은 SQL 문에서 필드 이름으로 사용할 수 없습니다. 수신되는 페이로드는 공백이 있는 속성 이름을 가질 수 있지만 SQL 문에서는 이러한 이름을 사용할 수 없습니다. 그러나 와일드카드(\$1) 필드 이름 사양을 사용하는 경우 송신하는 페이로드로 전달됩니다.
# SELECT 절
AWS IoT SELECT 절은 기본적으로 ANSI SQL SELECT 절과 동일하지만 약간의 차이가 있습니다.
SELECT 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md)[리터럴](iot-sql-literals.md), [Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [변수](iot-sql-set.md#iot-sql-set-usage), [중첩된 객체 쿼리](iot-sql-nested-queries.md)및를 지원합니다[이진 페이로드](binary-payloads.md).
SELECT 절을 사용하여 수신 MQTT 메시지에서 정보를 추출할 수 있습니다. `SELECT *`를 사용하여 전체 수신 메시지 페이로드를 검색할 수도 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
페이로드가 JSON 객체일 경우 객체 내 키를 참조할 수 있습니다. 송신 페이로드에는 키-값 페어가 포함됩니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
AS 키워드를 사용하여 키 이름을 바꿀 수 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic':{"color":"red", "temperature":50}
SQL:SELECT color AS my_color FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red"}
```
쉼표로 구분하여 여러 항목을 선택할 수 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT color as my_color, temperature as fahrenheit FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red","fahrenheit":50}
```
'\$1'를 포함하여 여러 항목을 선택하여 수신 페이로드에 항목을 추가할 수 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT *, 15 as speed FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50, "speed":15}
```
`"VALUE"` 키워드를 사용하여 JSON 객체가 아닌 송신 페이로드를 생성할 수 있습니다. SQL 버전 `2015-10-08`에서는 한 항목만 선택할 수 있습니다. SQL 버전 `2016-03-23` 이상에서는 최상위 객체로 출력할 배열을 선택할 수도 있습니다.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
`'.'` 구문을 사용하여 수신 페이로드에서 중첩된 JSON 객체를 자세히 확인할 수 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}
SQL: SELECT color.red as red_value FROM 'topic/subtopic'
Outgoing payload: {"red_value":255}
```
숫자 또는 하이픈(-) 문자와 같은 예약된 문자가 포함된 JSON 객체 및 속성 이름을 사용하는 방법에 대한 자세한 내용은 [JSON 확장](iot-sql-json.md) 단원을 참조하세요.
함수([함수](iot-sql-functions.md) 섹션 참조)를 사용하여 수신 페이로드를 변환할 수 있습니다. 그룹화에 괄호를 사용할 수 있습니다. 다음 예를 참조하세요.
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT (temperature - 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'topic/subtopic'
Outgoing payload: {"celsius":10,"my_color":"RED"}
```
# FROM 절
FROM 절은 규칙이 [주제](topics.md#topicnames) 또는 [주제 필터](topics.md#topicfilters)를 구독하도록 지정합니다. 주제 또는 주제 필터를 작은따옴표(')로 묶으세요. 여기에 지정된 주제 필터와 일치하는 MQTT 주제로 전송된 각 메시지가 규칙을 트리거합니다. 주제 필터를 사용하여 비슷한 주제의 그룹을 구독할 수 있습니다.
**예:**
주제 `'topic/subtopic'`에 게시된 수신 페이로드: `{temperature: 50}`
주제 `'topic/subtopic-2'`에 게시된 수신 페이로드: `{temperature: 50}`
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`.
규칙이 `'topic/subtopic'`를 구독하므로 수신 페이로드가 규칙에 전달됩니다. 규칙 작업에 전달되는 송신 페이로드는 `{t: 50}`입니다. 규칙이 `'topic/subtopic-2'`를 구독하지 않으며, 따라서 `'topic/subtopic-2'`에 게시된 메시지가 규칙을 트리거하지 않습니다.
**\$1 와일드카드 예:**
'\$1'(다중 레벨) 와일드카드 문자를 사용하여 하나 이상의 특정 경로 요소와 일치시킬 수 있습니다.
주제 `'topic/subtopic'`에 게시된 수신 페이로드: `{temperature: 50}`
주제 `'topic/subtopic-2'`에 게시된 수신 페이로드: `{temperature: 60}`
주제 `'topic/subtopic-3/details'`에 게시된 수신 페이로드: `{temperature: 70}`
주제 `'topic-2/subtopic-x'`에 게시된 수신 페이로드: `{temperature: 80}`
SQL: `"SELECT temperature AS t FROM 'topic/#'"`.
규칙이 `'topic'`으로 시작하는 모든 주제를 구독하므로 세 번 실행되어 `{t: 50}`(topic/subtopic), `{t: 60}`(topic/subtopic-2) 및 `{t: 70}`(topic/subtopic-3/details)의 송신 페이로드를 해당 작업으로 전송합니다. 규칙이 `'topic-2/subtopic-x'`를 구독하지 않으며, 따라서 `{temperature: 80}` 메시지가 규칙을 트리거하지 않습니다.
**\$1 와일드카드 예:**
'\$1'(단일 레벨) 와일드카드 문자를 사용하여 어느 하나의 특정 경로 요소와 일치시킬 수 있습니다.
주제 `'topic/subtopic'`에 게시된 수신 페이로드: `{temperature: 50}`
주제 `'topic/subtopic-2'`에 게시된 수신 페이로드: `{temperature: 60}`
주제 `'topic/subtopic-3/details'`에 게시된 수신 페이로드: `{temperature: 70}`
주제 `'topic-2/subtopic-x'`에 게시된 수신 페이로드: `{temperature: 80}`
SQL: `"SELECT temperature AS t FROM 'topic/+'"`.
규칙이 첫 번째 요소가 `'topic'`인 2개의 경로 요소를 갖는 모든 주제를 구독합니다. 규칙은 `'topic/subtopic'` 및 `'topic/subtopic-2'`에 전송된 메시지에 대해 실행되지만, `'topic/subtopic-3/details'`(주제(topic) 필터보다 더 많은 레벨이 있음) 또는 `'topic-2/subtopic-x'`(`topic`으로 시작하지 않음)에 전송된 메시지에 대해서는 실행되지 않습니다.
# SET 절
SET 절을 사용하여 표현식 결과를 저장하는 변수를 정의합니다. SELECT 및 WHERE 절과 대체 템플릿에서 이러한 변수를 재사용할 수 있습니다. 이렇게 하면 복잡한 표현식을 복제하지 않고 SQL 문에서 함수 호출 수를 줄일 수 있습니다.
SET 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md), [리터럴](iot-sql-literals.md)[Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [변수](#iot-sql-set-usage) 및를 지원합니다[중첩된 객체 쿼리](iot-sql-nested-queries.md).
## SET 절 구문
SET 절은 SQL 문의 SELECT 절 앞에 나타나야 합니다. 다음 구문을 사용합니다.
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
구문 규칙:
+ 를 사용하여 변수 이름 시작 `@`
+ 변수 이름에는 문자, 숫자 및 밑줄이 포함될 수 있습니다.
+ 변수 이름은 최대 64자까지 가능합니다.
+ 쉼표로 구분된 단일 SET 절에서 여러 변수를 설정할 수 있습니다.
+ 각 변수는 한 번만 할당할 수 있습니다(변수는 변경할 수 없음).
+ SET 키워드는 SQL 문당 한 번만 사용할 수 있습니다.
## 변수 사용
변수를 정의한 후 다음에서 사용할 수 있습니다.
+ SELECT 절
+ WHERE 절
+ 기타 SET 변수 할당
+ 작업 대체 템플릿
+ 오류 작업 대체 템플릿
+ 중첩된 SELECT 쿼리
+ 함수 파라미터( roleArn 파라미터와 같은 특정 파라미터 및와 유사한 함수 모드를 전환하는 파라미터는 변수를 지원하지 `transform("enrichArray", attributes, values)` 않음)
변수는 `@variable_name` SET 절에 사용된 것과 동일한 구문을 사용하여 참조됩니다. JSON 확장 구문을 사용하여와 같이 객체가 포함된 변수의 속성에 액세스할 수도 있습니다`@variable_name.property`.
## SET 절 예제
**기본 변수 사용**
다음 예제는 주제에 게시된 페이로드를 보여줍니다`device/data`. `{"temp_fahrenheit": 75, "humidity": 60}`
SQL 문
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
발신 페이로드: `{"celsius": 23.89, "humidity": 60}`
**임베디드 JSON 객체의 멤버 액세스 **
다음 예제는 주제에 게시된 페이로드를 보여줍니다`device/data`. `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
SQL 문
```
SET @device_sensor_data = device1.deviceData.sensors
SELECT @device_sensor_data.temp_fahrenheit AS temp_fahrenheit, @device_sensor_data.humidity as humidity, device1.deviceId as deviceId FROM 'device/data'
```
발신 페이로드: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
JSON 확장을 사용하는 방법에 대한 자세한 내용은 섹션을 참조하세요. [JSON 확장](iot-sql-json.md)
**중복 함수 호출 방지**
SET 변수는 복잡한 디코딩 작업의 중복을 방지하는 데 도움이 됩니다.
```
SET @decoded_data = decode(encode(*, 'base64'), 'proto', 'schema', 'schema.desc', 'message.proto', 'Message')
SELECT @decoded_data.sensor_id, @decoded_data.reading FROM 'device/protobuf'
WHERE @decoded_data.reading > 100
```
SET 변수가 없으면 디코딩 함수를 세 번 반복해야 하며, 이는 함수 호출 제한을 초과합니다.
**여러 변수**
쉼표로 구분하여 단일 SET 절에서 여러 변수를 정의할 수 있습니다.
```
SET @user_data = get_user_properties(device_id), @threshold = 50
SELECT @user_data.name, temp_fahrenheit FROM 'sensors/+'
WHERE temp_fahrenheit > @threshold AND @user_data.active = true
```
**대체 템플릿에서 변수 사용**
변수는 작업 대체 템플릿에도 사용할 수 있으므로 SQL 문과 규칙 작업 모두에서 계산된 값을 재사용할 수 있습니다.
SQL 문
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
작업 구성:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
이 예제에서는 대체 템플릿에서 SET 변수를 `@temp_celsius` 사용하여 S3 작업의 키 필드를 구성합니다.
**비 JSON 페이로드 사용량**
SET 변수는 비 JSON 페이로드를 직접 지원하지 않으므로 먼저 페이로드를 인코딩하거나 디코딩해야 합니다.
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
비 JSON 페이로드 작업 방법에 대한 자세한 내용은 섹션을 참조하세요. [이진 페이로드 작업](binary-payloads.md)
## SET 절 제한
SET 변수에는 다음 제한이 적용됩니다.
+ SQL 문당 최대 10개의 고유 변수
+ 최대 변수 값 크기 128KiB(최소 UTF-8 JSON 문자열)
+ 모든 변수에 대해 128KiB의 최대 총 값 크기
+ 변수 이름은 64자로 제한됩니다.
+ 변수는 JSON 페이로드를 그대로 직접 수락할 수 있습니다(JSON이 아닌 페이로드를 먼저 인코딩/디코딩해야 함).
# WHERE 절
WHERE 절은 규칙에서 지정된 작업이 수행되었는지 여부를 확인합니다. WHERE 절이 true로 평가될 경우 규칙 작업이 수행됩니다. 그렇지 않으면 규칙 작업이 수행되지 않습니다.
WHERE 절은 [데이터 타입](iot-sql-data-types.md), , [연산자](iot-sql-operators.md), [함수](iot-sql-functions.md), [리터럴](iot-sql-literals.md)[Case 문](iot-sql-case.md), [JSON 확장](iot-sql-json.md), [변수](iot-sql-set.md#iot-sql-set-usage) 및를 지원합니다[중첩된 객체 쿼리](iot-sql-nested-queries.md).
**예:**
`topic/subtopic`에 게시된 수신 페이로드: `{"color":"red", "temperature":40}`
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
이 경우 규칙이 트리거되지만 규칙에서 지정된 작업은 수행되지 않습니다. 송신 페이로드가 없습니다.
WHERE 절에서 함수 및 연산자를 사용할 수 있습니다. 하지만 SELECT 절의 AS 키워드를 사용하여 생성된 별칭은 참조할 수 없습니다. SELECT 절 평가 여부를 결정하기 위해 WHERE 절이 먼저 평가됩니다.
**비 JSON 페이로드 예제:**
'topic/subtopic'에 게시된 들어오는 비 JSON 페이로드: '80'
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
이 경우 규칙이 트리거되고 규칙에서 지정된 작업이 수행됩니다. 나가는 페이로드는 SELECT 절에 의해 JSON 페이로드 `{"value":80}`으로 변환됩니다.
# 데이터 타입
AWS IoT 규칙 엔진은 모든 JSON 데이터 형식을 지원합니다.
**지원되는 데이터 유형**
| Type | 의미 |
| --- | --- |
| Int | 이산 Int. 최대 34자리. |
| Decimal | 정밀도 34자리, 0이 아닌 최소 크기 1E-999, 최대 크기 9.999…E999의 `Decimal` 일부 함수는 34자리 정밀도 대신 배정밀도의 `Decimal`을 반환합니다. SQL V2(2016-03-23)에서 `10.0`와(과) 같은 정수인 숫자 값은 예상되는 `Decimal` 값(`10.0`) 대신 `Int` 값(`10`)으로 처리됩니다. 정수 숫자 값을 `Decimal` 값으로 안정적으로 처리하려면 규칙 쿼리 문에 SQL V1(2015-10-08)을 사용하세요. |
| Boolean | True 또는 False |
| String | UTF-8 문자열 |
| Array | 동일한 형식일 필요가 없는 일련의 값 |
| Object | 키 및 값으로 구성된 JSON 값입니다. 키는 문자열이어야 합니다. 값은 임의의 형식일 수 있습니다. |
| Null | JSON에 의해 정의된 Null입니다. 이는 값 없음을 나타내는 실제 값입니다. SQL 문에서 Null 키워드를 사용하여 명시적으로 Null 값을 생성할 수 있습니다. 예: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | 값이 아닙니다. 값을 생략하는 것 이외에는 JSON에서 이를 명시적으로 표현할 수 없습니다. 예를 들어 객체 `{"foo": null}`에서 키 "foo"는 NULL을 반환하지만 키 "bar"는 `Undefined`를 반환합니다. 내부적으로는 SQL 언어가 `Undefined`를 값으로 취급하지만 JSON에서는 표현이 불가능합니다. 따라서 JSON으로 직렬화될 경우 결과는 `Undefined`입니다. {"foo":null, "bar":undefined} 다음과 같이 JSON으로 직렬화됩니다. {"foo":null} 마찬가지로, `Undefined`는 자체에 의해 직렬화될 경우 빈 문자열로 변환됩니다. 잘못된 인수(예: 잘못된 형식, 잘못된 인수 개수 등)로 호출된 함수는 `Undefined`를 반환합니다. |
## 변환
다음 표에는 (함수에 잘못된 형식의 값이 입력된 경우) 값이 한 형식에서 다른 형식으로 변환될 경우의 결과가 나와 있습니다. 예를 들어 절대값 함수 "abs"(`Int` 또는 `Decimal`이 필요함)에 `String`이 주어질 경우 이 함수는 다음 규칙에 따라 `String`을 `Decimal`로 변환하려고 시도합니다. 이 경우 'abs("-5.123")'는 'abs(-5.123)'으로 취급됩니다.
**참고**
`Array`, `Object`, `Null` 또는 `Undefined`로는 변환이 시도되지 않습니다.
**소수로 변환**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 소수점이 없는 Decimal |
| Decimal | 소스 값 |
| Boolean | Undefined(명시적으로 cast 함수를 사용하여 true = 1.0, false = 0.0으로 변환할 수 있습니다.) |
| String | SQL 엔진은 문자열을 로 구문 분석하려고 시도합니다Decimal.는 정규식과 일치하는 문자열을 구문 분석하려고 AWS IoT 시도합니다^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12"는 모두 자동으로 Decimal로 변환되는 문자열의 예입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Null. |
| 정의되지 않음 | Undefined. |
**정수로 변환**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 소스 값 |
| Decimal | 가장 가까운 Int로 반올림한 소스 값 |
| Boolean | Undefined(명시적으로 cast 함수를 사용하여 true = 1.0, false = 0.0으로 변환할 수 있습니다.) |
| String | SQL 엔진은 문자열을 로 구문 분석하려고 시도합니다Decimal.는 정규식과 일치하는 문자열을 구문 분석하려고 AWS IoT 시도합니다^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12"는 모두 자동으로 Decimals. AWS IoT attempts로 변환되어를 String로 변환하는 문자열의 예Decimal입니다. 그런 다음 해당 문자열의 소수점을 잘라Decimal내어를 만듭니다Int. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Null. |
| 정의되지 않음 | Undefined. |
**부울로 변환**
| 인수 유형 | 결과 |
| --- | --- |
| Int | Undefined(명시적으로 cast 함수를 사용하여 0 = False, 0이 아닌 값 = True로 변환할 수 있습니다.) |
| Decimal | Undefined(명시적으로 cast 함수를 사용하여 0 = False, 0이 아닌 값 = True로 변환할 수 있습니다.) |
| Boolean | 원래 값 |
| String | "true"=True, "false"=False(대/소문자를 구분하지 않음). 다른 문자열 값은 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
**문자열로 변환**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 표준 표기법을 따른 Int의 문자열 표현. |
| Decimal | 유효숫자 표기법을 따를 수 있는 Decimal의 문자열 표현. |
| Boolean | "true" 또는 "false". 모두 소문자. |
| String | 원래 값 |
| 배열 | JSON으로 직렬화된 Array입니다. 결과 문자열은 대괄호 안의 쉼표로 구분된 목록입니다. String은 따옴표로 묶입니다. Decimal, Int, Boolean 및 Null은 따옴표로 묶이지 않습니다. |
| 객체 | JSON으로 직렬화된 객체입니다. 결과 문자열은 키-값 페어의 쉼표로 구분된 목록이며 중괄호로 묶입니다. String은 따옴표로 묶입니다. Decimal, Int, Boolean 및 Null은 따옴표로 묶이지 않습니다. |
| Null | Undefined. |
| 정의되지 않음 | Undefined |
# 연산자
SELECT 및 WHERE 절에서 다음 연산자를 사용할 수 있습니다.
## AND 연산자
`Boolean` 결과를 반환합니다. 논리적 AND 연산을 수행합니다. 왼쪽 및 오른쪽 피연산자가 true일 경우 true를, 그렇지 않을 경우 false를 반환합니다. `Boolean` 피연산자 또는 대/소문자를 구분하지 않는 "true" 또는 "false" 문자열 피연산자가 필요합니다.
*구문:* ` expression AND expression`.
**AND 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Boolean | Boolean | Boolean. 양쪽 피연산자가 true일 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Boolean | String/Boolean | 모든 문자열이 "true" 또는 "false"(대/소문자를 구분하지 않음)일 경우 문자열은 Boolean로 변환된 후 정상적으로 boolean AND boolean로 처리됩니다. |
| 기타 값 | 기타 값 | Undefined. |
## OR 연산자
`Boolean` 결과를 반환합니다. 논리적 OR 연산을 수행합니다. 왼쪽 또는 오른쪽 피연산자가 true일 경우 true를, 그렇지 않을 경우 false를 반환합니다. 그렇지 않을 경우 false를 반환합니다. `Boolean` 피연산자 또는 대/소문자를 구분하지 않는 "true" 또는 "false" 문자열 피연산자가 필요합니다.
*구문:* ` expression OR expression`.
**OR 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Boolean | Boolean | Boolean. 어느 한 피연산자가 true일 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Boolean | String/Boolean | 모든 문자열이 "true" 또는 "false"(대/소문자를 구분하지 않음)인 경우 문자열은 부울로 변환되고 정상적으로 boolean OR boolean으로 처리됩니다. |
| 기타 값 | 기타 값 | Undefined. |
## NOT 연산자
`Boolean` 결과를 반환합니다. 논리적 NOT 연산을 수행합니다. 피연산자가 false일 경우 true를, 그렇지 않은 경우 false를 반환합니다. `Boolean` 피연산자 또는 대/소문자를 구분하지 않는 "true" 또는 "false" 문자열 피연산자가 필요합니다.
*구문:* `NOT expression`.
**NOT 연산자**
| 피연산자 | 출력 |
| --- | --- |
| Boolean | Boolean. 피연산자가 false일 경우 true입니다. 그렇지 않은 경우 true입니다. |
| String | 문자열이 'true' 또는 'false'(대/소문자를 구분하지 않음)일 경우 문자열은 해당하는 부울 값으로 변환되고 반대 값이 반환됩니다. |
| 기타 값 | Undefined. |
## IN 연산자
`Boolean` 결과를 반환합니다. WHERE 절의 IN 연산자를 사용하여 값이 배열의 값과 일치하는지 확인할 수 있습니다. 일치 항목이 발견되면 true를 반환하고 그렇지 않으면 false를 반환합니다.
*구문:* ` expression IN expression`.
**IN 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | 배열에서 Integer/Decimal/String/Array/Object 요소가 발견되면 true입니다. 그렇지 않으면 false입니다. |
*예:*
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
이 예제에서는 `arr`이라는 배열에 3이 존재하므로 `where 3 in arr` 조건 절이 true로 평가됩니다. 따라서 SQL 문에서 `select * from 'a/b'`가 실행됩니다. 이 예제는 배열이 이기종일 수 있음을 보여줍니다.
## EXISTS 연산자
`Boolean` 결과를 반환합니다. 조건부 절에서 EXISTS 연산자를 사용하여 하위 쿼리에 요소가 있는지 테스트할 수 있습니다. 하위 쿼리가 하나 이상의 요소를 반환하는 경우 true를 반환하고 하위 쿼리가 요소를 반환하지 않는 경우 false를 반환합니다.
*구문:* ` expression`.
*예:*
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
이 예제에서는 `arr`이라는 배열에 3이 존재하므로 `where exists (select * from arr as a where a = 3)` 조건 절이 true로 평가됩니다. 따라서 SQL 문에서 `select * from 'a/b'`가 실행됩니다.
*예:*
```
SQL: select * from 'a/b' where exists (select * from e as e where foo = 2)
JSON: {"foo":4,"bar":5,"e":[{"foo":1},{"foo":2}]}
```
이 예제에서는 JSON 객체 `e` 내의 배열에 객체 `{"foo":2}`가 포함되어 있기 때문에 `where exists (select * from e as e where foo = 2)` 조건 절이 true로 평가됩니다. 따라서 SQL 문에서 `select * from 'a/b'`가 실행됩니다.
## > 연산자
`Boolean` 결과를 반환합니다. 왼쪽 피연산자가 오른쪽 피연산자보다 클 경우 true를 반환합니다. 두 피연산자 모두 `Decimal`로 변환된 후 비교됩니다.
*구문:* `expression > expression`.
**> 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. 왼쪽 피연산자가 오른쪽 피연산자보다 클 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열을 Decimal로 변환할 수 있는 경우 Boolean입니다. 왼쪽 피연산자가 오른쪽 피연산자보다 클 경우 true를 반환합니다. 그렇지 않으면 false입니다. |
| 기타 값 | Undefined. | Undefined. |
## >= 연산자
`Boolean` 결과를 반환합니다. 왼쪽 피연산자가 오른쪽 피연산자보다 크거나 같을 경우 true, 그렇지 않을 경우 false를 반환합니다. 두 피연산자 모두 `Decimal`로 변환된 후 비교됩니다.
*구문:* `expression >= expression`.
**>= 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. 왼쪽 피연산자가 오른쪽 피연산자보다 크거나 같을 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열을 Decimal로 변환할 수 있는 경우 Boolean입니다. 왼쪽 피연산자가 오른쪽 피연산자보다 크거나 같을 경우 true, 그렇지 않을 경우 false를 반환합니다. 그렇지 않으면 false입니다. |
| 기타 값 | Undefined. | Undefined. |
## < 연산자
`Boolean` 결과를 반환합니다. 왼쪽 피연산자가 오른쪽 피연산자보다 작을 경우 true를 반환합니다. 두 피연산자 모두 `Decimal`로 변환된 후 비교됩니다.
*구문:* `expression < expression`.
**< 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. 왼쪽 피연산자가 오른쪽 피연산자보다 작을 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열을 Decimal로 변환할 수 있는 경우 Boolean입니다. 왼쪽 피연산자가 오른쪽 피연산자보다 작을 경우 true를 반환합니다. 그렇지 않으면 false입니다. |
| 기타 값 | Undefined | Undefined |
## <= 연산자
`Boolean` 결과를 반환합니다. 왼쪽 피연산자가 오른쪽 피연산자보다 작거나 같을 경우 true, 그렇지 않을 경우 false를 반환합니다. 두 피연산자 모두 `Decimal`로 변환된 후 비교됩니다.
*구문:* `expression <= expression`.
**<= 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. 왼쪽 피연산자가 오른쪽 피연산자보다 작거나 같을 경우 true입니다. 그렇지 않으면 false입니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열을 Decimal로 변환할 수 있는 경우 Boolean입니다. 왼쪽 피연산자가 오른쪽 피연산자보다 작거나 같을 경우 true, 그렇지 않을 경우 false를 반환합니다. 그렇지 않으면 false입니다. |
| 기타 값 | Undefined | Undefined |
## <> 연산자
`Boolean` 결과를 반환합니다. 왼쪽 및 오른쪽 피연산자가 다를 경우 true를, 그렇지 않을 경우 false를 반환합니다.
*구문:* ` expression <> expression`.
**<> 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | 왼쪽 피연산자가 오른쪽 피연산자와 다를 경우 true입니다. 그렇지 않으면 false입니다. |
| Decimal | Decimal | 왼쪽 피연산자가 오른쪽 피연산자와 다를 경우 true입니다. 그렇지 않으면 false입니다. Int은(는) Decimal(으)로 변환된 후 비교됩니다. |
| String | String | 왼쪽 피연산자가 오른쪽 피연산자와 다를 경우 true입니다. 그렇지 않으면 false입니다. |
| 배열 | 배열 | 각 피연산자의 항목이 같지 않고 동일한 순서가 아닐 경우 true입니다. 그렇지 않으면 false입니다. |
| 객체 | 객체 | 각 피연산자의 키 및 값이 다를 경우 true입니다. 그렇지 않으면 false입니다. 키/값의 순서는 무시됩니다. |
| Null | Null | False. |
| 임의의 값 | Undefined | Undefined |
| Undefined | 임의의 값 | Undefined |
| 일치하지 않은 형식 | 일치하지 않은 형식 | True. |
## = 연산자
`Boolean` 결과를 반환합니다. 왼쪽 및 오른쪽 피연산자가 동일한 경우 true를, 그렇지 않을 경우 false를 반환합니다.
*구문:* ` expression = expression`.
**= 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | 왼쪽 피연산자가 오른쪽 피연산자와 같을 경우 true입니다. 그렇지 않으면 false입니다. |
| Decimal | Decimal | 왼쪽 피연산자가 오른쪽 피연산자와 같을 경우 true입니다. 그렇지 않으면 false입니다. Int은(는) Decimal(으)로 변환된 후 비교됩니다. |
| String | String | 왼쪽 피연산자가 오른쪽 피연산자와 같을 경우 true입니다. 그렇지 않으면 false입니다. |
| 배열 | 배열 | 각 피연산자의 항목이 같고 동일한 순서일 경우 true입니다. 그렇지 않으면 false입니다. |
| 객체 | 객체 | 각 피연산자의 키 및 값이 같을 경우 true입니다. 그렇지 않으면 false입니다. 키/값의 순서는 무시됩니다. |
| 임의의 값 | Undefined | Undefined. |
| Undefined | 임의의 값 | Undefined. |
| 일치하지 않은 형식 | 일치하지 않은 형식 | False. |
## \$1 연산자
"\$1"는 오버로드된 연산자입니다. 문자열 연결 또는 추가에 사용할 수 있습니다.
*구문:* ` expression + expression`.
**\$1 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| String | 임의의 값 | 오른쪽 피연산자를 문자열로 변환하여 왼쪽 피연산자의 끝에 연결합니다. |
| 임의의 값 | String | 왼쪽 피연산자를 문자열로 변환하고 오른쪽 피연산자를 변환된 왼쪽 피연산자의 끝에 연결합니다. |
| Int | Int | Int 값 피연산자를 함께 더합니다. |
| Int/Decimal | Int/Decimal | Decimal 값 피연산자를 함께 더합니다. |
| 기타 값 | 기타 값 | Undefined. |
## - 연산자
왼쪽 피연산자에서 오른쪽 피연산자를 뺍니다.
*구문:* ` expression - expression`.
**- 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int 값 왼쪽 피연산자에서 오른쪽 피연산자를 뺍니다. |
| Int/Decimal | Int/Decimal | Decimal 값 왼쪽 피연산자에서 오른쪽 피연산자를 뺍니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 올바르게 10진수로 변환된 경우 Decimal 값이 반환됩니다. 왼쪽 피연산자에서 오른쪽 피연산자를 뺍니다. 그렇지 않은 경우 Undefined를 반환합니다. |
| 기타 값 | 기타 값 | Undefined. |
| 기타 값 | 기타 값 | Undefined. |
## \$1 연산자
왼쪽 피연산자에 오른쪽 피연산자를 곱합니다.
*구문:* ` expression * expression`.
**\$1 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int 값 왼쪽 피연산자에 오른쪽 피연산자를 곱합니다. |
| Int/Decimal | Int/Decimal | Decimal 값 왼쪽 피연산자에 오른쪽 피연산자를 곱합니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 올바르게 10진수로 변환된 경우 Decimal 값이 반환됩니다. 왼쪽 피연산자에 오른쪽 피연산자를 곱합니다. 그렇지 않은 경우 Undefined를 반환합니다. |
| 기타 값 | 기타 값 | Undefined. |
## / 연산자
왼쪽 피연산자를 오른쪽 피연산자로 나눕니다.
*구문:* ` expression / expression`.
**/ 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int 값 왼쪽 피연산자를 오른쪽 피연산자로 나눕니다. |
| Int/Decimal | Int/Decimal | Decimal 값 왼쪽 피연산자를 오른쪽 피연산자로 나눕니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 올바르게 10진수로 변환된 경우 Decimal 값이 반환됩니다. 왼쪽 피연산자를 오른쪽 피연산자로 나눕니다. 그렇지 않은 경우 Undefined를 반환합니다. |
| 기타 값 | 기타 값 | Undefined. |
## % 연산자
왼쪽 피연산자를 오른쪽 피연산자로 나눈 나머지를 반환합니다.
*구문:* ` expression % expression`.
**% 연산자**
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int 값 왼쪽 피연산자를 오른쪽 피연산자로 나눈 나머지를 반환합니다. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 올바르게 10진수로 변환된 경우 Decimal 값이 반환됩니다. 왼쪽 피연산자를 오른쪽 피연산자로 나눈 나머지를 반환합니다. 그렇지 않을 경우 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
# 함수
SQL 표현식의 SELECT 또는 WHERE 절에서 다음 내장 함수를 사용할 수 있습니다.
, [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)및 외부 함수는 규칙 작업과 동일한 요금이 청구됩니다[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow). 또한 [JSON에 대한 Protobuf 메시지를 디코딩](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf)할 때만 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) 함수에 대한 요금이 청구됩니다. 자세한 내용은 [AWS IoT Core pricing page](https://aws.amazon.com/iot-core/pricing/)를 참조하세요.
## abs(Decimal)
숫자의 절대값을 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `abs(-5)`= 5.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int, 인수의 절대값 |
| Decimal | Decimal, 인수의 절대값 |
| Boolean | Undefined. |
| String | Decimal. 결과는 인수의 절대값입니다. 문자열을 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## accountid()
이 규칙을 소유하는 계정의 ID를 `String`으로 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`accountid() ` = "123456789012"
## acos(Decimal)
숫자의 역코사인을 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `acos(0)` = 1.5707963267948966
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 역코사인. 가상 결과는 Undefined로 반환됩니다. |
| Decimal | Decimal(배정밀도), 인수의 역코사인. 가상 결과는 Undefined로 반환됩니다. |
| Boolean | Undefined. |
| String | Decimal, 인수의 역코사인. 문자열을 변환할 수 없는 경우 결과는 Undefined입니다. 가상 결과는 Undefined로 반환됩니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## asin(Decimal)
숫자의 역사인을 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `asin(0)` = 0.0
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 역사인. 가상 결과는 Undefined로 반환됩니다. |
| Decimal | Decimal(배정밀도), 인수의 역사인. 가상 결과는 Undefined로 반환됩니다. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 역사인. 문자열을 변환할 수 없는 경우 결과는 Undefined입니다. 가상 결과는 Undefined로 반환됩니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## atan(Decimal)
숫자의 역탄젠트를 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `atan(0)` = 0.0
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 역탄젠트. 가상 결과는 Undefined로 반환됩니다. |
| Decimal | Decimal(배정밀도), 인수의 역탄젠트. 가상 결과는 Undefined로 반환됩니다. |
| Boolean | Undefined. |
| String | Decimal, 인수의 역탄젠트. 문자열을 변환할 수 없는 경우 결과는 Undefined입니다. 가상 결과는 Undefined로 반환됩니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## atan2(Decimal, Decimal)
양의 x축과 두 인수로 정의된 점(x, y) 사이의 각도(라디안)를 반환합니다. 이 각도는 시계 반대 방향 각도(상반면, y > 0)의 경우 양수이고, 시계 방향 각도(하반면, y < 0). `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `atan2(1, 0)` = 1.5707963267948966
****
| 인수 유형 | 인수 유형 | 결과 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal(배정밀도), x축과 지정된 점(x,y) 사이의 각도. |
| Int/Decimal/String | Int/Decimal/String | Decimal, 설명된 점의 역탄젠트. 문자열을 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## aws\$1lambda(functionArn, inputJson)
`inputJson`을 Lambda 함수로 전달하도록 지정된 Lambda 함수를 호출한 다음 Lambda 함수에서 생성되는 JSON 데이터를 반환합니다.
**인수**
| 인수 | 설명 |
| --- | --- |
| functionArn | 호출할 Lambda 함수의 ARN입니다. Lambda 함수는 JSON 데이터를 반환해야 합니다. |
| inputJson | Lambda 함수로 전달되는 JSON 입력 값입니다. 중첩된 객체 쿼리와 리터럴을 전달하려면 SQL 버전 2016-03-23을 사용해야 합니다. |
지정된 Lambda 함수를 호출할 수 있는 권한을 부여 AWS IoT `lambda:InvokeFunction`해야 합니다. 다음은 AWS CLI를 사용하여 `lambda:InvokeFunction` 권한을 부여하는 방법을 보여주는 예제입니다.
```
aws lambda add-permission --function-name "function_name"
--region "region"
--principal iot.amazonaws.com
--source-arn arn:aws:iot:us-east-1:account_id:rule/rule_name
--source-account "account_id"
--statement-id "unique_id"
--action "lambda:InvokeFunction"
```
다음은 **add-permission** 명령의 인수입니다.
--function-name
Lambda 함수의 이름입니다. 함수의 리소스 정책을 업데이트하기 위한 새 권한을 추가합니다.
--region
계정 AWS 리전 의 입니다.
--principal
권한을 부여받는 보안 주체입니다. 이는 Lambda 함수`iot.amazonaws.com`를 호출할 수 있는 AWS IoT 권한을 허용하기 위한 것이어야 합니다.
--source-arn
규칙의 ARN입니다. **get-topic-rule** AWS CLI 명령을 사용하여 규칙의 ARN을 가져올 수 있습니다.
--source-account
규칙이 정의된 AWS 계정 입니다.
--statement-id
고유한 문 식별자입니다.
--action
이 문에서 허용할 Lambda 작업입니다. AWS IoT 가 Lambda 함수를 호출하도록 허용하려면 `lambda:InvokeFunction`을 지정합니다.
**중요**
`source-arn` 또는를 제공하지 않고 AWS IoT 보안 주체에 대한 권한을 추가하는 경우 Lambda 작업으로 규칙을 생성하는 `source-account` AWS 계정 는 Lambda 함수를 호출하는 규칙을 트리거할 수 있습니다 AWS IoT. 자세한 내용은 [Lambda 권한 모델](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)을 참조하세요.
다음과 같은 JSON 메시지 페이로드가 있을 경우:
```
{
"attribute1": 21,
"attribute2": "value"
}
```
다음과 같이 `aws_lambda` 함수를 사용하여 Lambda 함수를 호출할 수 있습니다.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
전체 MQTT 메시지 페이로드를 전달하려면 다음 예와 같이 '\$1'를 사용하여 JSON 페이로드를 지정할 수 있습니다.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element`는 'topic/subtopic' 주제에 게시되는 메시지에서 데이터를 선택합니다.
`some.value`는 Lambda 함수에서 생성되는 출력에서 데이터를 선택합니다.
**참고**
규칙 엔진은 Lambda 함수의 실행 시간을 제한합니다. 규칙의 Lambda 함수 호출은 2,000ms 이내에 완료되어야 합니다.
## bitand(Int, Int)
두 `Int`(변환) 인수의 비트 표현에 대해 비트 단위 AND를 수행합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `bitand(13, 5)` = 5
****
| 인수 유형 | 인수 유형 | 결과 |
| --- | --- | --- |
| Int | Int | Int, 두 인수의 비트 단위 AND. |
| Int/Decimal | Int/Decimal | Int, 두 인수의 비트 단위 AND. 모든 비 Int 숫자는 가장 가까운 Int로 내림됩니다. 인수를 Int로 변환할 수 없는 경우 결과는 Undefined입니다. |
| Int/Decimal/String | Int/Decimal/String | Int, 두 인수의 비트 단위 AND. 모든 문자열은 10진수로 변환된 후 가장 가까운 Int로 내림됩니다. 변환이 실패할 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## bitor(Int, Int)
두 인수의 비트 표현에 대해 비트 단위 OR을 수행합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `bitor(8, 5)` = 13
****
| 인수 유형 | 인수 유형 | 결과 |
| --- | --- | --- |
| Int | Int | Int, 두 인수의 비트 단위 OR. |
| Int/Decimal | Int/Decimal | Int, 두 인수의 비트 단위 OR. 모든 비 Int 숫자는 가장 가까운 Int로 내림됩니다. 변환이 실패할 경우 결과는 Undefined입니다. |
| Int/Decimal/String | Int/Decimal/String | Int, 두 인수의 비트 단위 OR. 모든 문자열은 10진수로 변환된 후 가장 가까운 Int로 내림됩니다. 변환이 실패할 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## bitxor(Int, Int)
두 `Int`(변환) 인수의 비트 표현에 대해 비트 단위 XOR을 수행합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `bitor(13, 5)` = 8
****
| 인수 유형 | 인수 유형 | 결과 |
| --- | --- | --- |
| Int | Int | Int, 두 인수에 대한 비트 단위 XOR. |
| Int/Decimal | Int/Decimal | Int, 두 인수에 대한 비트 단위 XOR. 비 Int 숫자는 가장 가까운 Int로 내림됩니다. |
| Int/Decimal/String | Int/Decimal/String | Int, 두 인수에 대한 비트 단위 XOR. 문자열은 10진수로 변환되어 가장 가까운 Int로 내림됩니다. 변환이 실패할 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## bitnot(Int)
`Int`(변환) 인수의 비트 표현에 대해 비트 단위 NOT을 수행합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `bitnot(13)` = 2
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int, 인수의 비트 단위 NOT. |
| Decimal | Int, 인수의 비트 단위 NOT. Decimal 값은 가장 가까운 Int로 내림됩니다. |
| String | Int, 인수의 비트 단위 NOT. 문자열은 10진수로 변환된 후 가장 가까운 Int로 내림됩니다. 변환이 실패할 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 |
## cast()
값을 한 데이터 형식에서 다른 형식으로 변환합니다. cast는 일반 변환과 거의 비슷하게 동작하지만 숫자와 부울 간 캐스팅이 추가됩니다. 가 한 유형을 다른 유형으로 캐스팅하는 방법을 결정할 AWS IoT 수 없는 경우 결과는 입니다`Undefined`. SQL 버전 2015-10-08 이상에서 지원됩니다. 형식: cast(*value* as *type*).
예제:
`cast(true as Int) ` = 1
`cast` 호출 시 다음 키워드가 "as" 뒤에 나올 수 있습니다.
**SQL 버전 2015-10-08 및 2016-03-23의 경우**
| 키워드 | 결과 |
| --- | --- |
| String | 값을 String로 캐스팅합니다. |
| Nvarchar | 값을 String로 캐스팅합니다. |
| 텍스트 | 값을 String로 캐스팅합니다. |
| Ntext | 값을 String로 캐스팅합니다. |
| varchar | 값을 String로 캐스팅합니다. |
| Int | 값을 Int로 캐스팅합니다. |
| Integer | 값을 Int로 캐스팅합니다. |
| 배정밀도 실수 | 값을 Decimal(배정밀도)로 캐스팅합니다. |
**SQL 버전 2016-03-23의 경우**
| 키워드 | 결과 |
| --- | --- |
| Decimal | 값을 Decimal로 캐스팅합니다. |
| 부울 | 값을 Boolean로 캐스팅합니다. |
| Boolean | 값을 Boolean로 캐스팅합니다. |
캐스팅 규칙:
**소수로 캐스팅**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 소수점이 없는 Decimal |
| Decimal | 소스 값 SQL V2(2016-03-23)에서 `10.0`와(과) 같은 정수인 숫자 값은 예상되는 `Decimal` 값(`10.0`) 대신 `Int` 값(`10`)을 반환합니다. 정수 숫자 값을 `Decimal` 값으로 안정적으로 캐스팅하려면 규칙 쿼리 문에 SQL V1(2015-10-08)을 사용하세요. |
| Boolean | true = 1.0, false = 0.0. |
| String | 문자열을 Decimal로 구문 분석하려고 시도합니다. AWS IoT 는 다음 정규식 ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1와 일치하는 문자열을 구문 분석하려고 시도합니다. "0", "-1.2", "5E-12"는 모두 자동으로 10진수로 변환되는 문자열의 예입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
**정수로 캐스팅**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 소스 값 |
| Decimal | 가장 가까운 Int로 내림한 소스 값 |
| Boolean | true = 1.0, false = 0.0. |
| String | 문자열을 Decimal로 구문 분석하려고 시도합니다. AWS IoT 는 다음 정규식 ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1와 일치하는 문자열을 구문 분석하려고 시도합니다. "0", "-1.2", "5E-12"는 모두 자동으로 10진수로 변환되는 문자열의 예입니다. AWS IoT 는 문자열을 Decimal로 변환한 후 가장 가까운 Int로 내림하려고 시도합니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
**`Boolean`로 캐스팅**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 0 = False, 0이 아닌 값 = True. |
| Decimal | 0 = False, 0이 아닌 값 = True. |
| Boolean | 소스 값 |
| String | "true" = True, "false" = False(대/소문자를 구분하지 않음). 다른 문자열 값 = Undefined. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
**문자열로 캐스팅**
| 인수 유형 | 결과 |
| --- | --- |
| Int | 표준 표기법을 따른 Int의 문자열 표현. |
| Decimal | 유효숫자 표기법을 따를 수 있는 Decimal의 문자열 표현. |
| Boolean | "true" 또는 "false", 모두 소문자. |
| String | 소스 값 |
| 배열 | JSON으로 직렬화된 배열입니다. 결과 문자열은 대괄호 안의 쉼표로 구분된 목록입니다. String은 따옴표로 묶입니다. Decimal, Int 및 Boolean은 따옴표로 묶이지 않습니다. |
| 객체 | JSON으로 직렬화된 객체입니다. JSON 문자열은 키-값 페어의 쉼표로 구분된 목록이며 중괄호로 묶입니다. String은 따옴표로 묶입니다. Decimal, Int, Boolean 및 Null은 따옴표로 묶이지 않습니다. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## ceil(Decimal)
지정된 `Decimal`을 가장 가까운 `Int`로 올림합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int, 인수 값 |
| Decimal | Int, 가장 가까운 Int로 올림된 Decimal 값 |
| String | Int. 문자열은 Decimal로 변환된 후 가장 가까운 Int로 올림됩니다. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | Undefined. |
## chr(String)
지정된 `Int` 인수에 대응하는 ASCII 문자를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`chr(65)` = "A".
`chr(49)` = "1".
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | 지정된 ASCII 값에 대응하는 문자입니다. 인수가 유효한 ASCII 값이 아닐 경우 결과는 Undefined입니다. |
| Decimal | 지정된 ASCII 값에 대응하는 문자입니다. Decimal 인수는 가장 가까운 Int로 내림됩니다. 인수가 유효한 ASCII 값이 아닐 경우 결과는 Undefined입니다. |
| Boolean | Undefined. |
| String | String을 Decimal로 변환할 수 있는 경우 가장 가까운 Int로 내림됩니다. 인수가 유효한 ASCII 값이 아닐 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 기타 값 | Undefined. |
## clientid()
메시지를 전송하는 MQTT 클라이언트의 ID, 또는 메시지가 MQTT를 통해 전송되지 않은 경우 `n/a`를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`clientid() ` = "123456789012"
## concat()
배열 또는 문자열을 연결합니다. 이 함수는 인수의 수를 제한하지 않으며 `String` 또는 `Array`를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`concat() ` = `Undefined`.
`concat(1) ` = "1".
`concat([1, 2, 3], 4)` = [1, 2, 3, 4].
`concat([1, 2, 3], "hello")` = [1, 2, 3, "hello"]
`concat("con", "cat")` = "concat"
`concat(1, "hello")` = "1hello"
`concat("he","is","man")` = "heisman"
`concat([1, 2, 3], "hello", [4, 5, 6])` = [1, 2, 3, "hello", 4, 5, 6]
****
| 인수의 수 | 결과 |
| --- | --- |
| 0 | Undefined. |
| 1 | 인수가 수정 없이 반환됩니다. |
| 2\$1 | 인수가 `Array`일 경우 결과는 모든 인수를 포함하는 단일 배열입니다. 모든 인수가 배열이 아니고 하나 이상의 인수가 `String`일 경우 결과는 모든 인수에 대한 `String` 표현의 연결입니다. 인수는 이전에 나열된 표준 변환을 사용하여 문자열로 변환됩니다. |
## cos(Decimal)
숫자의 코사인을 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`cos(0)` = 1.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 코사인. 가상 결과는 Undefined로 반환됩니다. |
| Decimal | Decimal(배정밀도), 인수의 코사인. 가상 결과는 Undefined로 반환됩니다. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 코사인. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. 가상 결과는 Undefined로 반환됩니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## cosh(Decimal)
숫자의 쌍곡코사인을 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `cosh(2.3)` = 5.037220649268761.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 쌍곡코사인. 가상 결과는 Undefined로 반환됩니다. |
| Decimal | Decimal(배정밀도), 인수의 쌍곡코사인. 가상 결과는 Undefined로 반환됩니다. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 쌍곡코사인. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. 가상 결과는 Undefined로 반환됩니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## decode(value, decodingScheme)
`decode` 함수를 사용하여 인코딩된 값을 디코딩합니다. 디코딩된 문자열이 JSON 문서인 경우, 주소 지정 가능한 객체가 반환됩니다. 그렇지 않으면 디코딩된 문자열이 문자열로 반환됩니다. 문자열을 디코딩할 수 없는 경우 함수는 NULL을 반환합니다. 이 함수는 base64로 인코딩된 문자열과 프로토콜 버퍼(protobuf) 메시지 형식의 디코딩을 지원합니다.
SQL 버전 2016-03-23 이상에서 지원됩니다.
값
문자열 값, 또는 문자열을 반환하는 ([AWS IoT SQL 참조](iot-sql-reference.md)에 정의된) 유효한 표현식입니다.
decodingScheme
값을 디코딩하는 데 사용되는 체계를 나타내는 리터럴 문자열입니다. 현재 `'base64'` 및 `'proto'`만 지원됩니다.
### base64로 인코딩된 문자열 디코딩
이 예에서 메시지 페이로드는 인코딩된 값을 포함합니다.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
이 SQL 문의 `decode` 함수는 메시지 페이로드의 값을 디코딩합니다.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
`encoded_temp` 값을 디코딩하면 SELECT 문에서 온도 값을 읽을 수 있는 다음과 같은 유효한 JSON 문서가 생성됩니다.
```
{ "temperature": 33 }
```
이 예제에서 SELECT 문의 결과는 다음과 같습니다.
```
{ "temp": 33 }
```
디코딩된 값이 유효한 JSON 문서가 아닌 경우 디코딩된 값은 문자열로 반환됩니다.
### protobuf 메시지 페이로드 디코딩
decode SQL 함수를 사용하여 protobuf 메시지 페이로드를 디코딩할 수 있는 규칙을 구성할 수 있습니다. 자세한 내용은 [protobuf 메시지 페이로드 디코딩](binary-payloads.md#binary-payloads-protobuf)을 참조하세요.
**중요**
AWS IoT 보안 주체에 대한 권한을 설정할 `source‐account` 때 `source‐arn` 또는를 생략하면에서 다른 AWS IoT 규칙을 통해 디코딩 함수를 호출할 AWS 계정 수 있습니다. 함수를 보호하려면 *Amazon Simple Storage Service 사용 설명서*의 [버킷 정책](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html)을 참조하세요.
함수 서명은 다음과 같습니다.
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
디코딩할 protobuf 인코딩 데이터를 지정합니다. 규칙으로 전송된 전체 메시지가 protobuf로 인코딩된 데이터인 경우 `*`를 사용하여 원시 바이너리 수신 페이로드를 참조할 수 있습니다. 그렇지 않은 경우 이 필드는 base-64로 인코딩된 JSON 문자열이어야 하며 문자열에 대한 참조를 직접 전달할 수 있습니다.
1) 원시 바이너리 protobuf 수신 페이로드를 디코딩하는 방법
```
decode(*, 'proto', ...)
```
2) base64로 인코딩된 문자열 'a.b'로 표시되는 protobuf로 인코딩된 메시지를 디코딩하는 방법
```
decode(a.b, 'proto', ...)
```
`proto`
디코딩할 데이터를 protobuf 메시지 형식으로 지정합니다. `proto` 대신 `base64`를 지정하면 이 함수는 base64로 인코딩된 문자열을 JSON으로 디코딩합니다.
`S3 BUCKET NAME`
`FileDescriptorSet` 파일을 업로드한 Amazon S3 버킷의 이름입니다.
`S3 OBJECT KEY`
Amazon S3 버킷 내의 `FileDescriptorSet` 파일을 지정하는 객체 키입니다.
`PROTO NAME`
`FileDescriptorSet` 파일을 생성하는 데 사용된 `.proto` 파일의 이름(확장명 제외)입니다.
`MESSAGE TYPE`
디코딩할 데이터가 준수해야 하는 `FileDescriptorSet` 파일 내 protobuf 메시지 구조의 이름입니다.
decode SQL 함수를 사용한 SQL 표현식의 예는 다음과 같습니다.
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
`mymessagetype`이라는 protobuf 메시지 유형을 준수하는 이진 수신 페이로드를 나타냅니다.
+ `messageformat.desc`
`s3-bucket`이라는 Amazon S3 버킷에 저장된 `FileDescriptorSet` 파일입니다.
+ `myproto`
`myproto.proto`라는 `FileDescriptorSet` 파일을 생성하는 데 사용된 원본 `.proto` 파일입니다.
+ `messagetype`
`myproto.proto`에 정의된 `messagetype`이라는 메시지 유형(가져온 종속 항목 포함)입니다.
## encode(value, encodingScheme)
`encode` 함수를 사용하여 페이로드(비 JSON 데이터일 수 있음)를 인코딩 체계를 기반으로 한 문자열 표현으로 인코딩합니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
값
[AWS IoT SQL 참조](iot-sql-reference.md)에서 정의된 임의의 유효한 표현식. \$1를 지정하여 JSON 형식 여부와 상관없이 전체 페이로드를 인코딩할 수 있습니다. 사용자가 표현식을 제공할 경우 식 결과가 문자열로 변환된 후 인코딩됩니다.
encodingScheme
사용할 인코딩 체계를 나타내는 리터럴 문자열. 현재 `'base64'`만 지원됩니다.
## endswith(String, String)
첫 번째 `String` 인수가 두 번째 `String` 인수로 끝나는지 여부를 나타내는 `Boolean`을 반환합니다. 인수가 `Null` 또는 `Undefined`일 경우 결과는 `Undefined`입니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `endswith("cat","at")` = true.
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| String | String | 첫 번째 인수가 두 번째 인수로 끝날 경우 true입니다. 그렇지 않으면 false입니다. |
| 기타 값 | 기타 값 | 두 인수는 모두 표준 변환 규칙을 사용하여 문자열로 변환됩니다. 첫 번째 인수가 두 번째 인수로 끝날 경우 true입니다. 그렇지 않으면 false입니다. 인수가 Null 또는 Undefined일 경우 결과는 Undefined입니다. |
## exp(Decimal)
`Decimal` 인수로 거듭제곱된 e를 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `exp(1)` = e.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), e ^ 인수. |
| Decimal | Decimal(배정밀도), e ^ 인수. |
| String | Decimal(배정밀도), e ^ 인수. String을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | Undefined. |
## floor(십진수)
지정된 `Decimal`을 가장 가까운 `Int`로 내림합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int, 인수 값 |
| Decimal | 가장 가까운 Int로 내림된 Decimal 값은 Int입니다. |
| String | Int. 문자열은 Decimal로 변환된 후 가장 가까운 Int로 내림됩니다. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | Undefined. |
## 시작
모음과 같은 형식(배열, 문자열, 객체)에서 값을 추출합니다. 첫 번째 인수에는 변환이 적용되지 않습니다. 변환은 두 번째 인수에 표에 설명된 대로 적용됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = "a"
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| 배열 | 임의의 형식(Int로 변환됨) | 두 번째 인수(Int로 변환됨)가 제공하는 0부터 시작하는 Array 인덱스의 항목. 변환이 실패할 경우 결과는 Undefined입니다. 인덱스가 Array의 범위를 벗어날 경우(음수 또는 >= array.length) 결과는 Undefined입니다. |
| 문자열 | 임의의 형식(Int로 변환됨) | 두 번째 인수(Int로 변환됨)가 제공하는 0부터 시작하는 문자열 인덱스의 문자. 변환이 실패할 경우 결과는 Undefined입니다. 인덱스가 문자열의 범위를 벗어날 경우(음수 또는 >= string.length) 결과는 Undefined입니다. |
| 객체 | String(변환이 적용되지 않음) | 두 번째 인수가 제공하는 문자열 키 에 대응되는 첫 번째 인수 객체에 저장된 값. |
| 기타 값 | 임의의 값 | Undefined. |
## get\$1dynamodb(tableName, partitionKeyName, partitionKeyValue, sortKeyName, sortKeyValue, roleArn)
DynamoDB 테이블에서 데이터를 검색합니다. `get_dynamodb()`를 사용하면 규칙이 평가되는 동안 DynamoDB 테이블을 쿼리할 수 있습니다. DynamoDB에서 검색된 데이터를 사용하여 메시지 페이로드를 필터링하거나 증가시킬 수 있습니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
`get_dynamodb()`는 다음 파라미터를 사용합니다.
tableName
쿼리할 DynamoDB 테이블의 이름입니다.
partitionKeyName
파티션 키의 이름입니다. 자세한 내용은 [ DynamoDB 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)를 참조하세요.
partitionKeyValue
레코드를 식별하는 데 사용되는 파티션 키의 값입니다. 자세한 내용은 [ DynamoDB 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)를 참조하세요.
sortKeyName
(선택 사항) 정렬 키의 이름입니다. 이 파라미터는 쿼리된 DynamoDB 테이블에서 복합 키를 사용하는 경우에만 필요합니다. 자세한 내용은 [ DynamoDB 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)를 참조하세요.
sortKeyValue
(선택 사항) 정렬 키의 값입니다. 이 파라미터는 쿼리된 DynamoDB 테이블에서 복합 키를 사용하는 경우에만 필요합니다. 자세한 내용은 [ DynamoDB 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)를 참조하세요.
roleArn
DynamoDB 테이블에 대한 액세스 권한을 부여하는 IAM 역할의 ARN입니다. 규칙 엔진은 사용자를 대신하여 DynamoDB 테이블에 액세스하기 위해 이 역할을 수임합니다. 지나치게 허용적인 역할을 사용하지 마세요. 규칙에 필요한 권한만 역할에 부여합니다. 다음은 하나의 DynamoDB 테이블에 대한 액세스 권한을 부여하는 정책 예제입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
`get_dynamodb()`를 사용하는 방법의 예로, AWS IoT에 연결된 모든 장치에 대한 디바이스 ID와 위치 정보가 포함된 DynamoDB 테이블이 있다고 가정해 보겠습니다. 다음 SELECT 문은 `get_dynamodb()` 함수를 사용하여 지정된 디바이스 ID의 위치를 검색합니다.
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**참고**
SQL 문 1개당 최대 한 번 `get_dynamodb()`를 호출할 수 있습니다. 단일 SQL 문에서 여러 번 `get_dynamodb()`를 호출하면 작업을 호출하지 않고 규칙이 종료됩니다.
## get\$1mqtt\$1property(name)
MQTT5 헤더 `contentType`, `payLoadFormatIndicator`, `responseTopic`, `correlationData` 중 하나를 참조합니다. 이 함수는 리터럴 문자열 `content_type`, `format_indicator`, `response_topic`, `correlation_data` 중 하나를 인수로 사용합니다. 자세한 내용은 다음 **함수 인수** 테이블을 참조하세요.
contentType
문자열: 게시 메시지의 내용을 설명하는 UTF-8으로 인코딩된 문자열입니다.
payLoadFormatIndicator
문자열: 페이로드가 UTF-8 형식으로 지정되었는지 여부를 나타내는 Enum 문자열 값입니다. 유효 값은 `UNSPECIFIED_BYTES` 및 `UTF8_DATA`입니다.
responseTopic
문자열: 응답 메시지의 주제 이름으로 사용되는 UTF-8 인코딩 문자열입니다. 응답 주제는 수신자가 요청-응답 흐름의 일부로 게시해야 하는 주제를 설명하는 데 사용됩니다. 주제에는 와일드카드 문자가 포함되어서는 안 됩니다.
correlationData
문자열: 요청 메시지 발신자가 응답 메시지를 수신할 때 어떤 요청에 대한 응답 메시지인지 식별하는 데 사용되는 base64 인코딩 이진 데이터입니다.
다음 표에는 `get_mqtt_property` 함수에 사용할 수 있는 함수 인수와 관련 반환 유형이 나와 있습니다.
**함수 인수**
| SQL | 반환되는 데이터 유형(있는 경우) | 반환되는 데이터 유형(없는 경우) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | 문자열(UNSPECIFIED\$1BYTES 또는 UTF8\$1DATA) | 문자열(UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | 문자열 | 정의되지 않음 |
| get\$1mqtt\$1property("response\$1topic") | 문자열 | 정의되지 않음 |
| get\$1mqtt\$1property("correlation\$1data") | base64로 인코딩된 문자열 | 정의되지 않음 |
| get\$1mqtt\$1property("some\$1invalid\$1name") | 정의되지 않음 | 정의되지 않음 |
다음 예제 규칙 SQL은 MQTT5 헤더 `contentType`, `payLoadFormatIndicator`, `responseTopic`, `correlationData` 중 하나를 참조합니다.
```
SELECT *, get_mqtt_property('content_type') as contentType,
get_mqtt_property('format_indicator') as payloadFormatIndicator,
get_mqtt_property('response_topic') as responseTopic,
get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'
```
## get\$1or\$1default(식, defaultValue)
지정된 경우 두 번째 파라미터의 기본값을 반환하고, 그렇지 않으면 첫 번째 파라미터의 표현식이 null, 정의되지 않음 또는 실패를 반환합니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
**중요**
`get_or_default`는 JSON이 아닌 페이로드를 있는 그대로 직접 지원하지 않습니다. 비 JSON 페이로드를 사용하는 경우 `encode` 또는 `decode` 함수를 사용합니다.
`get_or_default()`는 다음 파라미터를 사용합니다.
expression
[데이터 타입](iot-sql-data-types.md), , [함수](#iot-sql-functions), [리터럴](iot-sql-literals.md) [변수](iot-sql-set.md#iot-sql-set-usage), [중첩된 객체 쿼리](iot-sql-nested-queries.md)또는를 포함하는 모든 유효한 표현식입니다[JSON 확장](iot-sql-json.md).
defaultValue
(선택 사항) [데이터 타입](iot-sql-data-types.md), , [함수](#iot-sql-functions), [리터럴](iot-sql-literals.md) [변수](iot-sql-set.md#iot-sql-set-usage), [중첩된 객체 쿼리](iot-sql-nested-queries.md)또는를 포함하는 모든 유효한 표현식입니다[JSON 확장](iot-sql-json.md). 첫 번째 인수가 null, 정의되지 않음 또는 실패를 반환할 때마다 반환되는 값입니다.
get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf, machinelearning\$1predict와 같은 고객 소유 리소스에서 데이터를 가져오는 함수는 defaultValue 파라미터에 허용되지 않습니다.
다음 표에는 각 인수 및 관련 출력에 허용되는 함수 인수가 나와 있습니다.
| 첫 번째 인수 | 두 번째 인수 | 출력 |
| --- | --- | --- |
| 성공적인 평가 | 모든 값 또는 지정되지 않음 | 첫 번째 인수 값입니다. |
| 정의되지 않음, Null 또는 실패 | 정의되지 않음 또는 Null을 포함한 모든 값 | 두 번째 인수 값입니다. |
| 정의되지 않음, Null 또는 실패 | 지정되지 않음 | Undefined |
**예**:
예제 1:
다음 예제에서는 DynamoDB 테이블 또는 쿼리가 실패할 경우 defaultValue 값을 제공합니다.
```
SELECT
device_id,
get_or_default(
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME"),
{"mode": "standard", "timeout": 30, "enabled": true }
) as config
FROM 'device/telemetry'
```
예제 2:
다음 예제에서는 상태가 정의되지 않은 경우 안전한 기본값 "UNKNOWN"을 제공합니다.
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
예제 3:
다음 예제에서는 단일 파라미터와 함께 get\$1or\$1default를 사용하는 방법을 보여줍니다. 이는 명확한 기본값이 없을 수 있지만 규칙 실행이 실패하지 않도록 하려는 시나리오에서 유용합니다.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
DynamoDB 조회가 실패하면 규칙 실행이 실패하고 작업이 실행되지 않습니다. 대신 다음 SQL을 사용하는 경우:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
get\$1or\$1default 문은 로 평가`Undefined`되므로이 예제에서는 SELECT 문 전체가 로 평가`{}`되고 규칙 작업이 시도됩니다.
**중요**
이 함수를 사용할 때 보안을 유지하려면 다음 모범 사례를 따르는 것이 좋습니다.
기본값을 포함한 규칙 정의에서 하드 코딩된 보안 암호 사용 금지
민감한 정보 관리에 AWS Secrets Manager 사용
## get\$1registry\$1data(registryAPI, thingName, roleArn)
AWS IoT 규칙에서 AWS IoT 사물 레지스트리 데이터를 검색합니다. 레지스트리 데이터(예: 디바이스가 속한 속성, 사물 유형 및 사물 그룹)를 읽고이 정보를 사용하여 메시지를 필터링, 보강 또는 동적으로 라우팅할 수 있습니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
`get_registry_data()`는 다음 파라미터를 사용합니다.
registryAPI
호출 중인 레지스트리 API입니다. 유효 값은 `DescribeThing` 및 `ListThingGroupsForThing`입니다. 이러한 값은 상수 문자열이어야 합니다.
thingName
문자열: 레지스트리 데이터를 검색하려는 사물의 이름입니다.
roleArn
문자열: 호출 중인 API에 따라 `iot:DescribeThing` 권한 및/또는 `iot:ListThingGroupsForThing` 권한이 있는 역할 ARN입니다.
`get_registry_data` 함수의 응답 형식은 라는 레지스트리 API와 동일합니다. 자세한 내용은 [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) 및 [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs.
예제:
사물 유형 정보를 검색하여 사물 유형이 인 사물(사물 이름이 MQTT 클라이언트 ID와 일치)에 대한 AWS IoT Core 수명 주기 이벤트 메시지를 필터링할 수 있습니다`testenv`.
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
예제:
게이트웨이 디바이스에서 보낸 모든 메시지에 대해 사물 이름을 가진 디바이스`sensor1`의 사물 속성을 검색할 수 있습니다`gateway1`.
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**참고**
작업 및 오류 작업에 대해 SQL 문 및 대체 템플릿당 `get_registry_data()` 최대 한 번 호출할 수 있습니다.
## get\$1secret(secretId, secretType, key, roleArn)
[AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)에서 현재 버전의 보안 암호에 대한 암호화된 `SecretString` 또는 `SecretBinary` 필드의 값을 검색합니다. 보안 암호 생성 및 유지 관리에 대한 자세한 내용은 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), [UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html) 및 [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)를 참조하세요.
`get_secret()`는 다음 파라미터를 사용합니다.
SecretId
문자열: 검색할 보안 암호의 Amazon 리소스 이름(ARN) 또는 친숙한 이름입니다.
secretType
문자열: 보안 암호 유형입니다. 유효한 값: `SecretString` \$1 `SecretBinary`.
SecretString
+ APIs, AWS CLI또는 AWS Secrets Manager 콘솔을 사용하여 JSON 객체로 생성하는 보안 암호의 경우:
+ `key` 파라미터에 값을 지정한 경우, 이 함수는 지정된 키의 값을 반환합니다.
+ `key` 파라미터에 값을 지정하지 않은 경우 이 함수는 전체 JSON 객체를 반환합니다.
+ API, 또는 AWS CLI를 사용하여 JSON 객체로 생성하는 보안 암호의 경우:
+ `key` 파라미터에 값을 지정한 경우 이 함수는 예외와 함께 실패합니다.
+ `key` 파라미터에 값을 지정하지 않은 경우 이 함수는 보안 암호의 내용을 반환합니다.
SecretBinary
+ `key` 파라미터에 값을 지정한 경우 이 함수는 예외와 함께 실패합니다.
+ `key` 파라미터에 값을 지정하지 않은 경우 이 함수는 보안 암호 값을 Base64로 인코딩된 UTF-8 문자열로 반환합니다.
키
(선택 사항) 문자열: `SecretString` 보안 암호 필드에 저장된 JSON 객체 내부의 키 이름입니다. 전체 JSON 객체 대신 보안 암호에 저장된 키의 값만 검색하려는 경우 이 값을 사용합니다.
이 파라미터에 값을 지정하고 보안 암호의 `SecretString` 필드에 JSON 객체가 포함되어 있지 않으면 이 함수는 예외와 함께 실패합니다.
roleArn
문자열: `secretsmanager:GetSecretValue` 및 `secretsmanager:DescribeSecret` 권한을 갖는 역할 ARN입니다.
**참고**
이 함수는 항상 현재 버전의 보안 암호(`AWSCURRENT` 태그가 있는 버전)를 반환합니다 AWS IoT 규칙 엔진은 각 보안 암호를 최대 15분 동안 캐싱합니다. 따라서 규칙 엔진이 보안 암호를 업데이트하는 데 최대 15분이 걸릴 수 있습니다. 즉 AWS Secrets Manager, 업데이트 후 최대 15분 이내에 보안 암호를 검색하면이 함수가 이전 버전을 반환할 수 있습니다.
이 함수는 측정되지 않지만 AWS Secrets Manager 요금이 적용됩니다. 보안 암호 캐싱 메커니즘으로 인해 규칙 엔진은 때때로 AWS Secrets Manager을(를) 호출합니다. 규칙 엔진은 완전히 분산된 서비스이므로 15분 캐싱 기간 동안 규칙 엔진에서 여러 Secrets Manager API 호출을 볼 수 있습니다.
예시:
`get_secret` 함수를 다음 API 키 인증 예제와 같이 HTTPS 규칙 동작의 인증 헤더에서 사용할 수 있습니다.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
HTTPS 규칙 작업에 대한 자세한 내용은 [HTTP](https-rule-action.md) 단원을 참조하세요.
## get\$1thing\$1shadow(thingName, shadowName, roleArn)
지정된 사물의 지정된 섀도우를 반환합니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
thingName
문자열: 섀도우를 검색할 사물의 이름입니다.
shadowName
(선택 사항) 문자열: 섀도우의 이름입니다. 이 파라미터는 명명된 섀도우를 참조하는 경우에만 필요합니다.
roleArn
문자열: `iot:GetThingShadow` 권한을 갖는 역할 ARN입니다.
예시:
명명된 섀도우와 함께 사용할 경우 `shadowName` 파라미터를 제공합니다.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
명명되지 않은 섀도우와 함께 사용할 경우 `shadowName` 파라미터를 생략합니다.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties(userPropertyKey)
MQTT5에서 지원되는 속성 헤더 유형 중 하나인 사용자 속성을 참조합니다.
userProperty
문자열: 사용자 속성은 키-값 페어입니다. 이 함수는 키를 인수로 사용하여 관련 키와 일치하는 모든 값의 배열을 반환합니다.
**함수 인수**
메시지 헤더에 있는 다음 사용자 속성의 경우:
| Key(키) | 값 |
| --- | --- |
| some key | some value |
| a different key | a different value |
| some key | value with duplicate key |
다음 표에는 예상 SQL 동작이 나와 있습니다.
| SQL | 반환되는 데이터 형식 | 반환되는 데이터 값 |
| --- | --- | --- |
| get\$1user\$1properties('some key') | 문자열 배열 | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('other key') | 문자열 배열 | ['a different value'] |
| get\$1user\$1properties( ) | 키-값 페어 객체의 배열 | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('non-existent key') | 정의되지 않음 | |
다음 예제 규칙 SQL은 사용자 속성(MQTT5 속성 헤더 유형)을 페이로드로 참조합니다.
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## 해시 함수
AWS IoT 는 다음과 같은 해싱 함수를 제공합니다.
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
모든 해시 함수에는 문자열 인수 1개가 필요합니다. 결과는 해당 문자열의 해시된 값입니다. 표준 문자열 변환이 비 문자열 인수에 적용됩니다. 모든 해시 함수는 SQL 버전 2015-10-08 이상에서 지원합니다.
예시:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
두 번째 인수의 첫 번째 인덱스(0부터 시작)을 첫 번째 인수의 하위 문자열로 반환합니다. 두 인수 모두 문자열이 필요합니다. 문자열이 아닌 인수에는 표준 문자열 변환 규칙이 적용됩니다. 이 함수는 배열에는 적용되지 않고 문자열에만 적용됩니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
예시:
`indexof("abcd", "bc") ` = 1
## isNull()
인수가 `Null` 값이면 true를 반환합니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
예시:
`isNull(5) ` = false.
`isNull(Null) ` = true.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | true |
| Undefined | false |
## isUndefined()
인수가 `Undefined`이면 true를 반환합니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
예시:
`isUndefined(5) ` = false.
`isUndefined(floor([1,2,3]))) ` = true.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(String)
제공된 문자열의 문자 수를 반환합니다. 비 `String` 인수에는 표준 변환 규칙이 적용됩니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
예시:
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
인수의 자연 로그를 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `ln(e)` = 1.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 자연 로그. |
| Decimal | Decimal(배정밀도), 인수의 자연 로그. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 자연 로그. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## log(Decimal)
인수의 기수 10 로그를 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `log(100)` = 2.0.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 기수 10 로그. |
| Decimal | Decimal(배정밀도), 인수의 기수 10 로그. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 기수 10 로그. String을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## lower(String)
지정된 `String`의 소문자 버전을 반환합니다. 비 문자열 인수는 표준 변환 규칙을 사용하여 문자열로 변환됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`lower("HELLO")` = "hello".
`lower(["HELLO"])` = "[\$1"hello\$1"]".
## lpad(String, Int)
두 번째 인수로 지정된 수의 공백이 왼쪽에 추가된 `String` 인수를 반환합니다. `Int` 인수는 0부터 1000 사이여야 합니다. 제공된 값이 이 유효한 범위를 벗어날 경우 인수가 가장 가까운 유효한 값(0 또는 1000)으로 설정됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| String | Int | String. 제공된 Int와 동일한 수의 공백이 지정된 String 왼쪽에 추가됩니다. |
| String | Decimal | Decimal 인수는 가장 가까운 Int로 내림되고 String은 지정된 수의 공백이 왼쪽에 추가됩니다. |
| String | String | 두 번째 인수는 Decimal로 변환된 후 가장 가까운 Int로 내림되고, String은 지정된 수의 공백이 왼쪽에 추가됩니다. 두 번째 인수를 Int로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | Int/Decimal/String | 첫 번째 값이 표준 변환을 통해 String로 변환된 후, 이 String에 LPAD 함수가 적용됩니다. 변환이 불가능한 경우 결과는 Undefined입니다. |
| 임의의 값 | 기타 값 | Undefined. |
## ltrim(String)
제공된 `String`에서 모든 선행 공백(탭 및 공백)을 제거합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`Ltrim(" h i ")` = "hi ".
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | 모든 선행 공백이 제거된 Int의 String 표현. |
| Decimal | 모든 선행 공백이 제거된 Decimal의 String 표현. |
| Boolean | 모든 선행 공백이 제거된 부울('true' 또는 'false')의 String 표현. |
| String | 모든 선행 공백이 제거된 인수. |
| 배열 | 모든 선행 공백이 제거된 Array의 String표현(표준 변환 규칙 사용). |
| 객체 | 모든 선행 공백이 제거된 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
`machinelearning_predict` 함수를 사용하여 Amazon SageMaker AI 모델을 기반으로 MQTT 메시지의 데이터를 사용하여 예측합니다. SQL 버전 2015-10-08 이상에서 지원됩니다. `machinelearning_predict` 함수의 인수는 다음과 같습니다.
modelId
예측을 실행할 모델의 ID. 모델의 실시간 엔드포인트가 활성화되어야 합니다.
roleArn
`machinelearning:Predict` 및 `machinelearning:GetMLModel` 권한을 갖는 정책이 연결되고 예측을 실행할 모델에 대한 액세스를 허용하는 IAM 역할입니다.
record
SageMaker AI 예측 API로 전달할 데이터입니다. 이 인수는 단일 계층 JSON 객체로 표현되어야 합니다. 레코드가 다중 수준 JSON 객체일 경우 레코드가 값 직렬화를 통해 평면화됩니다. 예를 들어 다음 JSON이
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
다음과 같이 평면화됩니다.
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
이 함수는 다음 필드를 포함하는 JSON 객체를 반환합니다.
predictedLabel
모델을 기반으로 한 입력의 분류입니다.
details
다음 속성을 포함합니다.
PredictiveModelType
모델 유형입니다. 유효한 값은 REGRESSION, BINARY, MULTICLASS입니다.
Algorithm
SageMaker AI가 예측에 사용하는 알고리즘입니다. 값은 SGD이어야 합니다.
predictedScores
각 레이블에 해당하는 원시 분류 점수를 포함합니다.
predictedValue
SageMaker AI가 예측한 값입니다.
## mod(Decimal, Decimal)
첫 번째 인수를 두 번째 인수로 나눈 나머지를 반환합니다. [나머지(십진수, 십진수)](#iot-func-remainder)와 동일합니다. 또한 "%"를 동일한 모듈로 기능의 중위 연산자로 사용할 수도 있습니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `mod(8, 3)` = 2.
****
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int, 두 번째 인수를 법으로 하는 첫 번째 인수. |
| Int/Decimal | Int/Decimal | Decimal, 두 번째 피연산자를 법으로 하는 첫 번째 인수. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 10진수로 변환될 경우 결과는 두 번째 인수를 법으로 하는 첫 번째 인수입니다. 그렇지 않을 경우 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## nanvl(AnyValue, AnyValue)
유효한 `Decimal`일 경우 첫 번째 인수를 반환합니다. 그렇지 않으면 두 번째 인수를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `Nanvl(8, 3)` = 8.
****
| 인수 형식 1 | 인수 형식 2 | 출력 |
| --- | --- | --- |
| 정의되지 않음 | 임의의 값 | 두 번째 인수. |
| Null | 임의의 값 | 두 번째 인수. |
| Decimal(NaN) | 임의의 값 | 두 번째 인수. |
| Decimal(NaN 아님) | 임의의 값 | 첫 번째 인수. |
| 기타 값 | 임의의 값 | 첫 번째 인수. |
## newuuid()
임의의 16바이트 UUID를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
지정된 문자열의 UTF-8 인코딩 내 바이트 수를 반환합니다. 비 `String` 인수에는 표준 변환 규칙이 적용됩니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
예시:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
`parse_time` 함수는 타임스탬프를 사람이 읽을 수 있는 날짜/시간 형식으로 만듭니다. SQL 버전 2016-03-23 이상에서 지원됩니다. 타임스탬프 문자열을 밀리초로 변환하려면 [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch) 단원을 참조하세요.
`parse_time` 함수는 다음 인수를 사용합니다.
pattern
(문자열) [Joda-Time 형식](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)을 따르는 날짜/시간 패턴입니다.
timestamp
(Long) Unix Epoch부터의 시간을 밀리초로 변환한 시간입니다. [timestamp()](#iot-function-timestamp) 함수를 참조하세요.
timezone
(문자열) 형식 지정된 날짜/시간의 시간대입니다. 기본값은 "UTC"입니다. 이 함수는 [Joda-Time 시간대](http://joda-time.sourceforge.net/timezones.html)를 지원합니다. 이 인수는 선택 사항입니다.
예시:
이 메시지가 주제 'A/B'에 게시되면 페이로드 `{"ts": "1970.01.01 AD at 21:46:40 CST"}`가 S3 버킷으로 전송됩니다.
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", 100000000, 'America/Belize' ) as ts FROM 'A/B'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
이 메시지가 주제 'A/B'에 게시되면 페이로드 `{"ts": "2017.06.09 AD at 17:19:46 UTC"}`가 S3 버킷으로 전송됩니다.
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", timestamp() ) as ts FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
`parse_time()`은 대체 템플릿으로 사용할 수도 있습니다. 예를 들어 이 메시지가 주제 'A/B'에 게시되면 페이로드가 키 값이 "2017"인 S3 버킷으로 전송됩니다.
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT * FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "${parse_time('yyyy', timestamp(), 'UTC')}"
}
}],
"ruleName": "RULE_NAME"
}
}
```
## power(Decimal, Decimal)
두 번째 인수로 거듭제곱된 첫 번째 인수를 반환합니다. `Decimal`인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `power(2, 5)` = 32.0.
****
| 인수 형식 1 | 인수 형식 2 | 출력 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal(배정밀도), 두 번째 인수의 승수로 거듭제곱된 첫 번째 인수. |
| Int/Decimal/String | Int/Decimal/String | Decimal(배정밀도), 두 번째 인수의 승수로 거듭제곱된 첫 번째 인수. 모든 문자열은 10진수로 변환됩니다. String을(를) Decimal(으)로 변환하지 못한 경우 결과는 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## principal()
트리거하는 메시지가 게시된 방식에 따라 디바이스가 인증에 사용하는 위탁자를 반환합니다. 다음 표에서는 각 게시 방법과 프로토콜에 대해 반환된 보안 주체를 설명합니다.
****
| 메시지 게시 방법 | 프로토콜 | 자격 증명 유형 | 위탁자 |
| --- | --- | --- | --- |
| MQTT 클라이언트 | MQTT | X.509 디바이스 인증서 | X.509 인증서 지문 |
| AWS IoT 콘솔 MQTT 클라이언트 | MQTT | IAM 사용자 또는 역할 | iam-role-id:session-name |
| AWS CLI | HTTP | IAM 사용자 또는 역할 | userid |
| AWS IoT 디바이스 SDK | MQTT | X.509 디바이스 인증서 | X.509 인증서 지문 |
| AWS IoT 디바이스 SDK | MQTT over WebSocket | IAM 사용자 또는 역할 | userid |
다음은 `principal()`이 반환할 수 있는 다양한 유형의 값을 보여주는 예입니다.
+ X.509 인증서 지문: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ IAM 역할 ID 및 세션 이름: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ 사용자 ID 반환: `ABCD1EFG3HIJK2LMNOP5`
## rand()
0.0\$11.0 범위의 균등 분포된 배정밀도 의사 난수를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`rand()` = 0.8231909191640703
## regexp\$1matches(String, String)
문자열(첫 번째 인수)에 정규식(두 번째 인수)과 일치하는 항목이 포함되어 있으면 true를 반환합니다. 정규 표현식에서 `|` 코드를 사용하는 경우 `()`와 함께 사용해야 합니다.
예시:
`regexp_matches("aaaa", "a{2,}") ` = true.
`regexp_matches("aaaa", "b")` = false.
`regexp_matches("aaa", "(aaa|bbb)") ` = true.
`regexp_matches("bbb", "(aaa|bbb)") ` = true.
`regexp_matches("ccc", "(aaa|bbb)") ` = false.
**첫 번째 인수:**
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int의 String 표현. |
| Decimal | Decimal의 String 표현. |
| Boolean | 부울('true' 또는 'false')의 String 표현 |
| String | String. |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
*두 번째 인수:*
유효한 정규식이어야 합니다. 비 문자열 형식은 표준 변환 규칙을 사용하여 `String`으로 변환됩니다. 형식에 따라 결과 문자열이 유효한 정규식이 아닐 수도 있습니다. (변환된) 인수가 유효한 정규식이 아닐 경우 결과는 `Undefined`입니다.
## regexp\$1replace(String, String, String)
첫 번째 인수에서 모든 두 번째 인수(정규식)를 세 번째 인수로 대체합니다. "\$1"를 사용하여 캡처 그룹을 참조합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**첫 번째 인수:**
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int의 String 표현. |
| Decimal | Decimal의 String 표현. |
| Boolean | 부울('true' 또는 'false')의 String 표현 |
| String | 소스 값 |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
*두 번째 인수:*
유효한 정규식이어야 합니다. 비 문자열 형식은 표준 변환 규칙을 사용하여 `String`으로 변환됩니다. 형식에 따라 결과 문자열이 유효한 정규식이 아닐 수도 있습니다. (변환된) 인수가 유효한 정규식이 아닐 경우 결과는 `Undefined`입니다.
*세 번째 인수:*
유효한 정규식 대체 문자열이어야 합니다. (캡처 그룹을 참조할 수 있습니다.) 비 문자열 형식은 표준 변환 규칙을 사용하여 `String`으로 변환됩니다. (변환된) 인수가 유효한 정규식 대체 문자열이 아닐 경우 결과는 `Undefined`입니다.
## regexp\$1substr(String, String)
첫 번째 파라미터에서 두 번째 파라미터(정규식)의 첫 번째 일치를 찾습니다. "\$1"를 사용하여 캡처 그룹을 참조합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**첫 번째 인수:**
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int의 String 표현. |
| Decimal | Decimal의 String 표현. |
| Boolean | 부울('true' 또는 'false')의 String 표현 |
| String | String 인수. |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
*두 번째 인수:*
유효한 정규식이어야 합니다. 비 문자열 형식은 표준 변환 규칙을 사용하여 `String`으로 변환됩니다. 형식에 따라 결과 문자열이 유효한 정규식이 아닐 수도 있습니다. (변환된) 인수가 유효한 정규식이 아닐 경우 결과는 `Undefined`입니다.
## 나머지(십진수, 십진수)
첫 번째 인수를 두 번째 인수로 나눈 나머지를 반환합니다. [mod(Decimal, Decimal)](#iot-func-mod)와 동일합니다. 또한 "%"를 동일한 모듈로 기능의 중위 연산자로 사용할 수도 있습니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `remainder(8, 3)` = 2.
****
| 왼쪽 피연산자 | 오른쪽 피연산자 | 출력 |
| --- | --- | --- |
| Int | Int | Int, 두 번째 인수를 법으로 하는 첫 번째 인수. |
| Int/Decimal | Int/Decimal | Decimal, 두 번째 피연산자를 법으로 하는 첫 번째 인수. |
| String/Int/Decimal | String/Int/Decimal | 모든 문자열이 10진수로 변환될 경우 결과는 두 번째 인수를 법으로 하는 첫 번째 인수입니다. 그렇지 않을 경우 Undefined입니다. |
| 기타 값 | 기타 값 | Undefined. |
## 바꾸기(문자열, 문자열, 문자열)
첫 번째 인수에서 모든 두 번째 인수를 세 번째 인수로 대체합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**모든 인수**
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int의 String 표현. |
| Decimal | Decimal의 String 표현. |
| Boolean | 부울('true' 또는 'false')의 String 표현 |
| String | 소스 값 |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## rpad(String, Int)
두 번째 인수로 지정된 수의 공백이 오른쪽에 추가된 문자열 인수를 반환합니다. `Int` 인수는 0부터 1000 사이여야 합니다. 제공된 값이 이 유효한 범위를 벗어날 경우 인수가 가장 가까운 유효한 값(0 또는 1000)으로 설정됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| String | Int | 제공된 Int와 동일한 수의 공백이 String의 오른쪽에 추가됩니다. |
| String | Decimal | Decimal 인수는 가장 가까운 Int로 내림되고, 문자열은 제공된 Int와 동일한 수의 공백이 오른쪽에 추가됩니다. |
| String | String | 두 번째 인수는 Decimal로 변환된 후 가장 가까운 Int로 내림됩니다. Int 값과 동일한 수의 공백이 String의 오른쪽에 추가됩니다. |
| 기타 값 | Int/Decimal/String | 첫 번째 값이 표준 변환을 통해 String로 변환된 후, 이 String에 rpad 함수가 적용됩니다. 변환이 불가능한 경우 결과는 Undefined입니다. |
| 임의의 값 | 기타 값 | Undefined. |
## round(Decimal)
지정된 `Decimal`을 가장 가까운 `Int`로 반올림합니다. `Decimal`이 두 `Int` 값과 등거리일 경우(예: 0.5) `Decimal`은 올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `Round(1.2)` = 1.
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | 인수. |
| Decimal | Decimal은 가장 가까운 Int로 내림됩니다. |
| String | Decimal은 가장 가까운 Int로 내림됩니다. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 기타 값 | Undefined. |
## rtrim(String)
제공된 `String`에서 모든 후행 공백(탭 및 공백)을 제거합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`rtrim(" h i ")` = " h i"
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int의 String 표현. |
| Decimal | Decimal의 String 표현. |
| Boolean | 부울('true' 또는 'false')의 String 표현 |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined |
## sign(Decimal)
지정된 숫자의 부호를 반환합니다. 인수의 부호가 플러스일 경우 1이 반환됩니다. 인수의 부호가 마이너스일 경우 -1이 반환됩니다. 인수가 0일 경우 0이 반환됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Int, Int 값의 부호. |
| Decimal | Int, Decimal 값의 부호. |
| String | Int, Decimal 값의 부호. 문자열은 Decimal 값으로 변환된 후 Decimal 값의 부호가 반환됩니다. String을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. SQL 버전 2015-10-08 이상에서 지원됩니다. |
| 기타 값 | Undefined. |
## sin(Decimal)
숫자의 사인을 라디안 단위로 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `sin(0)` = 0.0
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 사인. |
| Decimal | Decimal(배정밀도), 인수의 사인. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 사인. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
숫자의 쌍곡사인을 반환합니다. `Decimal` 값은 함수 적용 전에 배정밀도로 반올림됩니다. 결과는 배정밀도의 `Decimal` 값입니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `sinh(2.3)` = 4.936961805545957
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 쌍곡사인. |
| Decimal | Decimal(배정밀도), 인수의 쌍곡사인. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 쌍곡사인. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## sourceip()
연결되는 디바이스 또는 라우터의 IP 주소를 검색합니다. 디바이스가 인터넷에 직접 연결되어 있는 경우 함수는 디바이스의 소스 IP 주소를 반환합니다. 디바이스가 인터넷에 연결되는 라우터에 연결되어 있는 경우 함수는 라우터의 소스 IP 주소를 반환합니다. SQL 버전 2016-03-23에서 지원됩니다. `sourceip()`는 파라미터를 사용하지 않습니다.
**중요**
디바이스의 퍼블릭 소스 IP 주소는 대개 마지막 Network Address Translation(NAT) Gateway(예: 인터넷 서비스 공급자의 라우터 또는 케이블 모뎀)의 IP 주소입니다.
예시:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
SQL 예시
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
AWS IoT Core 규칙 작업에서 sourceip() 함수를 사용하는 방법의 예:
**예제 1**.
다음 예시는 [DynamoDB 작업](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html)에서 () 함수를 [대체 템플릿](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)으로 호출하는 방법을 보여줍니다.
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${sourceip()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
**예제 2**.
다음 예시는 [대체 템플릿](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)을 사용하여 sourceip() 함수를 MQTT 사용자 속성으로 추가하는 방법을 보여줍니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "sourceip",
"value": "${sourceip()}"
}
]
}
}
}
]
}
}
```
메시지 브로커 및 [기본 수집](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html) 경로 모두에서 AWS IoT Core 규칙에 전달되는 메시지에서 소스 IP 주소를 검색할 수 있습니다. IPv4와 IPv6 메시지에 대한 소스 IP도 검색할 수 있습니다. 소스 IP는 다음과 같이 표시됩니다.
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**참고**
원본 소스 IP는 [재게시 작업](republish-rule-action.md)을 거쳐 전달되지 않습니다.
## substring(String, Int[, Int])
`String` 이후에 하나 또는 두 개의 `Int` 값이 필요합니다. `String` 및 단일 `Int` 인수일 경우 이 함수는 지정된 `Int` 인덱스(0부터 시작, 포함)부터 `String`의 끝까지의 지정된 `String`의 하위 문자열을 반환합니다. `String` 및 2개 `Int` 인수일 경우 이 함수는 첫 번째 `Int` 인덱스 인수(0부터 시작, 포함)부터 두 번째 `Int` 인덱스 인수(0부터 시작, 미포함)까지의 지정된 `String`의 하위 문자열을 반환합니다. 0보다 작은 인덱스는 0으로 설정됩니다. `String` 길이보다 큰 인덱스는 `String` 길이로 설정됩니다. 3개 인수 버전의 경우, 첫 번째 인덱스가 두 번째 인덱스보다 크거나 같을 경우 결과는 빈 `String`입니다.
제공된 인수가 (*String*, *Int*) 또는 (*String*, *Int*, *Int*)가 아닐 경우 인수에 표준 변환을 적용하여 올바른 형식으로 변환합니다. 형식을 변환할 수 없을 경우 함수 결과는 `Undefined`입니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`substring("012345", 0)` = "012345".
`substring("012345", 2)` = "2345".
`substring("012345", 2.745)` = "2345".
`substring(123, 2)` = "3".
`substring("012345", -1)` = "012345".
`substring(true, 1.2)` = "rue".
`substring(false, -2.411E247)` = "false".
`substring("012345", 1, 3)` = "12".
`substring("012345", -50, 50)` = "012345".
`substring("012345", 3, 1)` = "".
## sql\$1version()
이 규칙에 지정된 SQL 버전을 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`sql_version()` = "2016-03-23"
## sqrt(Decimal)
숫자의 제곱근을 반환합니다. `Decimal` 인수는 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `sqrt(9)` = 3.0.
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | 인수의 제곱근. |
| Decimal | 인수의 제곱근. |
| Boolean | Undefined. |
| String | 인수의 제곱근. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## startswith(String, String)
첫 번째 문자열 인수가 두 번째 문자열 인수로 시작하는지 여부를 나타내는 `Boolean`을 반환합니다. 인수가 `Null` 또는 `Undefined`일 경우 결과는 `Undefined`입니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`startswith("ranger","ran")` = true
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| String | String | 첫 번째 문자열이 두 번째 문자열로 시작하는지 여부. |
| 기타 값 | 기타 값 | 두 인수는 모두 표준 변환 규칙을 사용하여 문자열로 변환됩니다. 첫 번째 문자열이 두 번째 문자열로 시작하면 true를 반환합니다. 인수가 Null 또는 Undefined일 경우 결과는 Undefined입니다. |
## tan(Decimal)
숫자의 탄젠트를 라디안 단위로 반환합니다. `Decimal` 값은 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `tan(3)` = -0.1425465430742778
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 탄젠트. |
| Decimal | Decimal(배정밀도), 인수의 탄젠트. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 탄젠트. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## tanh(Decimal)
숫자의 쌍곡탄젠트를 라디안 단위로 반환합니다. `Decimal` 값은 함수 적용 전에 배정밀도로 반올림됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `tanh(2.3)` = 0.9800963962661914
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | Decimal(배정밀도), 인수의 쌍곡탄젠트. |
| Decimal | Decimal(배정밀도), 인수의 쌍곡탄젠트. |
| Boolean | Undefined. |
| String | Decimal(배정밀도), 인수의 쌍곡탄젠트. 문자열을 Decimal로 변환할 수 없는 경우 결과는 Undefined입니다. |
| 배열 | Undefined. |
| 객체 | Undefined. |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## time\$1to\$1epoch(String, String)
`time_to_epoch` 함수를 사용하여 타임스탬프 문자열을 Unix Epoch 시간의 밀리초 수로 변환합니다. SQL 버전 2016-03-23 이상에서 지원됩니다. 밀리초를 형식이 지정된 타임스탬프 문자열로 변환하려면 [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time) 단원을 참조하세요.
`time_to_epoch` 함수는 다음 인수를 사용합니다.
timestamp
(문자열) Unix Epoch 이후 밀리초로 변환할 타임스탬프 문자열입니다. 타임스탬프 문자열에서 시간대를 지정하지 않으면 함수는 UTC 시간대를 사용합니다.
pattern
(문자열) [JDK11 Time 형식](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html)을 따르는 날짜/시간 패턴입니다.
예시:
`time_to_epoch("2020-04-03 09:45:18 UTC+01:00", "yyyy-MM-dd HH:mm:ss VV")` = 1585903518000
`time_to_epoch("18 December 2015", "dd MMMM yyyy")` = 1450396800000
`time_to_epoch("2007-12-03 10:15:30.592 America/Los_Angeles", "yyyy-MM-dd HH:mm:ss.SSS z")` = 1196705730592
## timestamp()
AWS IoT 규칙 엔진에서 관찰한 대로 1970년 1월 1일 목요일 00:00:00 협정 세계시(UTC)부터 현재 타임스탬프를 밀리초 단위로 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예: `timestamp()` = `1481825251155`
## topic(Decimal)
규칙을 트리거한 메시지가 전송된 주제를 반환합니다. 지정된 파라미터가 없을 경우 전체 주제가 반환됩니다. `Decimal` 파라미터는 특정 주제 세그먼트를 지정하는데 사용되며, 첫 번째 세그먼트는 1로 지정됩니다. 주제 `foo/bar/baz`의 경우, topic(1)이 `foo`를 반환하고, topic(2)가 `bar`를 반환하는 식입니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
[Basic Ingest](iot-basic-ingest.md)를 사용하는 경우 주제(`$aws/rules/rule-name`)의 최초 접두사는 topic() 함수에 사용할 수 없습니다. 예를 들어 주제는 다음과 같습니다.
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
MQTT 메시지의 트레이스 ID(UUID), 또는 메시지가 MQTT를 통해 전송되지 않은 경우 `Undefined`를 반환합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Object, Array)
`Object` 파라미터에서 `Array` 파라미터의 지정된 변환 결과를 포함하는 객체 배열을 반환합니다.
SQL 버전 2016-03-23 이상에서 지원됩니다.
문자열
사용할 변환 모드입니다. 지원되는 변환 모드와 `Object` 및 `Array` 파라미터에서 `Result`를 생성하는 방법은 다음 표를 참조하세요.
객체
`Array`의 각 요소에 적용할 속성을 포함하는 객체입니다.
배열
`Object`의 속성이 적용되는 객체의 배열입니다.
이 배열의 각 객체는 함수의 응답에 있는 객체에 해당합니다. 함수 응답의 각 객체에는 원래 객체에 있는 속성과, `String`에 지정된 변환 모드에 의해 결정되어 `Object`에서 제공한 속성이 포함됩니다.
| `String` 파라미터 | `Object` 파라미터 | `Array` 파라미터 | 결과 |
| --- | --- | --- | --- |
| `enrichArray` | 객체 | 객체 배열 | 각 객체에 `Array` 파라미터의 요소 특성과 `Object` 파라미터의 특성이 포함된 객체 배열입니다. |
| 기타 값 | 임의의 값 | 임의의 값 | 정의되지 않음 |
**참고**
이 함수에 의해 반환된 배열은 128KiB로 제한됩니다.
### 변환 함수 예제 1
이 예제에서는 **transform()** 함수가 데이터 객체와 배열에서 단일 객체 배열을 생성하는 방법을 보여줍니다.
이 예에서 다음 메시지는 MQTT 주제 `A/B`에 게시됩니다.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
주제 규칙 작업에 대한 이 SQL 문은 `String` 값이 `enrichArray`인 **transform()** 함수를 사용합니다. 이 예에서 `Object`는 메시지 페이로드의 `attributes` 속성이고 `Array`는 세 개의 객체를 포함하는 `values` 배열입니다.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
메시지 페이로드를 수신하면 SQL 문은 다음과 같은 응답으로 평가됩니다.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### 변환 함수 예제 2
이 예에서는 **transform()** 함수가 리터럴 값을 사용하여 메시지 페이로드의 개별 속성을 포함시키고 이름을 바꾸는 방법을 보여줍니다.
이 예에서 다음 메시지는 MQTT 주제 `A/B`에 게시됩니다. 이는 [변환 함수 예제 1](#iot-func-transform-example1)에 사용된 것과 동일한 메시지입니다.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
주제 규칙 작업에 대한 이 SQL 문은 `String` 값이 `enrichArray`인 **transform()** 함수를 사용합니다. `Object` 함수의 **transform()**에는 메시지 페이로드의 값이 `key`인 `attributes.data1`라는 단일 속성이 있고 `Array`는 이전 예에서 사용된 것과 동일한 세 개의 객체를 포함하는 `values` 배열입니다.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
메시지 페이로드를 수신하면 이 SQL 문은 다음 응답으로 평가됩니다. 응답에서 `data1` 속성의 이름이 `key`로 지정되는 방법에 주목하세요.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### 변환 함수 예제 3
이 예에서는 중첩된 SELECT 절에서 **transform()** 함수를 사용하여 여러 속성을 선택하고 후속 처리를 위해 새 객체를 만드는 방법을 보여줍니다.
이 예에서 다음 메시지는 MQTT 주제 `A/B`에 게시됩니다.
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
이 변환 함수의 `Object`는 메시지의 `data2` 객체의 `a` 및 `b` 요소를 포함하는, SELECT 문에서 반환된 객체입니다. `Array` 파라미터는 원본 메시지에서 `data2.c` 배열의 두 객체로 구성됩니다.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
앞의 메시지를 사용하여 SQL 문은 다음 응답으로 평가됩니다.
```
[
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true,
"a": "first attribute",
"b": "second attribute"
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false,
"a": "first attribute",
"b": "second attribute"
}
]
```
이 응답에서 반환된 배열은 `batchMode`를 지원하는 주제 규칙 작업과 함께 사용할 수 있습니다.
## trim(String)
제공된 `String`에서 모든 선행 및 후행 공백을 제거합니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예제:
`Trim(" hi ") ` = "hi"
****
| 인수 유형 | 결과 |
| --- | --- |
| Int | 모든 선행 및 후행 공백이 제거된 Int의 String 표현. |
| Decimal | 모든 선행 및 후행 공백이 제거된 Decimal의 String 표현. |
| Boolean | 모든 선행 및 후행 공백이 제거된 Boolean("true" 또는 "false")의 String 표현. |
| String | 모든 선행 및 후행 공백이 제거된 String. |
| 배열 | Array의 String 표현(표준 변환 규칙 사용). |
| 객체 | 객체의 String 표현(표준 변환 규칙 사용). |
| Null | Undefined. |
| 정의되지 않음 | Undefined. |
## trunc(Decimal, Int)
첫 번째 인수를 두 번째 인수로 지정된 `Decimal` 자리수로 절사합니다. 두 번째 인수가 0보다 작을 경우 0으로 설정됩니다. 두 번째 인수가 34보다 클 경우 34로 설정됩니다. 끝의 0은 결과에서 제거됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2.31.
`trunc(2.888, 2)` = 2.88.
`trunc(2.00, 5)` = 2.
****
| 인수 형식 1 | 인수 형식 2 | 결과 |
| --- | --- | --- |
| Int | Int | 소스 값 |
| Int/Decimal | Int/Decimal | 첫 번째 인수가 두 번째 인수로 지정된 길이로 절사됩니다. 두 번째 인수는 Int가 아닐 경우 가까운 Int로 내림됩니다. |
| Int/Decimal/String | Int/Decimal | 첫 번째 인수가 두 번째 인수로 지정된 길이로 절사됩니다. 두 번째 인수는 Int가 아닐 경우 가까운 Int로 내림됩니다. String은 Decimal 값으로 변환됩니다. 문자열 변환이 실패할 경우 결과는 Undefined입니다. |
| 기타 값 | | Undefined. |
## upper(String)
지정된 `String`의 대문자 버전을 반환합니다. 비 `String` 인수는 표준 변환 규칙을 사용하여 `String`으로 변환됩니다. SQL 버전 2015-10-08 이상에서 지원됩니다.
예시:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# 리터럴
규칙 SQL의 SELECT 및 WHERE 절에서 리터럴 객체를 직접 지정할 수 있습니다. 이는 정보 전달에 유용할 수 있습니다.
**참고**
리터럴은 SQL 버전 2016-03-23 이상에서만 사용 가능합니다.
JSON 객체 구문을 사용합니다(키-값 페어, 쉼표로 구분, 키는 문자열이고 값은 JSON 값, 중괄호 \$1\$1로 묶임). 다음 예를 참조하세요.
주제 `topic/subtopic`에 게시된 수신 페이로드: `{"lat_long": [47.606,-122.332]}`
SQL 문: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
결과 송신 페이로드: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
규칙 SQL의 SELECT 및 WHERE 절에서 배열도 직접 지정할 수 있습니다. 그러면 정보를 그룹화할 수 있습니다. JSON 구문을 사용합니다(쉼표로 구분된 항목을 대괄호 []로 묶어 배열 리터럴을 생성). 다음 예를 참조하세요.
주제 `topic/subtopic`에 게시된 수신 페이로드: `{"lat": 47.696, "long": -122.332}`
SQL 문: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
결과 출력 페이로드: `{"lat_long": [47.606,-122.332]}`.
# Case 문
Case 문은 switch 문과 같은 분기 실행에 사용할 수 있습니다.
구문:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
표현식 *`v`*는 각 `WHEN` 절의 *`t[i]`* 값과 일치 여부가 평가됩니다. 일치가 발견될 경우 해당하는 *`r[i]`* 표현식이 `CASE` 문의 결과가 됩니다. `WHEN` 절은 일치하는 절이 두 개 이상 있는 경우 첫 번째 일치 절의 결과가 `CASE` 문의 결과가 되도록 순서대로 평가됩니다. 일치하는 항목이 없는 경우 `ELSE` 절의 *`r[e]`*가 결과입니다. 일치하는 항목과 `ELSE` 절이 없는 경우 결과는 `Undefined`입니다.
`CASE` 문에는 적어도 하나의 `WHEN` 절이 필요합니다. `ELSE` 절은 선택 사항입니다.
예:
주제 `topic/subtopic`에 게시된 수신 페이로드:
```
{
"color":"yellow"
}
```
SQL 문
```
SELECT CASE color
WHEN 'green' THEN 'go'
WHEN 'yellow' THEN 'caution'
WHEN 'red' THEN 'stop'
ELSE 'you are not at a stop light' END as instructions
FROM 'topic/subtopic'
```
결과 출력 페이로드:
```
{
"instructions":"caution"
}
```
**참고**
*`v`*가 `Undefined`일 경우 case 문의 결과는 `Undefined`입니다.
# JSON 확장
다음과 같은 ANSI SQL 구문 확장을 사용하여 중첩된 JSON 객체 작업을 용이하게 할 수 있습니다.
'.' 연산자
이 연산자는 포함된 JSON 객체의 멤버에 액세스하고 ANSI SQL 및 JavaScript와 동일하게 기능합니다. 다음 예를 참조하세요.
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
`topic/subtopic` 주제로 전송된 다음 메시지 페이로드에서 `foo` 객체의 `bar` 속성 값을 선택합니다.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
JSON 속성 이름에 하이픈 문자 또는 숫자 문자가 포함되어 있으면 '점' 표기법이 작동하지 않습니다. 대신, [가져오기 함수(get function)](iot-sql-functions.md#iot-sql-function-get)를 사용하여 속성 값을 추출할 수 있습니다.
이 예에서 다음 메시지는 `iot/rules` 주제로 전송됩니다.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
일반적으로, `my-key`의 값은 이 쿼리와 같이 식별됩니다.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
그러나 속성 이름 `my-key`에는 하이픈이 있고 `item2`에는 숫자 문자가 포함되어 있으면 [가져 오기 함수(get function)](iot-sql-functions.md#iot-sql-function-get)는 다음 쿼리에서 보여 주는 대로 사용해야 합니다.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*` 연산자
이 연산자는 ANSI SQL의 `*` 와일드카드와 동일하게 기능합니다. SELECT 절에서만 사용되며 메시지 데이터를 포함하는 새 JSON 객체를 생성합니다. 메시지 페이로드가 JSON 형식이 아닐 경우 `*`는 전체 메시지 페이로드를 원시 바이트로 반환합니다. 다음 예를 참조하세요.
```
SELECT * FROM 'topic/subtopic'
```
**속성 값에 함수 적용**
다음 예는 디바이스가 게시할 수 있는 JSON 페이로드입니다.
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
다음 예제는 JSON 페이로드의 속성 값에 함수를 적용합니다.
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
이 쿼리의 결과는 다음 JSON 객체입니다.
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# 대체 템플릿
대체 템플릿을 사용하여 규칙이 트리거되고 작업을 AWS IoT 수행할 때 반환되는 JSON 데이터를 보강할 수 있습니다. 대체 템플릿의 구문은 `${`*표현식*`}`입니다. 여기서 *표현식*은 SELECT 절, WHERE 절 및 AWS IoT 에서가 지원하는 모든 표현식일 수 있습니다[AWS IoT 규칙 작업](iot-rule-actions.md). 이 표현식을 규칙의 작업 필드에 연결하여 작업을 동적으로 구성할 수 있습니다. 실제로 이 기능은 작업의 정보를 대체합니다. 이러한 표현식에는 함수, 연산자, 그리고 원본 메시지 페이로드에서 제공되는 정보가 포함됩니다.
**중요**
대체 템플릿의 표현식은 'SELECT ...' 문과 별도로 평가되므로 AS 절을 사용하여 생성한 별칭은 참조할 수 없습니다. 원래 페이로드에 있는 정보, [함수](iot-sql-functions.md) 및 [연산자](iot-sql-operators.md)만 참조할 수 있습니다.
지원되는 표현식에 대한 자세한 내용은 [AWS IoT SQL 참조](iot-sql-reference.md) 섹션을 참조하세요.
다음 규칙 작업은 대체 템플릿을 지원합니다. 각 작업은 대체할 수 있는 다른 필드를 지원합니다.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch 경보](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Logs](cloudwatch-logs-rule-action.md)
+ [CloudWatch 지표](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [DynamoDBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [AWS IoT Events](iotevents-rule-action.md)
+ [AWS IoT SiteWise](iotsitewise-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [Location](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [재게시](republish-rule-action.md)
+ [S3](s3-rule-action.md)
+ [SNS](sns-rule-action.md)
+ [SQS](sqs-rule-action.md)
+ [단계 함수](stepfunctions-rule-action.md)
+ [Timestream](timestream-rule-action.md)
대체 템플릿은 규칙 내의 작업 파라미터에 나타납니다.
```
{
"sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
이 규칙이 `my/iot/topic`에 게시된 다음 JSON에 의해 트리거될 경우:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
그런 `${topic()}/republish`다음이 규칙은에서 AWS IoT 대체`my/iot/topic/republish`하는 다음 JSON을에 게시합니다.
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# 중첩된 객체 쿼리
중첩된 SELECT 절을 사용하여 배열 및 내부 JSON 객체에서 속성을 쿼리할 수 있습니다. SQL 버전 2016-03-23 이상에서 지원됩니다.
다음 MQTT 메시지를 살펴보겠습니다.
```
{
"e": [
{ "n": "temperature", "u": "Cel", "t": 1234, "v": 22.5 },
{ "n": "light", "u": "lm", "t": 1235, "v": 135 },
{ "n": "acidity", "u": "pH", "t": 1235, "v": 7 }
]
}
```
**Example**
다음 규칙을 사용하여 값을 새 배열로 변환할 수 있습니다.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
이 규칙은 다음과 같은 출력을 생성합니다.
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
동일한 MQTT 메시지에 대해, 다음 규칙을 사용하여 중첩된 객체에서 특정 값을 쿼리할 수도 있습니다.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
이 규칙은 다음과 같은 출력을 생성합니다.
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
더 복잡한 규칙으로 출력을 평면화할 수도 있습니다.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
이 규칙은 다음과 같은 출력을 생성합니다.
```
{
"temperature": 22.5
}
```
# 이진 페이로드 작업
메시지 페이로드를 JSON 객체가 아닌 원시 이진 데이터로 처리해야 하려면 \$1 연산자를 사용하여 SELECT 절에서 참조할 수 있습니다.
**Topics**
+ [이진 페이로드 예](#binary-payloads-examples)
+ [protobuf 메시지 페이로드 디코딩](#binary-payloads-protobuf)
## 이진 페이로드 예
\$1를 사용하여 메시지 페이로드를 원시 이진 데이터로 참조하면 규칙에 데이터를 추가할 수 있습니다. 비어 있거나 JSON 페이로드가 있는 경우 결과 페이로드에 규칙을 사용하여 데이터를 추가할 수 있습니다. 다음은 지원되는 `SELECT` 절의 예를 보여줍니다.
+ 다음 이진 페이로드에 \$1만 있는 다음 `SELECT` 절을 사용할 수 있습니다.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ 데이터를 추가하고 다음 `SELECT` 절을 사용할 수도 있습니다.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ 이진 페이로드에 이러한 `SELECT` 절을 사용할 수도 있습니다.
+ 다음은 WHERE 절에서 `device_type`을 참조합니다.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ 다음도 지원됩니다.
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
다음 규칙 작업은 이진 페이로드를 지원하지 않으므로 디코딩해야 합니다.
+ [Lambda 작업](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule)과 같은 일부 규칙 작업은 이진 페이로드 입력을 지원하지 않으므로 이진 페이로드를 디코딩해야 합니다. Lambda 규칙 작업은 base64로 인코딩되고 JSON 페이로드에 있는 경우 이진 데이터를 수신할 수 있습니다. 규칙을 다음으로 변경하여 이 작업을 수행할 수 있습니다.
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ SQL 문은 문자열을 입력으로 지원하지 않습니다. 문자열 입력을 JSON으로 변환하려면 다음 명령을 실행합니다.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## protobuf 메시지 페이로드 디코딩
[프로토콜 버퍼(protobuf)](https://developers.google.com/protocol-buffers)는 구조화된 데이터를 압축 이진 형식으로 직렬화하는 데 사용되는 오픈 소스 데이터 형식입니다. 이는 데이터를 네트워크를 통해 전송하거나 파일에 저장하는 데 사용됩니다. Protobuf를 사용하면 다른 메시징 형식보다 작은 패킷 크기와 빠른 속도로 데이터를 전송할 수 있습니다. AWS IoT Core 규칙은 디[코딩(값, 디decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수를 제공하여 protobuf를 지원하므로 protobuf 인코딩 메시지 페이로드를 JSON 형식으로 디코딩하고 다운스트림 서비스로 라우팅할 수 있습니다. 이 섹션에서는 AWS IoT Core 규칙에서 protobuf 디코딩을 구성하는 단계별 프로세스를 자세히 설명합니다.
**Topics**
+ [사전 조건](#binary-payloads-protobuf-prerequisites)
+ [설명자 파일 생성](#binary-payloads-protobuf-descriptor-steps)
+ [S3 버킷에 설명자 파일 업로드](#binary-payloads-protobuf-s3-steps)
+ [규칙에서 protobuf 디코딩 구성](#binary-payloads-protobuf-steps)
+ [제한 사항](#binary-payloads-protobuf-limitations)
+ [모범 사례](#binary-payloads-protobuf-bestpractices)
### 사전 조건
+ [프로토콜 버퍼(protobuf)](https://developers.google.com/protocol-buffers) 에 대한 기본적인 이해
+ 메시지 유형 및 관련 종속 항목을 정의하는 [`.proto` 파일](https://developers.google.com/protocol-buffers/docs/proto3)
+ 시스템에 [Protobuf 컴파일러(protoc)](https://github.com/protocolbuffers/protobuf/releases) 설치
### 설명자 파일 생성
설명자 파일이 이미 있는 경우 이 단계를 건너뛰어도 됩니다. 설명자 파일(`.desc`)은 protobuf 직렬화에 사용할 데이터 구조와 메시지 유형을 정의하는 텍스트 파일인 `.proto` 파일의 컴파일된 버전입니다. 설명자 파일을 생성하려면 `.proto` 파일을 정의하고 [protoc](https://github.com/protocolbuffers/protobuf/releases) 컴파일러를 사용하여 컴파일해야 합니다.
1. 메시지 유형을 정의하는 `.proto` 파일을 생성합니다. 예제 `.proto` 파일은 다음과 같습니다.
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
이 예제 `.proto` 파일에서는 proto3 구문을 사용하고 `Person`이라는 메시지 유형을 정의합니다. `Person` 메시지 정의는 3개의 필드(이름, ID 및 이메일)를 지정합니다. `.proto` 파일 메시지 형식에 대한 자세한 내용은 [Language Guide(proto3)](https://developers.google.com/protocol-buffers/docs/proto3)(언어 가이드(proto3))를 참조하세요.
1. [protoc](https://github.com/protocolbuffers/protobuf/releases) 컴파일러를 사용하여 `.proto` 파일을 컴파일하고 설명자 파일을 생성합니다. 설명자(`.desc`) 파일을 생성하는 예제 명령은 다음과 같습니다.
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
이 예제 명령은에 정의된 데이터 구조를 준수하는 protobuf 페이로드를 디코딩하는 데 사용할 수 있는 `.desc` AWS IoT Core 설명자 파일을 생성합니다`.proto`.
+ `--descriptor_set_out`
생성할 설명자 파일(`.desc`)의 이름을 지정합니다.
+ `--proto_path`
컴파일되는 파일에서 참조하는 가져온 `.proto` 파일의 위치를 지정합니다. 가져온 `.proto` 파일이 여러 개 있고 파일의 위치가 서로 다른 경우 플래그를 여러 번 지정할 수 있습니다.
+ `--include_imports`
가져온 `.proto` 파일도 컴파일하여 `.desc` 설명자 파일에 포함하도록 지정합니다.
+ `.proto`
컴파일할 `.proto` 파일의 이름을 지정합니다.
protoc 참조에 대한 자세한 내용은 [API 참조](https://developers.google.com/protocol-buffers/docs/reference/overview)를 참조하세요.
### S3 버킷에 설명자 파일 업로드
설명자 파일을 생성한 후 AWS API`.desc`, AWS SDK 또는 `.desc`를 사용하여 설명자 파일을 Amazon S3 버킷에 업로드합니다 AWS Management Console.
**중요 고려 사항**
+ 규칙을 구성하려는 AWS 리전 것과 동일한의 Amazon S3 버킷 AWS 계정 에 설명자 파일을 업로드해야 합니다.
+ S3`FileDescriptorSet`에서를 읽을 수 있는 AWS IoT Core 액세스 권한을 부여해야 합니다. S3 버킷에서 서버 측 암호화(SSE)가 비활성화되었거나 S3 버킷이 Amazon S3 관리형 키(SSE-S3)를 사용하여 암호화된 경우 추가 정책 구성이 필요하지 않습니다. 이 작업은 다음과 같은 예제 버킷 정책을 사용하여 수행할 수 있습니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ S3 버킷이 AWS Key Management Service 키(SSE-KMS)를 사용하여 암호화된 경우 S3 버킷에 액세스할 때 키를 사용할 수 있는 AWS IoT Core 권한을 부여해야 합니다. 키 정책에 다음 문을 추가하면 됩니다.
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### 규칙에서 protobuf 디코딩 구성
설명자 파일을 Amazon S3 버킷에 업로드한 후 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수를 사용하여 protobuf 메시지 페이로드 형식을 디코딩할 수 있는 [규칙](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)을 구성합니다. 자세한 함수 서명 및 예시는 *AWS IoT SQL 참조*의 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수 섹션에서 찾을 수 있습니다.
다음은 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) 함수를 사용하는 예시 SQL 표현식입니다.
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
이 예제 표현식에서는
+ [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수를 사용하여 `*`에서 참조하는 바이너리 메시지 페이로드를 디코딩합니다. 이는 바이너리 protobuf로 인코딩된 페이로드이거나 base64로 인코딩된 protobuf 페이로드를 나타내는 JSON 문자열일 수 있습니다.
+ 제공된 메시지 페이로드는 `PROTO_FILENAME.proto`에 정의된 `Person` 메시지 유형을 사용하여 인코딩됩니다.
+ `BUCKET NAME`이라는 Amazon S3 버킷에는 `PROTO_FILENAME.proto`에서 생성된 `FILENAME.desc`가 포함되어 있습니다.
구성을 완료한 후 규칙이 구독되는 주제에 메시지를 AWS IoT Core 에 게시합니다.
### 제한 사항
AWS IoT Core 규칙은 다음과 같은 제한 사항이 있는 protobuf를 지원합니다.
+ [대체 템플릿](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) 내에서 protobuf 메시지 페이로드를 디코딩하는 것은 지원되지 않습니다.
+ protobuf 메시지 페이로드를 디코딩할 때 단일 SQL 표현식 내에서 [decode SQL 함수](iot-sql-functions.md#iot-sql-decode-base64)를 최대 두 번 사용할 수 있습니다.
+ 최대 인바운드 페이로드 크기는 128KiB(1KiB=1024바이트)이고, 최대 아웃바운드 페이로드 크기는 128KiB이며, Amazon S3 버킷에 저장되는 `FileDescriptorSet` 객체의 최대 크기는 32KiB입니다.
+ SSE-C로 암호화된 Amazon S3 버킷은 지원되지 않습니다.
### 모범 사례
다음은 몇 가지 모범 사례와 문제 해결 팁입니다.
+ Amazon S3 버킷에 proto 파일을 백업합니다.
문제가 발생할 경우에 대비하여 proto 파일을 백업하는 것이 좋습니다. 예를 들어, protoc을 실행할 때 백업 없이 proto 파일을 잘못 수정하면 프로덕션 스택에 문제가 발생할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에는 여러 가지가 있습니다. 예를 들어, [S3 버킷에서 버전 관리를 사용](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html)할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에 대한 자세한 내용은 *[Amazon S3 개발자 안내서](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*를 참조하세요.
+ 로그 항목을 보도록 AWS IoT 로깅을 구성합니다.
CloudWatch에서 계정의 AWS IoT 로그를 확인할 수 있도록 AWS IoT 로깅을 구성하는 것이 좋습니다. 규칙의 SQL 쿼리가 외부 함수를 호출하면 AWS IoT Core 규칙은 실패 문제를 해결하는 데 도움이 `FunctionExecution`되는 이유 필드가 포함된 `eventType`의를 사용하여 로그 항목을 생성합니다. 발생할 수 있는 오류에는 Amazon S3 객체를 찾을 수 없거나 protobuf 파일 설명자가 잘못된 것 등이 포함됩니다. AWS IoT 로깅을 구성하고 로그 항목을 확인하는 방법에 대한 자세한 내용은 [AWS IoT 로깅 구성](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) 및 [규칙 엔진 로그 항목](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec)을 참조하세요.
+ 새 객체 키를 사용하여 `FileDescriptorSet`를 업데이트하고 규칙에서 객체 키를 업데이트합니다.
업데이트된 설명자 파일을 Amazon S3 버킷에 업로드하여 `FileDescriptorSet`를 업데이트할 수 있습니다. `FileDescriptorSet`에 대한 업데이트 내용이 반영되는 데 최대 15분이 걸릴 수 있습니다. 이러한 지연을 피하려면 새 객체 키를 사용하여 업데이트된 `FileDescriptorSet`를 업로드하고 규칙에서 객체 키를 업데이트하는 것이 좋습니다.
# SQL 버전
AWS IoT 규칙 엔진은 SQL과 유사한 구문을 사용하여 MQTT 메시지에서 데이터를 선택합니다. SQL 문은 규칙을 설명하는 JSON 문서에서 `awsIotSqlVersion` 속성으로 지정된 SQL 버전을 기반으로 해석됩니다. JSON 규칙 문서의 구조에 대한 자세한 내용은 [규칙 생성](iot-create-rule.md) 섹션을 참조하세요. `awsIotSqlVersion` 속성을 사용하면 사용할 AWS IoT SQL 규칙 엔진 버전을 지정할 수 있습니다. 새 버전이 개발될 경우 이전 버전을 계속 사용할 수도 있고 새 버전을 사용하도록 규칙을 변경할 수도 있습니다. 현재 규칙은 규칙 생성 당시의 버전을 계속 사용합니다.
다음 JSON 예제는 `awsIotSqlVersion` 속성을 사용하여 SQL 버전을 지정하는 방법을 보여줍니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
AWS IoT 는 현재 다음 SQL 버전을 지원합니다.
+ `2016-03-23` – 2016년 3월 23일 작성된 SQL 버전(권장됨).
+ `2015-10-08` – 2015년 10월 8일 작성된 원래 SQL 버전.
+ `beta` – 최신의 베타 SQL 버전. 이 버전으로 인해 규칙에 영향을 미치는 변화가 발생할 수 있습니다.
## 2016-03-23 SQL 규칙 엔진 버전의 새로운 기능
+ 중첩된 JSON 객체 선택에 대한 수정 사항
+ 배열 쿼리에 대한 수정 사항
+ 객체 내 쿼리 지원. 자세한 내용은 [중첩된 객체 쿼리](iot-sql-nested-queries.md) 단원을 참조하세요.
+ 최상위 객체로 배열 출력 지원
+ JSON 및 비 JSON 형식 데이터에 적용할 수 있는 `encode(value, encodingScheme)` 기능 추가 자세한 내용은 [encode 함수](iot-sql-functions.md#iot-sql-encode-payload)를 참조하세요.
### 최상위 객체로 `Array` 출력
이 기능을 사용하여 배열을 최상위 객체로 반환할 수 있습니다. 예를 들어 다음과 같은 MQTT 메시지가 있다고 가정합니다.
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
그리고 다음과 같은 규칙이 있다고 가정합니다.
```
SELECT VALUE arr FROM 'topic'
```
이 규칙은 다음과 같은 출력을 생성합니다.
```
[1,2,3,4]
```