기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 에 대한 규칙 AWS IoT
규칙은 디바이스가 상호 작용할 수 있는 기능을 제공합니다 AWS 서비스. MQTT 주제 스트림을 기반으로 규칙이 분석되고 작업이 수행됩니다. 규칙을 사용하여 다음 작업을 지원할 수 있습니다.
+ 디바이스로부터 수신한 데이터를 보강 또는 필터링합니다.
+ 디바이스로부터 수신한 데이터를 Amazon DynamoDB 데이터베이스에 기록합니다.
+ Amazon S3에 파일을 저장합니다.
+ Amazon SNS를 사용하는 모든 사용자에게 푸시 알림을 발송합니다.
+ Amazon SQS 대기열에 데이터를 게시합니다.
+ Lambda 함수를 호출하여 데이터를 추출합니다.
+ Amazon Kinesis를 사용하여 다수의 디바이스로부터 메시지를 처리합니다.
+ Amazon OpenSearch Service로 데이터를 전송합니다.
+ CloudWatch 지표를 수집합니다.
+ CloudWatch 경보를 변경합니다.
+ 기계 학습(ML) 모델을 기반으로 한 예측을 위해 MQTT 메시지의 데이터를 Amazon SageMaker AI에 전송합니다.
+ Salesforce IoT 입력 스트림에 메시지 전송
+ Step Functions 상태 머신 프로세스를 시작합니다.
+ 메시지 데이터를 AWS IoT Events 입력으로 전송합니다.
+ AWS IoT SiteWise의 자산 속성에 메시지 데이터를 전송합니다.
+ 메시지 데이터를 웹 애플리케이션 또는 서비스에 전송합니다.
규칙은 [디바이스 통신 프로토콜](protocols.md)에서 지원하는 게시/구독 프로토콜을 통과하는 MQTT 메시지를 사용할 수 있습니다. [기본 수집](iot-basic-ingest.md) 기능을 사용하여 [메시징 비용](https://aws.amazon.com/iot-core/pricing/) 없이 디바이스 데이터를 이전에 AWS 서비스 나열된 로 안전하게 전송할 수도 있습니다. [Basic Ingest](iot-basic-ingest.md)(기본 수집) 기능은 수집 경로에서 게시/구독 메시지 브로커를 제거해 데이터 흐름을 최적화합니다. 따라서의 보안 및 데이터 처리 기능을 유지하면서 비용 효율적입니다 AWS IoT.
AWS IoT 가 이러한 작업을 수행하기 전에 사용자를 대신하여 리소스에 액세스할 수 AWS 있는 권한을 부여해야 합니다. 작업이 수행되면 AWS 서비스 사용하는에 대한 표준 요금이 발생합니다.
**Topics**
+ [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md)
+ [역할 전달 권한](pass-role.md)
+ [AWS IoT 규칙 생성](iot-create-rule.md)
+ [AWS IoT 규칙 관리](iot-managae-rule.md)
+ [AWS IoT 규칙 작업](iot-rule-actions.md)
+ [규칙 문제 해결](#iot-troubleshoot-rule)
+ [AWS IoT 규칙을 사용하여 교차 계정 리소스에 액세스](accessing-cross-account-resources-using-rules.md)
+ [오류 처리(오류 작업)](rule-error-handling.md)
+ [Basic Ingest를 통한 메시징 비용 절감](iot-basic-ingest.md)
+ [AWS IoT SQL 참조](iot-sql-reference.md)
# AWS IoT 규칙에 필요한 액세스 권한 부여
IAM 역할을 사용하여 각 규칙이 액세스할 수 있는 AWS 리소스를 제어합니다. 규칙을 생성하기 전에 필요한 AWS 리소스에 대한 액세스를 허용하는 정책이 있는 IAM 역할을 생성해야 합니다. 규칙을 구현할 때이 역할을 수 AWS IoT 임합니다.
**다음 단계를 완료하여 AWS IoT 규칙에 필요한 액세스 권한을 부여하는 IAM 역할 및 AWS IoT 정책을 생성합니다(AWS CLI).**
1. 역할을 수임할 수 있는 AWS IoT 권한을 부여하는 다음 신뢰 정책 문서를 이라는 파일에 저장합니다`iot-role-trust.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
[create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) 명령을 사용하여 `iot-role-trust.json` 파일을 지정하는 IAM 역할을 생성합니다.
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
이 명령의 출력은 다음과 같습니다.
```
{
"Role": {
"AssumeRolePolicyDocument": "url-encoded-json",
"RoleId": "AKIAIOSFODNN7EXAMPLE",
"CreateDate": "2015-09-30T18:43:32.821Z",
"RoleName": "my-iot-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
```
1. 다음 JSON을 `my-iot-policy.json`이라는 파일에 저장합니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
이 JSON은 AWS IoT 관리자에게 DynamoDB에 대한 액세스 권한을 부여하는 정책 문서의 예입니다.
[create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) 명령을 사용하여 역할을 수임하고 `my-iot-policy.json` 파일을 전달할 때 AWS 리소스에 대한 AWS IoT 액세스 권한을 부여합니다.
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
정책 AWS 서비스 에서에 대한 액세스 권한을 부여하는 방법에 대한 자세한 내용은 섹션을 AWS IoT참조하세요[AWS IoT 규칙 생성](iot-create-rule.md).
[create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) 명령의 출력에는 정책의 ARN이 포함됩니다. 역할에 정책을 연결합니다.
```
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
```
1. [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) 명령을 사용하여 정책을 역할에 연결합니다.
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## 규칙 엔진 액세스 취소
규칙 엔진 액세스를 즉시 취소하려면 다음을 수행합니다.
1. [신뢰 정책](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)에서 iot.amazonaws.com 제거
1. 단계에 따라 [IoT 역할 세션을 취소](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# 역할 전달 권한
규칙의 작업에 지정된 리소스에 액세스할 권한을 부여하는 IAM 역할은 규칙 정의의 일부입니다. 규칙 작업이 호출되면 규칙 엔진이 해당 역할을 수임합니다. 역할은 규칙 AWS 계정 과 동일한에 정의되어야 합니다.
규칙을 생성 또는 교체하는 것은 규칙 엔진에 역할을 전달하는 것과 동일한 것입니다. 이 작업을 실행하려면 `iam:PassRole` 권한이 필요합니다. 이 권한이 있는지 확인하려면 `iam:PassRole` 권한을 부여하는 정책을 생성하여 IAM 사용자에게 연결합니다. 다음 정책은 역할에 `iam:PassRole` 권한을 허용하는 방법을 보여줍니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
이 정책 예제에서는 역할 `myRole`에 대한 `iam:PassRole` 권한이 부여됩니다. 역할은 역할의 ARN을 사용하여 지정됩니다. 이 정책을 IAM 사용자 또는 사용자가 속한 역할에 연결합니다. 자세한 내용은 [관리형 정책 작업](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html)을 참조하세요.
**참고**
Lambda 함수는 리소스 기반 정책을 사용합니다. 이때 정책은 Lambda 함수 자체에 직접 연결됩니다. Lambda 함수를 호출하는 규칙을 생성하는 경우 역할은 전달하지 않습니다. 따라서 규칙을 생성하는 사용자에게 `iam:PassRole` 권한이 필요하지 않습니다. Lambda 함수 권한 부여에 대한 자세한 내용은 [리소스 정책을 사용하여 권한 부여(Granting Permissions Using a Resource Policy)](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy) 단원을 참조하세요.
# AWS IoT 규칙 생성
연결된 사물의 데이터를 라우팅하여 다른 AWS 서비스와 상호 작용하는 AWS IoT 규칙을 생성할 수 있습니다. AWS IoT 규칙은 다음 구성 요소로 구성됩니다.
**규칙의 구성 요소**
| 구성 요소 | 설명 | 필수 또는 선택 |
| --- | --- | --- |
| 규칙 이름 | 규칙의 이름입니다. 규칙 이름에 개인 식별 정보를 사용하지 않는 것이 좋습니다. | 필수 사항입니다. |
| 규칙 설명 | 규칙에 대한 텍스트 설명입니다. 규칙 설명에 개인 식별 정보를 사용하지 않는 것이 좋습니다. | 선택 사항. |
| SQL 문 | MQTT 주제에서 수신된 메시지를 필터링하고 데이터를 다른 위치로 푸시하기 위해 간소화된 SQL 구문입니다. 자세한 내용은 [AWS IoT SQL 참조](iot-sql-reference.md) 단원을 참조하십시오. | 필수 사항입니다. |
| SQL 버전 | 규칙을 평가할 때 사용할 SQL 규칙의 버전입니다. 이 속성은 선택 사항이지만 SQL 버전을 지정하는 것이 좋습니다. AWS IoT Core 콘솔은 `2016-03-23` 기본적으로이 속성을 로 설정합니다. AWS CLI 명령 또는 CloudFormation 템플릿과 같이이 속성이 설정되지 않은 경우 `2015-10-08`가 사용됩니다. 자세한 내용은 [SQL 버전](iot-rule-sql-version.md) 단원을 참조하십시오. | 필수 사항입니다. |
| 하나 이상의 작업 | 작업은 규칙을 실행할 때 AWS IoT 수행됩니다. 예를 들어 DynamoDB 테이블에 데이터를 삽입하거나, Amazon S3 버킷에 데이터를 쓰거나, Amazon SNS 주제에 게시하거나, Lambda 함수를 호출할 수 있습니다. | 필수 사항입니다. |
| 오류 작업 | 작업은 규칙의 작업을 수행할 수 없을 때 AWS IoT 수행됩니다. | 선택 사항. |
AWS IoT 규칙을 생성하기 전에 필요한 AWS 리소스에 대한 액세스를 허용하는 정책을 사용하여 IAM 역할을 생성해야 합니다. 규칙을 구현할 때는이 역할을 수 AWS IoT 임합니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html) 및 [역할 권한 전달을](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html) 참조하세요.
규칙을 생성할 때 주제에 얼마나 많은 데이터를 게시하는지 알고 있어야 합니다. 와일드카드 주제 패턴을 포함하는 규칙을 만들면 메시지의 많은 부분과 매칭될 수 있습니다. 이 경우 대상 작업에 사용되는 AWS 리소스의 용량을 늘려야 할 수 있습니다. 중복 처리를 방지하고 비용을 절감하려면, 재게시 규칙에서 와일드카드 주제 패턴을 피하는 것이 좋습니다.
**참고**
규칙 생성 및 업데이트는 관리자 수준 작업입니다. 규칙을 생성 또는 업데이트할 수 있는 권한이 있는 모든 사용자는 규칙이 처리한 데이터에 액세스할 수 있습니다.
## 규칙 생성(콘솔)
**규칙(AWS Management Console)을 생성하려면**
[AWS Management Console](https://console.aws.amazon.com//iot/home#/home) 명령을 사용하여 규칙을 생성합니다.
1. [AWS IoT 콘솔](https://console.aws.amazon.com//iot/home#/home)을 엽니다.
1. 왼쪽 탐색에서 **관리** 섹션에서 **메시지 라우팅**을 선택합니다. 그런 다음 **규칙**을 선택합니다.
1. **규칙** 페이지에서 **규칙 생성**을 선택합니다.
1. **규칙 속성 지정** 페이지에서 규칙의 이름을 입력합니다. **규칙 설명** 및 **태그**는 선택 사항입니다. **다음**을 선택합니다.
1. **SQL 문 구성** 페이지에서 SQL 버전을 선택하고 SQL 문을 입력합니다. 예제 SQL 문은 `SELECT temperature FROM 'iot/topic' WHERE temperature > 50`일 수 있습니다. 자세한 내용은 [SQL versions](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html) 및 [AWS IoT SQL reference](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html)를 참조하세요.
1. **규칙 작업 연결** 페이지에서 다른 AWS 서비스로 데이터를 라우팅하는 규칙 작업을 추가합니다.
1. **규칙 작업**의 드롭다운 목록에서 규칙 작업을 선택합니다. 예를 들어 **Kinesis Stream**을 선택할 수 있습니다. 규칙 작업에 대한 자세한 내용은 [AWS IoT rule actions](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html)를 참조하세요.
1. 선택한 규칙 작업에 따라 관련 구성 세부 정보를 입력합니다. 예를 들어 **Kinesis Stream**을 선택하는 경우 데이터 스트림 리소스를 선택하거나 생성하고 선택적으로 스트림의 샤드별로 데이터를 그룹화하는 데 사용되는 **파티션 키**와 같은 구성 세부 정보를 입력해야 합니다.
1. **IAM 역할**에서 엔드포인트에 대한 AWS IoT 액세스 권한을 부여할 역할을 선택하거나 생성합니다. AWS IoT 는 선택한 IAM 역할 `aws-iot-rule` 아래에 접두사가 인 정책을 자동으로 생성합니다. **보기**를 선택하여 IAM 콘솔에서 IAM 역할과 정책을 볼 수 있습니다. **오류 작업**은 선택 사항입니다. [Error handling (error action)](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html)에서 자세한 내용을 확인할 수 있습니다. 규칙의 IAM 역할 생성에 대한 자세한 내용은 [Grant a rule the access it requires](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html)를 참조하세요. **다음**을 선택합니다.
1. **검토 및 생성** 페이지에서 모든 구성을 검토하고 필요한 경우 편집합니다. **생성(Create)**을 선택합니다.
규칙을 성공적으로 생성하면 규칙 페이지에 나열된 **규칙**이 표시됩니다. 규칙을 선택하여 규칙을 보고, 규칙을 편집하고, 규칙을 비활성화하고, 규칙을 삭제할 수 있는 **세부 정보** 페이지를 열 수 있습니다.
## 규칙 생성(CLI)
**규칙(AWS CLI)을 생성하려면**
규칙을 생성하려면 [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) 명령을 사용합니다.
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
다음 예제는 `iot/test` 주제에 전송된 모든 메시지를 지정된 DynamoDB 테이블에 삽입하는 규칙을 포함한 페이로드 파일입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 DynamoDB 테이블에 쓸 수 있는 AWS IoT 권한을 부여합니다.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my-dynamodb-table",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"hashKeyField": "topic",
"hashKeyValue": "${topic(2)}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}"
}
}
]
}
```
다음 예제는 `iot/test` 주제에 전송된 모든 메시지를 지정된 S3 버킷에 삽입하는 규칙을 포함한 페이로드 파일입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 Amazon S3 버킷에 쓸 수 있는 AWS IoT 권한을 부여합니다.
```
{
"awsIotSqlVersion": "2016-03-23",
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "amzn-s3-demo-bucket",
"key": "myS3Key"
}
}
]
}
```
다음 예제는 데이터를 Amazon OpenSearch Service로 푸시하는 규칙을 포함하는 페이로드 파일입니다.
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}"
}
}
]
}
```
다음 예제는 Lambda 함수를 호출하는 규칙을 포함한 페이로드 파일입니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
다음 예제는 Amazon SNS 주제에 게시하는 규칙을 포함한 페이로드 파일입니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
다음 예제는 다른 MQTT 주제에 재게시하는 규칙을 포함한 페이로드 파일입니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
다음 예제는 데이터를 Amazon Data Firehose 스트림으로 푸시하는 규칙을 포함한 페이로드 파일입니다.
```
{
"sql": "SELECT * FROM 'my-topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"deliveryStreamName": "my-stream-name"
}
}
]
}
```
다음 예제는 MQTT 페이로드의 데이터가 1로 분류될 경우 Amazon SageMaker AI `machinelearning_predict` 함수를 사용하여 주제에 재게시하는 규칙을 포함한 예시 페이로드 파일입니다.
```
{
"sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"topic": "my-mqtt-topic"
}
}
]
}
```
다음은 Salesforce IoT 클라우드 입력 스트림에 메시지를 게시하는 규칙을 가진 페이로드 파일의 예입니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
```
다음 예제는 Step Functions 상태 시스템 실행을 시작하는 규칙을 포함한 페이로드 파일입니다.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myCoolStateMachine",
"executionNamePrefix": "coolRunning",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
# AWS IoT 규칙 관리
다음 작업을 사용하여 AWS IoT 규칙을 관리할 수 있습니다.
**Topics**
+ [규칙 태그 지정](#iot-create-rule-tagging)
+ [규칙 보기](#iot-view-rules)
+ [규칙 삭제](#iot-delete-rule)
## 규칙 태그 지정
새 규칙이나 기존 규칙에 다른 특수성을 더하기 위해 태깅을 적용할 수 있습니다. 태그 지정은 규칙의 키-값 페어를 활용하여 규칙이 AWS IoT 리소스 및 서비스에 적용되는 방식과 위치를 더 잘 제어할 수 있습니다. 예를 들어, 규칙이 베타 환경에만 적용되도록 범위를 제한하여 릴리스 전 테스팅(`Key=environment, Value=beta`)을 하거나 특정 엔드포인트에서 `iot/test` 주제로 전송된 모든 메시지를 캡처하여 Amazon S3 버킷에 저장하도록 할 수 있습니다.
### IAM 정책 예시
규칙에 태깅 권한을 부여하는 방법을 보여주는 예로, 규칙을 만들고 베타 환경에만 태깅하기 위해 다음 명령을 실행하는 사용자를 생각해 보세요.
이 예에서 다음과 같이 대체합니다.
+ 규칙 이름이 포함된 *MyTopicRuleName*
+ 정책 문서의 이름이 포함된 *myrule.json*
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
이 예시에서는 다음 IAM 정책을 사용해야 합니다.
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
위 예시는 베타 환경에만 적용되는 새로 만든 규칙인 `MyTopicRuleName`을 보여줍니다. `MyTopicRuleName`이 강조된 정책 설명의 `iot:TagResource`는 `MyTopicRuleName` 생성 또는 업데이트 시 태깅을 허용합니다. 규칙을 만들 때 사용되는 `--tags "environment=beta"` 파라미터는 `MyTopicRuleName`의 범위를 베타 환경으로만 제한합니다. `--tags "environment=beta"` 파라미터를 제거하면 `MyTopicRuleName`이 모든 환경에 적용됩니다.
AWS IoT 규칙에 대한 IAM 역할 및 정책 생성에 대한 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 섹션을 참조하세요.
리소스 태깅에 대한 자세한 내용은 [AWS IoT 리소스에 태그 지정](tagging-iot.md) 섹션을 참조하세요.
## 규칙 보기
규칙을 나열하려면 [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html) 명령을 사용합니다.
```
aws iot list-topic-rules
```
규칙에 대한 정보를 가져오려면 [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html) 명령을 사용합니다.
```
aws iot get-topic-rule --rule-name myrule
```
## 규칙 삭제
규칙 사용을 마치면 이를 삭제할 수 있습니다.
**규칙(AWS CLI)을 삭제하려면**
규칙을 삭제하려면 [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html) 명령을 사용합니다.
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT 규칙 작업
AWS IoT 규칙 작업은 규칙이 호출될 때 수행할 작업을 지정합니다. Amazon DynamoDB 데이터베이스로 데이터를 전송하고, Amazon Kinesis Data Streams로 데이터를 전송하고, 함수를 AWS Lambda 호출하는 작업을 정의할 수 있습니다.는 작업의 서비스를 사용할 수 AWS 리전 있는에서 다음 작업을 AWS IoT 지원합니다.
| 규칙 작업 | 설명 | API의 이름 |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Apache Kafka 클러스터에 메시지를 전송합니다. | kafka |
| [CloudWatch 경보](cloudwatch-alarms-rule-action.md) | Amazon CloudWatch 경보 상태를 변경합니다. | cloudwatchAlarm |
| [CloudWatch Logs](cloudwatch-logs-rule-action.md) | Amazon CloudWatch Logs로 메시지를 전송합니다. | cloudwatchLogs |
| [CloudWatch 지표](cloudwatch-metrics-rule-action.md) | CloudWatch 지표에 메시지를 전송합니다. | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | DynamoDB 테이블에 메시지를 전송합니다. | dynamoDB |
| [DynamoDBv2](dynamodb-v2-rule-action.md) | 메시지 데이터를 DynamoDB 테이블의 여러 열에 전송합니다. | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | OpenSearch 엔드포인트에 메시지를 전송합니다. | OpenSearch |
| [HTTP](https-rule-action.md) | HTTPS 엔드포인트에 메시지를 게시합니다. | http |
| [AWS IoT Events](iotevents-rule-action.md) | AWS IoT Events 입력에 메시지를 전송합니다. | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | 메시지 데이터를 AWS IoT SiteWise 자산 속성으로 전송합니다. | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | 메시지를 Firehose 전송 스트림에 전송합니다. | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | 메시지를 Kinesis 데이터 스트림에 전송합니다. | kinesis |
| [Lambda](lambda-rule-action.md) | 메시지 데이터를 입력으로 사용하여 Lambda 함수를 호출합니다. | lambda |
| [Location](location-rule-action.md) | Amazon Location Service에 위치 데이터를 전송합니다. | location |
| [OpenSearch](opensearch-rule-action.md) | Amazon OpenSearch Service 엔드포인트에 메시지를 전송합니다. | OpenSearch |
| [재게시](republish-rule-action.md) | 메시지를 다른 MQTT 주제에 재게시합니다. | republish |
| [S3](s3-rule-action.md) | 메시지를 Amazon Simple Storage Service(Amazon S3) 버킷에 저장합니다. | s3 |
| [Salesforce IoT](salesforce-iot-rule-action.md) | 메시지를 Salesforce IoT 입력 스트림에 전송합니다. | salesforce |
| [SNS](sns-rule-action.md) | 메시지를 Amazon Simple Notification Service(Amazon SNS) 푸시 알림으로 게시합니다. | sns |
| [SQS](sqs-rule-action.md) | 메시지를 Amazon Simple Queue Service(Amazon SQS) 대기열에 전송합니다. | sqs |
| [단계 함수](stepfunctions-rule-action.md) | AWS Step Functions 상태 시스템을 시작합니다. | stepFunctions |
| [Timestream](timestream-rule-action.md) | 메시지를 Amazon Timestream 데이터베이스 테이블에 전송합니다. | timestream |
**참고**
규칙 작업이 해당 리소스와 상호 작용할 수 있도록 AWS 리전 다른 서비스의 리소스와 동일한에서 규칙을 정의합니다.
AWS IoT 규칙 엔진은 간헐적인 오류가 발생할 경우 작업을 여러 번 시도할 수 있습니다. 모든 시도가 실패하면 메시지가 삭제되고 CloudWatch Logs에서 오류를 확인할 수 있습니다. 각 규칙에 대해 실패 발생 후 간접 호출되는 오류 작업을 지정할 수 있습니다. 자세한 내용은 [오류 처리(오류 작업)](rule-error-handling.md) 단원을 참조하십시오.
일부 규칙 작업은 AWS Key Management Service (AWS KMS)와 통합되는 서비스에서 작업을 활성화하여 저장 데이터 암호화를 지원합니다. 고객 관리형 AWS KMS key (KMS 키)를 사용하여 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 고객 관리형 KMS 키에 대한 권한을 관리하는 방법을 알아보려면 해당 서비스 가이드의 데이터 암호화 주제를 참조하세요. 고객 관리형 KMS 키에 대한 자세한 내용은 **AWS Key Management Service 개발자 안내서의 [AWS Key Management Service 개념](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)을 참조하세요.
, [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), , , , , , 등의 외부 [함수](iot-sql-functions.md)를 포함하여 오류 작업의 SQL 문에서 함수 또는 [대체 템플릿을](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) 사용할 수 [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) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)있습니다[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). 오류 작업에서 외부 함수를 호출해야 하는 경우 오류 작업을 직접적으로 호출하면 외부 함수에 대한 추가 요금이 부과될 수 있습니다.
# Apache Kafka
Apache Kafka(Kafka) 작업은 [Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html)(Amazon MSK), [Confluent Cloud](https://www.confluent.io/)와 같은 서드파티 공급자가 관리하는 Apache Kafka 클러스터 또는 자체 관리형 Apache Kafka 클러스터로 직접 메시지를 전송합니다. Kafka 규칙 작업을 사용하면 IoT 데이터를 Kafka 클러스터로 라우팅할 수 있습니다. 이를 통해 스트리밍 분석, 데이터 통합, 시각화 및 미션 크리티컬 비즈니스 애플리케이션과 같은 다양한 목적을 위해 고성능 데이터 파이프라인을 구축할 수 있습니다.
**참고**
이 주제에서는 Apache Kafka 플랫폼 및 관련 개념에 대해 잘 알고 있다고 가정합니다. Apache Kafka에 대한 자세한 내용은 [Apache Kafka](https://kafka.apache.org/) 섹션을 참조하세요. [MSK Serverless](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html)는 지원되지 않습니다. MSK Serverless 클러스터는 현재 Apache Kafka 규칙 작업이 지원하지 않는 IAM 인증을 통해서만 수행할 수 있습니다. Confluent AWS IoT Core 를 사용하여를 구성하는 방법에 대한 자세한 내용은 [Confluent 활용 및 IoT 디바이스 및 데이터 관리 문제 AWS 해결을 참조하세요](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/).
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ 가 `ec2:CreateNetworkInterface`, , , , `ec2:DescribeNetworkInterfaces`, `ec2:CreateNetworkInterfacePermission`, `ec2:DescribeVpcAttribute`및 `ec2:DescribeSecurityGroups` 작업을 수행하기 위해 `ec2:DeleteNetworkInterface` `ec2:DescribeSubnets` `ec2:DescribeVpcs`수임할 AWS IoT 수 있는 IAM 역할입니다. 이 역할은 Amazon Virtual Private Cloud에 대한 탄력적인 네트워크 인터페이스를 생성 및 관리하여 Kafka 브로커에 도달할 수 있습니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT Core 있습니다.
네트워크 인터페이스에 대한 자세한 내용은 **Amazon EC2 사용 설명서의 [탄력적 네트워크 인터페이스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요.
지정한 역할에 연결된 정책은 다음 예시와 같습니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ AWS Secrets Manager 를 사용하여 Kafka 브로커에 연결하는 데 필요한 자격 증명을 저장하는 경우 `secretsmanager:GetSecretValue` 및 `secretsmanager:DescribeSecret` 작업을 수행하기 위해가 맡을 AWS IoT Core 수 있는 IAM 역할을 생성해야 합니다.
지정한 역할에 연결된 정책은 다음 예시와 같습니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ Amazon Virtual Private Cloud(VPC) 내에서 Apache Kafka 클러스터를 실행할 수 있습니다. Apache Kafka Virtual Private Cloud(VPC) 대상을 생성하고 서브넷에서 NAT 게이트웨이를 사용하여의 메시지를 퍼블릭 Kafka 클러스터 AWS IoT 로 전달해야 합니다. 규칙 엔진은 AWS IoT 대상에 나열된 각 서브넷에 네트워크 인터페이스를 생성하여 트래픽을 VPC로 직접 라우팅합니다. 대상 지정 시 AWS IoT 규칙 엔진은 VPC 규칙 작업을 자동으로 생성합니다. VPC 규칙 작업에 대한 자세한 내용은 [Apache Kafka Virtual Private Cloud(VPC) 대상](kafka-vpc-destination.md) 단원을 참조하세요.
+ 고객 관리형 AWS KMS key (KMS 키)를 사용하여 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon Managed Streaming for Apache Kafka 개발자 안내서*의 [Amazon MSK 암호화](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html)를 참조하세요.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
destinationArn
Apache Kafka Virtual Private Cloud(VPC) 대상의 Amazon 리소스 이름(ARN)입니다. 대상 생성에 대한 자세한 내용은 섹션을 참조하세요[Apache Kafka Virtual Private Cloud(VPC) 대상](kafka-vpc-destination.md).
주제
메시지에 대한 Kafka 주제는 Kafka 브로커로 전송됩니다.
대체 템플릿을 사용하여 이 필드를 대체할 수 있습니다. 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요.
key(선택 사항)
Kafka 메시지 키입니다.
대체 템플릿을 사용하여 이 필드를 대체할 수 있습니다. 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하십시오.
헤더(선택 사항)
지정한 Kafka 헤더 목록입니다. 각 헤더는 Kafka 작업을 생성할 때 지정할 수 있는 키-값 페어입니다. 메시지 페이로드를 수정하지 않고도 이러한 헤더를 사용하여 IoT 클라이언트의 데이터를 다운스트림 Kafka 클러스터로 라우팅할 수 있습니다.
대체 템플릿을 사용하여 이 필드를 대체할 수 있습니다. [Kafka 작업의 헤더에서 인라인 규칙의 함수를 대체 템플릿으로 전달하는 방법을 이해하려면 예시](#apache-kafka-rule-action-examples)를 참조하세요. 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하십시오.
바이너리 형식의 헤더는 지원되지 않습니다.
partition(선택 사항)
Kafka 메시지 파티션입니다.
대체 템플릿을 사용하여 이 필드를 대체할 수 있습니다. 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요.
clientProperties
Apache Kafka 프로듀서 클라이언트의 속성을 정의하는 객체입니다.
acks(선택 사항)
프로듀서가 요청이 완료되었음을 고려하기 전에 서버가 수신해야 하는 승인 수입니다.
값으로 0을 지정하면 프로듀서는 서버의 승인을 기다리지 않습니다. 서버에서 메시지를 받지 못하면 프로듀서는 메시지를 전송하려고 다시 시도하지 않습니다.
유효한 값: `-1`, `0`, `1`, `all`. 기본값은 `1`입니다.
bootstrap.servers
Kafka 클러스터에 대한 초기 연결을 설정하는 데 사용되는 호스트 및 포트 페어 목록(예: `host1:port1`, `host2:port2`)입니다.
compression.type(선택 사항)
생산자가 생성한 모든 데이터에 대한 압축 유형입니다.
유효한 값:`none` ,`gzip` ,`snappy` ,`lz4` .`zstd` 기본값은 `none`입니다.
security.protocol
Kafka 브로커에 연결하는 데 사용되는 보안 프로토콜입니다.
유효한 값: `SSL`, `SASL_SSL`. 기본값은 `SSL`입니다.
key.serializer
`ProducerRecord`와 함께 제공되는 키 객체를 바이트로 변환하는 방법을 지정합니다.
유효한 값: `StringSerializer`.
value.serializer
`ProducerRecord`와 함께 제공하는 값 객체를 바이트로 변환하는 방법을 지정합니다.
유효한 값: `ByteBufferSerializer`.
ssl.truststore
base64 형식의 truststore 파일 또는 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)의 truststore 파일 위치입니다. Amazon 인증 기관(CA)에서 사용자의 트러스트 스토어를 신뢰하는 경우에는 이 값이 필요하지 않습니다.
이 필드는 대체 템플릿을 지원합니다. Kafka 브로커에 연결하는 데 필요한 보안 인증 정보를 저장하는 데 Secrets Manager를 사용하는 경우, `get_secret` SQL 함수를 사용하여 이 필드의 값을 검색할 수 있습니다. 대체 변수에 대한 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요. `get_secret` SQL 함수에 대한 자세한 내용은 [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret) 섹션을 참조하세요. truststore가 파일 형식인 경우 `SecretBinary` 파라미터를 사용합니다. truststore가 문자열 형식인 경우 `SecretString` 파라미터를 사용합니다.
이 값의 최대 크기는 65KB입니다.
ssl.truststore.password
truststore의 암호입니다. 이 값은 truststore의 암호를 만든 경우에만 필요합니다.
ssl.keystore
keystore 파일입니다. `SSL`을 `security.protocol`의 값으로 지정할 때 이 값이 필요합니다.
이 필드는 대체 템플릿을 지원합니다. Secrets Manager를 사용하여 Kafka 브로커에 연결하는 데 필요한 보안 인증 정보를 저장합니다. `get_secret` SQL 함수를 사용하여 이 필드의 값을 검색합니다. 대체 변수에 대한 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요. `get_secret` SQL 함수에 대한 자세한 내용은 [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret) 섹션을 참조하세요. `SecretBinary` 파라미터를 사용합니다.
ssl.keystore.password
keystore 파일의 스토어 암호입니다. `ssl.keystore`에 값이 지정된 경우 이 값이 필요합니다.
이 필드의 값은 일반 텍스트일 수 있습니다. 이 필드는 대체 템플릿도 지원합니다. Secrets Manager를 사용하여 Kafka 브로커에 연결하는 데 필요한 보안 인증 정보를 저장합니다. `get_secret` SQL 함수를 사용하여 이 필드의 값을 검색합니다. 대체 변수에 대한 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요. `get_secret` SQL 함수에 대한 자세한 내용은 [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret) 섹션을 참조하세요. `SecretString` 파라미터를 사용합니다.
ssl.key.password
keystore 파일에 있는 프라이빗 키의 암호입니다.
이 필드는 대체 템플릿을 지원합니다. Secrets Manager를 사용하여 Kafka 브로커에 연결하는 데 필요한 보안 인증 정보를 저장합니다. `get_secret` SQL 함수를 사용하여 이 필드의 값을 검색합니다. 대체 변수에 대한 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요. `get_secret` SQL 함수에 대한 자세한 내용은 [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret) 섹션을 참조하세요. `SecretString` 파라미터를 사용합니다.
sasl.mechanism
Kafka 브로커에 연결하는 데 사용되는 보안 메커니즘입니다. `security.protocol`에 `SASL_SSL`을 지정할 때 이 값이 필요합니다.
유효한 값: `PLAIN`, `SCRAM-SHA-512`, `GSSAPI`.
`SCRAM-SHA-512`는 cn-north-1, cn-northwest-1, us-gov-east-1, and us-gov-west-1 리전에서 유일하게 지원되는 보안 메커니즘입니다.
sasl.plain.username
Secrets Manager에서 보안 문자열을 검색하는 데 사용되는 사용자 이름입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `PLAIN`을 지정할 때 이 값이 필요합니다.
sasl.plain.password
Secrets Manager에서 보안 문자열을 검색하는 데 사용되는 암호입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `PLAIN`을 지정할 때 이 값이 필요합니다.
sasl.scram.username
Secrets Manager에서 보안 문자열을 검색하는 데 사용되는 사용자 이름입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `SCRAM-SHA-512`을 지정할 때 이 값이 필요합니다.
sasl.scram.password
Secrets Manager에서 보안 문자열을 검색하는 데 사용되는 암호입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `SCRAM-SHA-512`을 지정할 때 이 값이 필요합니다.
sasl.kerberos.keytab
Secrets Manager의 Kerberos 인증을 위한 keytab 파일입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `GSSAPI`을 지정할 때 이 값이 필요합니다.
이 필드는 대체 템플릿을 지원합니다. Secrets Manager를 사용하여 Kafka 브로커에 연결하는 데 필요한 보안 인증 정보를 저장합니다. `get_secret` SQL 함수를 사용하여 이 필드의 값을 검색합니다. 대체 변수에 대한 자세한 내용은 [대체 템플릿](iot-substitution-templates.md) 단원을 참조하세요. `get_secret` SQL 함수에 대한 자세한 내용은 [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret) 섹션을 참조하세요. `SecretBinary` 파라미터를 사용합니다.
sasl.kerberos.service.name
Apache Kafka가 실행되는 Kerberos 보안 주체 이름입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `GSSAPI`을 지정할 때 이 값이 필요합니다.
sasl.kerberos.krb5.kdc
Apache Kafka 프로듀서 클라이언트가 연결하는 키 배포 센터(KDC)의 호스트 이름입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `GSSAPI`을 지정할 때 이 값이 필요합니다.
sasl.kerberos.krb5.realm
Apache Kafka 프로듀서 클라이언트가 연결되는 영역입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `GSSAPI`을 지정할 때 이 값이 필요합니다.
sasl.kerberos.principal
Kerberos가 Kerberos 인식 서비스에 액세스하기 위해 티켓을 할당할 수 있는 고유한 Kerberos ID입니다. `security.protocol`에 `SASL_SSL`, `sasl.mechanism`에 `GSSAPI`을 지정할 때 이 값이 필요합니다.
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 Apache Kafka 작업을 정의합니다. 다음 예시에서는 [sourceIp()](iot-sql-functions.md#iot-function-sourceip) 인라인 함수를 Kafka 작업 헤더의 [대체 템플릿](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)으로 전달합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**Kerberos 설정에 대한 중요 참고 사항**
+ 대상 VPC 내의 프라이빗 도메인 이름 시스템(DNS)을 통해 키 배포 센터(KDC) 를 확인할 수 있어야 합니다. 한 가지 가능한 방법은 KDC DNS 항목을 프라이빗 호스팅 영역에 추가하는 것입니다. 이 접근법에 대한 자세한 내용은 [프라이빗 호스팅 영역 작업](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)을 참조하세요.
+ 각 VPC에는 DNS 확인이 활성화되어 있어야 합니다. 자세한 내용은 [VPC에서 DNS 사용하기](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) 단원을 참조하세요.
+ VPC 대상의 네트워크 인터페이스 보안 그룹과 인스턴스 수준 보안 그룹은 다음 포트에서 VPC 내의 트래픽을 허용해야 합니다.
+ 부트스트랩 브로커 리스너 포트의 TCP 트래픽(대개 9092이지만 9000\$19100 범위 내에 있어야 함)
+ 포트 88에서 KDC에 대한 TCP 및 UDP 트래픽
+ `SCRAM-SHA-512`는 cn-north-1, cn-northwest-1, us-gov-east-1, and us-gov-west-1 리전에서 유일하게 지원되는 보안 메커니즘입니다.
# Apache Kafka Virtual Private Cloud(VPC) 대상
Apache Kafka 규칙 작업은 Amazon Virtual Private Cloud(Amazon VPC)의 Apache Kafka 클러스터로 데이터를 라우팅합니다. Apache Kafka 규칙 작업에서 사용하는 VPC 구성은 규칙 작업의 VPC 대상을 지정할 때 자동으로 사용됩니다.
Apache Kafka Virtual Private Cloud(VPC) 대상에는 VPC 내의 서브넷 목록이 포함됩니다. 규칙 엔진은 이 목록에서 지정한 각 서브넷에 탄력적 네트워크 인터페이스를 생성합니다. 네트워크 인터페이스에 대한 자세한 내용은 Amazon EC2 사용 설명서의 [탄력적 네트워크 인터페이스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요.
## 요구 사항 및 고려 사항
+ 인터넷을 통해 퍼블릭 엔드포인트를 사용하여 액세스될 자체 관리형 Apache Kafka 클러스터를 사용하는 경우:
+ 서브넷의 인스턴스에 대해 NAT 게이트웨이를 생성합니다. NAT 게이트웨이에는 인터넷에 연결할 수 있는 퍼블릭 IP 주소가 있으므로 규칙 엔진이 메시지를 퍼블릭 Kafka 클러스터로 전달할 수 있습니다.
+ Apache Kafka Virtual Private Cloud(VPC) 대상에서 생성한 탄력적 네트워크 인터페이스(ENIs)를 사용하여 탄력적 IP 주소를 할당합니다. 사용하는 보안 그룹은 수신 트래픽을 차단하도록 구성해야 합니다.
**참고**
Apache Kafka Virtual Private Cloud(VPC) 대상이 비활성화되었다가 다시 활성화된 경우 탄력적 IPs를 새 ENIs와 다시 연결해야 합니다.
+ Apache Kafka Virtual Private Cloud(VPC) 대상이 30일 연속으로 트래픽을 수신하지 않으면 비활성화됩니다.
+ Apache Kafka Virtual Private Cloud(VPC) 대상에서 사용하는 리소스가 변경되면 대상이 비활성화되고 사용할 수 없습니다.
+ Apache Kafka Virtual Private Cloud(VPC) 대상을 비활성화할 수 있는 몇 가지 변경 사항은 다음과 같습니다.
+ VPC, 서브넷, 보안 그룹 또는 사용된 역할 삭제.
+ 더 이상 필요한 권한이 없도록 역할을 수정합니다.
+ 거의 서브넷 용량에 도달하여 [ FedRAMP](https://aws.amazon.com/compliance/fedramp/) 패치를 적용할 수 없습니다.
+ 대상을 비활성화합니다.
## 가격 책정
가격 책정을 위해 리소스가 VPC에 있을 때 리소스에 메시지를 전송하는 작업 외에도 VPC 규칙 작업이 측정됩니다. 요금 정보는 [AWS IoT Core 요금](https://aws.amazon.com/iot-core/pricing/)을 참조하세요.
## Apache Kafka Virtual Private Cloud(VPC) 대상 생성
[CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html) API 또는 AWS IoT Core 콘솔을 사용하여 Apache Kafka Virtual Private Cloud(VPC) 대상을 생성합니다.
대상을 생성할 때 다음 정보를 지정해야 합니다.
vpcId
Amazon VPC의 고유 ID입니다.
subnetIds
규칙 엔진이 탄력적 네트워크 인터페이스를 만드는 서브넷 목록입니다. 규칙 엔진은 목록의 각 서브넷에 대해 단일 네트워크 인터페이스를 할당합니다.
securityGroups(선택 사항)
네트워크 인터페이스에 적용할 보안 그룹 목록입니다.
roleArn
사용자를 대신하여 네트워크 인터페이스를 생성할 권한이 있는 역할의 Amazon 리소스 이름(ARN)입니다.
이 ARN에는 다음 예와 같은 정책이 연결되어 있어야 합니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### 를 사용하여 Apache Kafka Virtual Private Cloud(VPC) 대상 생성 AWS CLI
다음 예제에서는를 사용하여 대상을 생성하는 방법을 보여줍니다 AWS CLI.
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
이 명령을 실행하면 대상 상태는가 됩니다`IN_PROGRESS`. 몇 분 후 상태가 `ERROR`(명령이 성공하지 못한 경우) 또는 `ENABLED`로 변경됩니다. 대상 상태가 `ENABLED`이면 사용할 준비가 된 것입니다.
다음 명령을 사용하여 Apache Kafka Virtual Private Cloud(VPC) 대상의 상태를 가져올 수 있습니다.
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### AWS IoT Core 콘솔을 사용하여 Apache Kafka Virtual Private Cloud(VPC) 대상 생성
다음 단계에서는 AWS IoT Core 콘솔을 사용하여 대상을 생성하는 방법을 설명합니다.
1. AWS IoT Core 콘솔로 이동합니다. 왼쪽 창의 **동작** 탭에서 **대상**을 선택합니다.
1. 다음 필드에 값을 입력합니다.
+ **VPC ID**
+ **서브넷 ID**
+ **보안 그룹**
1. 네트워크 인터페이스를 생성하는 데 필요한 권한이 있는 역할을 선택합니다. 앞의 예제 정책에는 이러한 사용 권한이 포함되어 있습니다.
Apache Kafka Virtual Private Cloud(VPC) 대상 상태가 **ENABLED**이면 바로 사용할 수 있습니다.
# CloudWatch 경보
CloudWatch 경보(`cloudWatchAlarm`) 작업은 Amazon CloudWatch 경보의 상태를 변경합니다. 이 호출에서 상태 변경 이유 및 값을 지정할 수 있습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `cloudwatch:SetAlarmState` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`alarmName`
CloudWatch 경보 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`stateReason`
경보 변경 이유입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`stateValue`
경보 상태의 값입니다. 유효한 값: `OK`, `ALARM`, `INSUFFICIENT_DATA`.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
CloudWatch 경보에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#cloudwatch-alarms-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 CloudWatch 경보 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch란 무엇입니까?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)
+ *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch 경보 사용](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)
# CloudWatch Logs
CloudWatch Logs(`cloudwatchLogs`) 작업은 데이터를 Amazon CloudWatch Logs에 전송합니다. `batchMode`를 사용하여 하나의 메시지에 여러 디바이스 로그 레코드를 업로드하고 타임스탬프를 지정할 수 있습니다. 작업에서 데이터를 전송할 로그 그룹을 지정할 수도 있습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ 가 `logs:CreateLogStream`, `logs:DescribeLogStreams`및 `logs:PutLogEvents` 작업을 수행하기 위해 수임할 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
+ 고객 관리형 AWS KMS key (KMS 키)를 사용하여 CloudWatch Logs에서 로그 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon CloudWatch Logs 사용 설명서*의 [AWS KMS를 사용하여 CloudWatch Logs에서 로그 데이터 암호화](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)를 참조하세요.
## `batchMode`에 대한 MQTT 메시지 형식 요구 사항
`batchMode`를 끄고 CloudWatch Logs 규칙 작업을 사용하는 경우 MQTT 메시지 형식 지정 요구 사항이 없습니다. (참고: `batchMode` 파라미터의 기본값은 `false`입니다.) 그러나 `batchMode`가 켜진 상태에서 CloudWatch Logs 규칙 작업을 사용하는 경우(파라미터 값은 `true`), 디바이스 측 로그를 포함하는 MQTT 메시지는 타임스탬프와 메시지 페이로드를 포함하도록 형식을 지정해야 합니다. **참고:** `timestamp`는 이벤트가 발생한 시간을 나타내며, 1970년 1월 1일 00:00:00 UTC 이후 경과된 밀리초 수로 표시됩니다.
다음은 게시 형식의 예입니다.
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
이 요구 사항을 준수하려면 기기 측 로그가 생성되는 방식에 따라 로그를 전송하기 전에 해당 로그를 필터링하고 형식을 다시 지정해야 할 수 있습니다. 자세한 내용은 [MQTT 메시지 페이로드](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html)를 참조하세요.
`batchMode` 파라미터와 관계없이 `message` 콘텐츠는 AWS IoT 메시지 크기 제한을 준수해야 합니다. 자세한 내용은 [AWS IoT Core 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/iot-core.html)을 참조하세요.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`logGroupName`
작업에서 데이터를 전송할 CloudWatch 로그 그룹입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`roleArn`
CloudWatch 로그 그룹에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#cloudwatch-logs-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
`batchMode` (선택 사항)
로그 레코드 배치를 추출하여 CloudWatch에 업로드할지 여부를 나타냅니다. 값에는 `true` 또는 `false`(기본값)가 포함됩니다. 자세한 내용은 [요구 사항](#cloudwatch-logs-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 CloudWatch Logs 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon CloudWatch Logs 사용 설명서*의 [Amazon CloudWatch Logs란 무엇입니까?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)
# CloudWatch 지표
CloudWatch 지표(`cloudwatchMetric`) 작업은 Amazon CloudWatch 지표를 포착합니다. 지표 네임스페이스, 이름, 값 및 타임스탬프를 지정할 수 있습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `cloudwatch:PutMetricData` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`metricName`
CloudWatch 지표 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`metricNamespace`
CloudWatch 지표 네임스페이스 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`metricUnit`
CloudWatch에서 지원되는 지표 단위입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`metricValue`
CloudWatch 지표 값을 포함하는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`metricTimestamp`
(선택 사항) Unix Epoch 시간으로 표시되는(초 단위) 타임스탬프가 포함된 문자열입니다. 기본값은 현재 Unix Epoch 시간입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
CloudWatch 지표에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#cloudwatch-metrics-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 CloudWatch 지표 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 CloudWatch 지표 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch란 무엇입니까?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)
+ *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch 지표 사용](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)
# DynamoDB
DynamoDB(`dynamoDB`) 작업은 MQTT 메시지의 전체 또는 일부를 Amazon DynamoDB 테이블에 씁니다.
DynamoDB 작업을 사용하여 규칙을 생성하고 테스트하는 방법을 자습서에서 확인할 수 있습니다. 자세한 내용은 [자습서: DynamoDB 테이블에 디바이스 데이터 저장](iot-ddb-rule.md) 섹션을 참조하세요.
**참고**
이 규칙은 비 JSON 데이터를 이진 데이터로 DynamoDB에 씁니다. DynamoDB 콘솔은 데이터를 Base64 인코딩된 텍스트로 표시합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `dynamodb:PutItem` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
+ 고객 관리형 AWS KMS key (KMS 키)를 사용하여 DynamoDB에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon DynamoDB 시작 안내서*의 [고객 관리형 KMS 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`tableName`
DynamoDB 테이블의 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`hashKeyField`
해시 키(파티션 키라고도 함)의 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`hashKeyType`
(선택 사항) 해시 키(파티션 키라고도 함)의 데이터 형식입니다. 유효한 값: `STRING`, `NUMBER`.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`hashKeyValue`
해시 키의 값입니다. `${topic()}` 또는 `${timestamp()}` 같은 대체 템플릿 사용을 고려하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`rangeKeyField`
(선택 사항) 범위 키(정렬 키라고도 함)의 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`rangeKeyType`
(선택 사항) 범위 키(정렬 키라고도 함)의 데이터 형식입니다. 유효한 값: `STRING`, `NUMBER`.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`rangeKeyValue`
(선택 사항) 범위 키의 값입니다. `${topic()}` 또는 `${timestamp()}` 같은 대체 템플릿 사용을 고려하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`payloadField`
(선택 사항) 페이로드가 기록될 열 이름입니다. 이 값을 생략할 경우 페이로드가 `payload`라는 열에 기록됩니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`operation`
(선택 사항) 수행할 작업의 유형입니다. 유효한 값: `INSERT`, `UPDATE`, `DELETE`.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleARN`
DynamoDB 테이블에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#dynamodb-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
DynamoDB 테이블에 기록된 데이터는 규칙 내 SQL 문의 결과입니다.
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 DynamoDB 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon DynamoDB 개발자 안내서*의 [Amazon DynamoDB란 무엇입니까?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB 개발자 안내서*의 [DynamoDB 시작하기](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
+ [자습서: DynamoDB 테이블에 디바이스 데이터 저장](iot-ddb-rule.md)
# DynamoDBv2
DynamoDBv2(`dynamoDBv2`) 작업은 MQTT 메시지의 전체 또는 일부를 Amazon DynamoDB 테이블에 전송합니다. 페이로드의 각 속성은 DynamoDB 데이터베이스의 개별 열에 기록됩니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `dynamodb:PutItem` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
+ MQTT 메시지 페이로드는 테이블의 기본 파티션 키와 일치하는 루트 수준 키, 그리고 정의된 경우 테이블의 기본 정렬 키와 일치하는 루트 수준 키를 포함해야 합니다.
+ 고객 관리형 AWS KMS key (KMS 키)를 사용하여 DynamoDB에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon DynamoDB 시작 안내서*의 [고객 관리형 KMS 키](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`putItem`
메시지 데이터를 작성할 DynamoDB 테이블을 지정하는 객체입니다. 이 객체에는 다음 정보가 포함되어 있어야 합니다.
`tableName`
DynamoDB 테이블의 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`roleARN`
DynamoDB 테이블에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#dynamodb-v2-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
DynamoDB 테이블에 기록된 데이터는 규칙 내 SQL 문의 결과입니다.
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 DynamoDBv2 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 DynamoDB 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon DynamoDB 개발자 안내서*의 [Amazon DynamoDB란 무엇입니까?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB 개발자 안내서*의 [DynamoDB 시작하기](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
# Elasticsearch
Elasticsearch(`elasticsearch`) 작업을 사용하여 MQTT 메시지의 데이터를 Amazon OpenSearch Service 도메인에 전송합니다. 그런 다음 OpenSearch 대시보드와 같은 도구를 사용하여 OpenSearch Service에서 데이터를 쿼리하고 시각화할 수 있습니다.
**주의**
`Elasticsearch` 작업은 기존 규칙 작업에서만 사용할 수 있습니다. 새 규칙 작업을 생성하거나 기존 규칙 작업을 업데이트하려면 대신 `OpenSearch` 규칙 작업을 사용합니다. 자세한 내용은 [OpenSearch](opensearch-rule-action.md) 단원을 참조하십시오.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `es:ESHttpPut` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
+ 고객 관리형 AWS KMS key (KMS 키)를 사용하여 OpenSearch에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon OpenSearch Service 개발자 안내서*의 [Amazon OpenSearch Service의 저장 시 데이터 암호화](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`endpoint`
서비스 도메인의 엔드포인트입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`index`
데이터를 저장할 인덱스입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`type`
저장 중인 문서의 유형입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`id`
각 문서의 고유 식별자입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleARN`
OpenSearch 도메인에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#elasticsearch-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 Elasticsearch 작업을 정의하고 `elasticsearch` 작업에 대한 필드를 지정하는 방법을 정의합니다. 자세한 내용은 [ElasticsearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_ElasticsearchAction.html) 섹션을 참조하세요.
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 Elasticsearch 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ [OpenSearch](opensearch-rule-action.md)
+ [Amazon OpenSearch Service란 무엇입니까?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
HTTPS(`http`) 작업은 MQTT 메시지의 데이터를 HTTPS 엔드포인트로 전송합니다. HTTPS 엔드포인트는 웹 애플리케이션 또는 서비스를 가리킬 수 있습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ 규칙 엔진에서 사용하려면 먼저 HTTPS 엔드포인트를 확인하고 활성화해야 합니다. 자세한 내용은 [HTTP 작업 대상](http-action-destination.md) 단원을 참조하십시오.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`url`
메시지가 HTTP POST 메서드를 사용하여 전송되는 HTTPS 엔드포인트입니다. 호스트 이름 대신 IP 주소를 사용하는 경우 IPv4 주소여야 합니다. IPv6 주소는 지원하지 않습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`confirmationUrl`
(선택 사항) 지정된 경우 확인 URL을 AWS IoT 사용하여 일치하는 주제 규칙 대상을 생성합니다. HTTP 작업에서 사용하기 전에 HTTP 작업 대상을 활성화해야 합니다. 자세한 내용은 [HTTP 작업 대상](http-action-destination.md) 단원을 참조하십시오. 대체 템플릿을 사용하는 경우 작업을 `http` 사용하려면 먼저 HTTP 작업 대상을 수동으로 생성해야 합니다.는 접두사여야 `confirmationUrl` 합니다`url`.
`url`과 `confirmationUrl` 사이의 관계는 다음으로 설명됩니다.
+ `url`가 하드코딩되고 `confirmationUrl`가 제공되지 않은 경우 `url` 필드를 로 암시적으로 취급합니다`confirmationUrl`.는에 대한 주제 규칙 대상을 AWS IoT 생성합니다`url`.
+ `url` 및 `confirmationUrl`가 하드코딩된 경우는 로 시작해야 `url` 합니다`confirmationUrl`.는에 대한 주제 규칙 대상을 AWS IoT 생성합니다`confirmationUrl`.
+ `url`에 대체 템플릿이 포함되어 있는 경우 `confirmationUrl`을 지정하고 `url`은 `confirmationUrl`로 시작해야 합니다. 에 대체 템플릿이 `confirmationUrl` 포함된 경우 HTTP 작업 대상을 수동으로 생성해야 `http` 작업을 사용할 수 있습니다. `confirmationUrl`에 대체 템플릿이 포함되어 있지 않은 경우는에 대한 주제 규칙 대상을 AWS IoT 생성합니다`confirmationUrl`.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`headers`
(선택 사항) 엔드포인트에 대한 HTTP 요청에 포함할 헤더 목록입니다. 각 헤더에는 다음 정보가 포함되어야 합니다.
`key`
헤더의 키입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`value`
헤더의 값
[대체 템플릿](iot-substitution-templates.md) 지원: 예
페이로드가 JSON 형식일 때 기본 콘텐츠 유형은 application/json입니다. 그렇지 않으면 application/octet-stream입니다. 키 콘텐츠 유형(대/소문자 구분 없음)으로 헤더에서 정확한 콘텐츠 유형을 지정하여 덮어쓸 수 있습니다.
`auth`
(선택 사항) `url` 인수에 지정된 엔드포인트 URL에 연결하기 위해 규칙 엔진에서 사용하는 인증입니다. 현재 서명 버전 4는 유일하게 지원되는 인증 유형입니다. 자세한 내용은 [HTTP 권한 부여](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html)를 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`enableBatching`
(선택 사항) HTTP 작업 메시지를 지정된 URL에 대한 단일 요청으로 처리할지 여부입니다. 값은 true 또는 false일 수 있습니다. 일괄 처리에 대한 자세한 내용은 [HTTP 작업 메시지 일괄 처리를 참조하세요](http_batching.md).
부울 값
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
`batchConfig`
(선택 사항) 일괄 처리를 위한 구성 설정입니다. 활성화되면 `batchConfig` 파라미터를 지정해야 합니다. `batchConfig` 파라미터를 지정하지 않으면 기본값이 사용됩니다.
`maxBatchOpenMs`
발신 메시지가 다른 메시지가 배치를 생성할 때까지 대기하는 최대 시간(밀리초)입니다. 설정이 높을수록 일괄 HTTP 작업의 지연 시간이 길어집니다.
최소값: 5ms. 최댓값: 200ms.
기본값: 20ms
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
`maxBatchSize`
단일 작업 실행에서 함께 일괄 처리되는 최대 메시지 수입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
최솟값: 메시지 2개. 최대값: 메시지 10개
기본값: 메시지 10개
`maxBatchSizeBytes`
메시지 배치의 최대 크기, 바이트 단위.
최소값: 100바이트. 최대값: 131,072바이트
기본값: 5,120바이트
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
페이로드가 JSON 형식일 때 기본 콘텐츠 유형은 application/json입니다. 그렇지 않으면 application/octet-stream입니다. 키 콘텐츠 유형(대/소문자 구분 없음)으로 헤더에서 정확한 콘텐츠 유형을 지정하여 덮어쓸 수 있습니다.
## 예제
다음 JSON 예제에서는 HTTP 작업을 사용하여 AWS IoT 규칙을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## HTTP 작업 재시도 논리
AWS IoT 규칙 엔진은 다음 규칙에 따라 HTTP 작업을 재시도합니다.
+ 규칙 엔진은 메시지를 한 번 이상 전송하려고 시도합니다.
+ 규칙 엔진은 최대 두 번 재시도합니다. 최대 시도 횟수는 3회입니다.
+ 규칙 엔진은 다음과 같은 경우 재시도를 수행하지 않습니다.
+ 이전 시도에서 16,384바이트보다 큰 응답을 제공했습니다.
+ 시도 후 다운스트림 웹 서비스 또는 애플리케이션에서 TCP 연결을 닫습니다.
+ 재시도로 요청을 완료하는 데 걸리는 총 시간이 요청 제한 시간 한도를 초과했습니다.
+ 이 요청이 429, 500-599 이외의 HTTP 상태 코드를 반환합니다.
**참고**
[표준 데이터 전송 비용](https://aws.amazon.com/ec2/pricing/on-demand/)이 재시도에 적용됩니다.
## 다음 사항도 참조하세요.
+ [HTTP 작업 메시지 배치 처리](http_batching.md)
+ [HTTP 작업 대상](http-action-destination.md)
+ 블로그*의 사물 인터넷 AWS*에서 [에서 AWS IoT Core 웹 서비스로 직접 데이터 라우팅](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/)
# HTTP 작업 메시지 배치 처리
일괄 처리를 사용하여 단일 요청으로 여러 HTTP 작업 메시지를 보낼 수 있습니다.
## 개요
일괄 처리를 사용하면 AWS IoT Core 규칙 엔진에서 HTTP 엔드포인트로 메시지를 일괄 전송할 수 있습니다. 이 기능을 사용하면 HTTP 작업 실행 수를 줄이고 새 연결 설정과 관련된 오버헤드를 줄여 효율성을 개선할 수 있습니다.
**참고**
일괄 HTTP 작업은 단일 작업으로 측정됩니다. AWS IoT Core 규칙 엔진에서 다운스트림 서비스로 내보내는 아웃바운드 배치 페이로드의 크기를 기준으로 5kiB 단위로 측정됩니다. 자세한 내용은 [AWS IoT Core 요금](https://aws.amazon.com/iot-core/pricing/) 페이지를 참조하세요.
IoT 규칙 작업의 정의에서 일괄 처리를 활성화하면 구성에 다음 파라미터를 사용할 수 있습니다.
`maxBatchOpenMs`
발신 메시지가 다른 메시지가 배치를 생성할 때까지 대기하는 최대 시간(밀리초)입니다. 설정이 높을수록 일괄 HTTP 작업의 지연 시간이 길어집니다.
최소값: 5ms. 최댓값: 200ms.
기본값: 20ms
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
`maxBatchSize`
단일 IoT 규칙 작업 실행에서 함께 일괄 처리되는 최대 메시지 수입니다.
최솟값: 메시지 2개. 최대값: 메시지 10개
기본값: 메시지 10개
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
`maxBatchSizeBytes`
메시지 배치의 최대 크기, 바이트 단위.
최소값: 100바이트. 최대값: 131,072바이트
기본값: 5120바이트
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
**중요**
여러 배치 파라미터를 지정하면 첫 번째 한도에 도달하면 일괄 처리가 완료됩니다. 예를 들어 최대 배치 열기 시간으로 100ms를 지정하고 최대 배치 크기로 5kiB를 지정하고 규칙 엔진이 100ms 이내에 2kiB만 배치하는 경우 2kiB 배치가 생성되고 전송됩니다.
## 배치에서 HTTP 헤더 사용
HTTP 작업에서 헤더를 사용하는 경우 일괄 처리 요청은 배치에 추가된 마지막 메시지의 헤더 값(반드시 게시한 마지막 메시지가 아님)을 사용합니다. 다음 중 하나인 헤더 값을 사용하는 것이 좋습니다.
+ 배치의 모든 메시지에서 동일
+ 모든 메시지에 적용 가능(예: 인증 자격 증명)
헤더는 HTTP 요청과 함께 전송되며 메시지 본문의 일부가 아닙니다.
**참고**
일괄 처리가 활성화된 경우:
배치 요청은 배치가 JSON 배열로 전송되므로 `Content-Type: application/json` 헤더를 자동으로 포함합니다.
배치의 마지막 메시지가 게시한 마지막 메시지임을 보장할 수는 없습니다. 배치로 만든 마지막 메시지입니다.
## 페이로드 예제
다음 예제는 HTTP 엔드포인트로 전송된 일괄 메시지 페이로드의 구조를 보여줍니다.
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## 제한 사항
다음은 일괄 처리의 제한 사항입니다.
+ AWS IoT Core 는 전체 메시지 순서를 보장하지 않습니다. 배치는 각 호스트에서 로컬로 수행되므로 배치 내의 메시지가 수신된 순서와 다른 순서로 처리될 수 있습니다.
+ AWS IoT Core 는 수신자 측에서 메시지 처리 지원을 제공하지 않습니다. 다운스트림 서비스가 데이터를 일괄적으로 수락하고 처리하도록 구성되어 있는지 확인하는 것은 사용자의 책임입니다.
+ 메시지가 동일한 리소스 식별자(HTTP URL 또는 리소스 ARN)로 향하는 경우에도 교차 계정 일괄 처리는 지원되지 않습니다.
+ AWS IoT Core 는 배치 크기가 지정한 구성을 충족할 것이라고 보장하지 않습니다. 배치는 타이밍 및 메시지 흐름에 따라 구성된 제한보다 작을 수 있습니다.
+ 일괄 처리가 활성화된 경우 이진 페이로드(UTF-8이 아닌 데이터)는 지원되지 않습니다. UTF-8 텍스트 페이로드(예: JSON)만 허용됩니다. 바이너리 데이터를 전송하려면 HTTP 작업으로 전송하기 전에 base64로 인코딩한 다음 수신 엔드포인트에서 디코딩합니다. 예를 들어 IoT 규칙의 [인코딩 함수](iot-sql-functions.html#iot-function-encode)를 사용하여 바이너리 페이로드를 인코딩할 수 있습니다. 또는 IoT 디바이스에서 바이너리 페이로드를 인코딩하여에 게시할 수 있습니다 AWS IoT Core.
## 일괄 처리를 위한 오류 작업
오류 작업 정의에서 별도의 일괄 처리 로직을 정의할 수 없습니다. 그러나 기본 작업에서 일괄 처리 로직을 정의한 경우 오류 작업은 일괄 처리를 지원합니다.
배치 요청이 실패하면 AWS IoT Core 규칙 엔진은 [HTTP 작업 재시도 로직](https-rule-action.md#https-rule-action-retry-logic)을 따릅니다. 마지막 재시도 후 실패한 전체 배치에 대해 오류 작업이 호출됩니다.
다음은 일괄 처리가 활성화된 오류 작업 메시지의 예입니다.
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**참고**
또한 배치 작업 실패는 더 큰 오류 작업 페이로드를 생성하여 크기로 인한 오류 작업 실패 가능성을 높일 수 있습니다. `ErrorActionFailure` 지표를 사용하여 오류 작업 실패를 모니터링할 수 있습니다. 자세한 정보는 [규칙 작업 지표](metrics_dimensions.md#rule-action-metrics)을 참조하세요.
## 를 사용하여 HTTP 작업 메시지 일괄 처리 AWS CLI
### 일괄 처리를 사용하여 규칙 작업 생성 또는 업데이트
1. 적절한 AWS CLI 명령을 사용하여 규칙을 생성하거나 업데이트합니다.
+ 새 규칙을 생성하려면 [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) 명령을 사용합니다.
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ 기존 규칙을 업데이트하려면 [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html) 명령을 사용합니다.
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. 주제 규칙 페이로드에서 enableBatching 파라미터를 true로 설정하여 일괄 처리 기능을 활성화합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. 일괄 처리 파라미터를 구성합니다. 모든 배치 파라미터를 지정할 필요는 없습니다. 1, 2 또는 3개의 배치 파라미터를 모두 지정하도록 선택할 수 있습니다. 배치 파라미터를 지정하지 않으면 규칙 엔진은 해당 파라미터를 기본값으로 업데이트합니다. 파라미터 일괄 처리 및 기본값에 대한 자세한 내용은 [HTTP 파라미터를](https-rule-action.md#https-rule-action-parameters) 참조하세요.
# HTTP 작업 대상
HTTP 작업 대상은 규칙 엔진이 주제 규칙에서 데이터를 라우팅할 수 있는 웹 서비스입니다. AWS IoT Core 리소스는에 대한 웹 서비스를 설명합니다 AWS IoT. 대상 리소스는 다른 규칙에서 공유할 수 있습니다.
AWS IoT Core 가 다른 웹 서비스로 데이터를 전송하려면 먼저 서비스의 엔드포인트에 액세스할 수 있는지 확인해야 합니다.
## 개요
HTTP 작업 대상은 확인 URL과 하나 이상의 데이터 수집 URLs을 지원하는 웹 서비스를 말합니다. 대상 리소스에는 웹 서비스의 확인 URL이 포함되어 있습니다. HTTP 작업을 구성할 때 웹 서비스의 확인 URL과 함께 데이터를 수신해야 하는 엔드포인트의 실제 URL을 지정합니다. 대상이 확인되면 주제 규칙은 SQL 문의 결과를 확인 URL이 아닌 HTTPS 엔드포인트로 전송합니다.
HTTP 작업 대상은 다음 상태 중 하나일 수 있습니다.
ENABLED
대상이 확인되었으며 규칙 작업에서 사용할 수 있습니다. 대상을 규칙에서 사용하려면 대상의 상태가 `ENABLED`여야 합니다. DISABLED 상태인 대상만 활성화할 수 있습니다.
DISABLED
대상이 확인되었지만 규칙 작업에서 사용할 수 없습니다. 이는 확인 프로세스를 다시 거치지 않고도 엔드포인트에 대한 트래픽을 일시적으로 차단하려는 경우에 유용합니다. ENABLED 상태인 대상만 비활성화할 수 있습니다.
IN\$1PROGRESS
대상 확인이 진행 중입니다.
ERROR
대상 확인 시간이 초과되었습니다.
HTTP 작업 대상이 확인되고 활성화되면 계정의 모든 규칙과 함께 사용할 수 있습니다.
## HTTP 작업 대상 관리
다음 작업을 사용하여 HTTP 작업 대상을 관리할 수 있습니다.
### HTTP 작업 대상 생성
`CreateTopicRuleDestination` 작업을 호출하거나 AWS IoT 콘솔을 사용하여 HTTP 작업 대상을 생성합니다.
대상을 생성한 후는 확인 URL로 확인 요청을 AWS IoT 보냅니다. 확인 요청의 형식은 다음과 같습니다.
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
확인 요청의 내용에는 다음 정보가 포함됩니다.
arn
확인할 HTTP 작업 대상의 Amazon 리소스 이름(ARN)입니다.
confirmationToken
에서 전송한 확인 토큰입니다 AWS IoT Core. 이 예제의 토큰은 잘려져 있습니다. 사용자의 토큰은 더 길어집니다. AWS IoT Core와 대상을 확인하려면 이 토큰이 필요합니다.
enableUrl
주제 규칙 대상을 확인하기 위해 찾아보는 URL입니다.
messageType
메시지 유형.
### HTTP 작업 대상 확인
AWS CLI를 사용하는 경우 엔드포인트 확인 프로세스를 완료하려면 확인 URL에서 확인 요청을 받은 후 다음 중 하나를 수행해야 합니다.
1.
**대상이 메시지를 수신할 준비가 되었는지 확인**
HTTP 작업 대상이 IoT 메시지를 수신할 준비가 되었는지 확인하려면 확인 요청`enableUrl`에서를 호출하거나 `ConfirmTopicRuleDestination` API 작업을 수행하고 확인 요청`confirmationToken`에서를 전달합니다.
1.
**주제 규칙 상태를 활성화됨으로 설정**
대상에서 메시지를 수신할 수 있는지 확인한 후 `UpdateTopicRuleDestination` API 작업을 수행하여 주제 규칙의 상태를 `ENABLED`로 설정해야 합니다.
AWS IoT 콘솔을 사용하는 경우를 복사`confirmationToken`하여 AWS IoT 콘솔의 대상 확인 대화 상자에 붙여 넣습니다. 그런 다음 주제 규칙을 활성화할 수 있습니다.
### 새 확인 요청 전송하기
대상에 대해 새 확인 메시지를 활성화하려면 `UpdateTopicRuleDestination`을 호출하고 주제 규칙 대상의 상태를 `IN_PROGRESS`로 설정합니다.
새 확인 요청을 전송한 후 확인 프로세스를 반복합니다.
### HTTP 작업 대상 비활성화 및 삭제
대상을 비활성화하려면 `UpdateTopicRuleDestination`을 호출하고 주제 규칙 대상의 상태를 `DISABLED`로 설정합니다. 새 확인 요청을 전송할 필요 없이 DISABLED 상태의 주제 규칙을 다시 사용할 수 있습니다.
HTTP 작업 대상을 삭제하려면를 호출합니다`DeleteTopicRuleDestination`.
## 인증 기관 지원
**참고**
자체 서명된 인증서는 지원되지 않습니다.
HTTP 작업 대상의 HTTPS 엔드포인트는 [AWS Private Certificate Authority](https://www.amazontrust.com/repository/)와 [Lets Encrypt](https://letsencrypt.org/certificates/) 모두에서 발급된 인증서를 지원합니다.
# AWS IoT Events
AWS IoT Events (`iotEvents`) 작업은 MQTT 메시지의 데이터를 AWS IoT Events 입력으로 전송합니다.
**중요**
페이로드가 AWS IoT Core 없이 로 전송`Input attribute Key`되거나 키가 키에 지정된 것과 동일한 JSON 경로에 있지 않으면 오류와 함께 IoT 규칙이 실패합니다`Failed to send message to Iot Events`.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `iotevents:BatchPutMessage` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`batchMode`
(선택 사항) 이벤트 작업을 배치로 처리할지 여부입니다. 기본값은 `false`입니다.
`batchMode`가 `true` 이고 규칙 SQL 문이 배열로 평가되면를 호출하여 AWS IoT 이벤트로 전송할 때 각 배열 요소가 별도의 메시지로 처리됩니다[https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html). 결과 배열의 메시지는 10개를 초과할 수 없습니다.
`batchMode`가 `true`인 경우 `messageId`를 지정할 수 없습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`inputName`
AWS IoT Events 입력의 이름입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`messageId`
(선택 사항) 지정된가 있는 하나의 입력(메시지)만 AWS IoT Events 감지기에 의해 `messageId` 처리되는지 확인하려면이 옵션을 사용합니다. `${newuuid()}` 대체 템플릿을 사용하여 각 요청에 대해 고유한 ID를 생성할 수 있습니다.
`batchMode`가 `true`인 경우 `messageId`을 지정할 수 없습니다--새 UUID 값이 할당됩니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
가 감지 AWS IoT 기에 입력을 전송하도록 허용하는 IAM 역할입니다 AWS IoT Events . 자세한 내용은 [요구 사항](#iotevents-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 IoT Events 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *AWS IoT Events 개발자 안내서*의 [란 무엇입니까 AWS IoT Events?](https://docs.aws.amazon.com/iotevents/latest/developerguide/)
# AWS IoT SiteWise
AWS IoT SiteWise (`iotSiteWise`) 작업은 MQTT 메시지의 데이터를의 자산 속성으로 전송합니다 AWS IoT SiteWise.
사물에서 데이터를 수집하는 방법을 보여주는 자습서를 따를 수 AWS IoT 있습니다. 자세한 내용은 사용 *AWS IoT SiteWise 설명서*의 [AWS IoT 사물에서 로 AWS IoT SiteWise 데이터 수집](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) 자습서 또는 [AWS IoT 코어 규칙을 사용하여 데이터 수집](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) 섹션을 참조하세요.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `iotsitewise:BatchPutAssetPropertyValue` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
아래 예제는 역할에 연결할 수 있는 신뢰 정책을 보여줍니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
보안을 강화하기 위해 `Condition` 속성에서 AWS IoT SiteWise 자산 계층 구조 경로를 지정할 수 있습니다. 다음 예제는 자산 계층 구조 경로를 지정하는 신뢰 정책입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ 이 작업을 AWS IoT SiteWise 사용하여에 데이터를 전송할 때 데이터는 `BatchPutAssetPropertyValue` 작업의 요구 사항을 충족해야 합니다. 자세한 내용은 *AWS IoT SiteWise API 참조*의 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)를 참조하세요.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`putAssetPropertyValueEntries`
각각 다음 정보를 포함하는 자산 속성 값 항목 목록입니다.
`propertyAlias`
(선택 사항) 자산 속성과 연결된 속성 별칭입니다. `propertyAlias` 또는 `assetId`와 `propertyId` 둘 다 지정합니다. 속성 별칭에 대한 자세한 내용은 *AWS IoT SiteWise 사용 설명서*의 [자산 속성에 산업 데이터 스트림 매핑](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html)을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`assetId`
(선택 사항) AWS IoT SiteWise 자산의 ID입니다. `propertyAlias` 또는 `assetId`와 `propertyId` 둘 다 지정합니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`propertyId`
(선택 사항) 자산 속성 ID입니다. `propertyAlias` 또는 `assetId`와 `propertyId` 둘 다 지정합니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`entryId`
(선택 사항) 이 항목의 고유 식별자입니다. 오류 발생 시 오류를 유발한 메시지를 더 잘 추적하도록 `entryId`를 정의합니다. 기본값은 새 UUID입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`propertyValues`
각각 다음 형식의 타임스탬프, 품질 및 값(TQV)을 포함하는 삽입할 속성 값 목록입니다.
`timestamp`
다음 정보가 포함된 타임스탬프 구조입니다.
`timeInSeconds`
Unix Epoch 시간에 초 단위 시간을 포함하는 문자열입니다. 메시지 페이로드에 타임스탬프가 없는 경우 현재 시간을 밀리초 단위로 반환하는 [timestamp()](iot-sql-functions.md#iot-function-timestamp)를 사용할 수 있습니다. 이 시간을 초로 변환하려면 대체 템플릿 **\$1\$1floor(timestamp() / 1E3)\$1**을 사용할 수 있습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`offsetInNanos`
(선택 사항) 초 단위 시간에서 나노초 시간 오프셋을 포함하는 문자열입니다. 메시지 페이로드에 타임스탬프가 없는 경우 현재 시간을 밀리초 단위로 반환하는 [timestamp()](iot-sql-functions.md#iot-function-timestamp)를 사용할 수 있습니다. 해당 시간에서 나노초 시간 오프셋을 계산하려면 대체 템플릿 **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**을 사용할 수 있습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
Unix epoch 시간과 관련하여는 타임스탬프가 과거 최대 7일, 향후 최대 5분인 항목만 AWS IoT SiteWise 허용합니다.
`quality`
(선택 사항) 값의 품질을 설명하는 문자열입니다. 유효한 값: `GOOD`, `BAD`, `UNCERTAIN`.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`value`
자산 속성의 데이터 형식에 따라 다음 값 필드 중 하나를 포함하는 값 구조입니다.
`booleanValue`
(선택 사항) 값 항목의 부울 값을 포함하는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`doubleValue`
(선택 사항) 값 항목의 실수 값을 포함하는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`integerValue`
(선택 사항) 값 항목의 정수 값을 포함하는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`stringValue`
(선택 사항) 값 항목의 문자열 값입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
자산 속성 값을 보낼 수 있는 AWS IoT 권한을 부여하는 IAM 역할의 ARN입니다 AWS IoT SiteWise. 자세한 내용은 [요구 사항](#iotsitewise-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 기본 IoT SiteWise 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 IoT SiteWise 작업을 정의합니다. 이 예제에서는 주제를 속성 별칭 및 `timestamp()` 함수로 사용합니다. 예를 들어 에 데이터를 `/company/windfarm/3/turbine/7/rpm`에 게시하는 경우 이 작업은 지정한 주제와 동일한 속성 별칭을 사용하여 데이터를 자산 속성에 전송합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *AWS IoT SiteWise 사용 설명서*의 [AWS IoT SiteWise란 무엇입니까?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html)
+ *AWS IoT SiteWise 사용 설명서*의 [AWS IoT Core 규칙을 사용하여 데이터 수집](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html)
+ *AWS IoT SiteWise 사용 설명서*의 [AWS IoT 사물 AWS IoT SiteWise 에서 로 데이터 수집](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)
+ *AWS IoT SiteWise 사용 설명서*의 [AWS IoT SiteWise 규칙 작업 문제 해결](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html)
# Firehose
Firehose(`firehose`) 작업을 사용하여 MQTT 메시지의 데이터를 Amazon Data Firehose 스트림에 전송합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `firehose:PutRecord` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서 역할을 선택하거나 생성하여가이 규칙 작업을 수행하도록 허용할 수 AWS IoT 있습니다.
+ Firehose를 사용하여 Amazon S3 버킷으로 데이터를 전송하고 고객 관리형를 AWS KMS 사용하여 Amazon S3에 저장된 데이터를 AWS KMS key 암호화하는 경우 Firehose는 버킷에 대한 액세스 권한과 호출자를 대신하여를 사용할 수 있는 AWS KMS key 권한이 있어야 합니다. 자세한 내용은 *Amazon Data Firehose 개발자 안내서*의 [Firehose에 Amazon S3 대상에 대한 액세스 권한 부여](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3)를 참조하세요.
## 파라미터
이 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`batchMode`
(선택 사항) [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html)를 사용하여 Firehose 스트림을 배치로 전송할지 여부입니다. 기본값은 `false`입니다.
`batchMode`가 `true`이고 규칙의 SQL 문이 Array로 평가되는 경우 각 Array 요소는 `PutRecordBatch` 요청에서 하나의 레코드를 형성합니다. 결과 배열의 레코드는 500개를 초과할 수 없습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`deliveryStreamName`
메시지 데이터를 기록할 Firehose 스트림입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`separator`
(선택 사항) Firehose 스트림에 기록된 레코드를 구분하는 데 사용할 문자 구분 기호입니다. 이 파라미터를 생략하면 스트림에서 구분 기호를 사용하지 않습니다. 유효한 값: `,`(쉼표) `\t`(탭), `\n`(줄 바꿈) `\r\n`(Windows 줄 바꿈).
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`roleArn`
Firehose 스트림에 대한 액세스 권한을 부여하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#kinesis-firehose-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 Firehose 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 Firehose 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon Kinesis Data Firehose 개발자 가이드*의 [Amazon Kinesis Data Firehose란?](https://docs.aws.amazon.com/firehose/latest/dev/)
# Kinesis Data Streams
Kinesis Data Streams(`kinesis`) 규칙 작업은 MQTT 메시지의 데이터를 Amazon Kinesis Data Streams에 전송합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `kinesis:PutRecord` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
+ AWS KMS 고객 관리형 AWS KMS key (KMS 키)를 사용하여 Kinesis Data Streams에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 AWS KMS key 를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [사용자 생성 AWS KMS keys를 사용할 수 있는 권한](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html)을 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`stream`
데이터를 기록할 Kinesis 데이터 스트림입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`partitionKey`
어느 샤드에 데이터를 기록할지 결정하는 데 사용되는 파티션 키입니다. 파티션 키는 일반적으로 표현식(예: `${topic()}` 또는 `${timestamp()}`)으로 구성됩니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
Kinesis 데이터 스트림에 액세스할 수 있는 AWS IoT 권한을 부여하는 IAM 역할의 ARN입니다. 자세한 내용은 [요구 사항](#kinesis-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 Kinesis Data Streams 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 Kinesis 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon Kinesis Data Streams 개발자 안내서*의 [Amazon Kinesis Data Streams란 무엇입니까?](https://docs.aws.amazon.com/streams/latest/dev/)
# Lambda
Lambda(`lambda`) 작업은 AWS Lambda 함수를 호출하여 MQTT 메시지를 전달합니다. Lambda 함수를 비동기적으로 AWS IoT 호출합니다.
Lambda 작업을 사용하여 규칙을 생성하고 테스트하는 방법을 보여주는 자습서를 따라할 수 있습니다. 자세한 내용은 [자습서: AWS Lambda 함수를 사용하여 알림 형식 지정](iot-lambda-rule.md) 단원을 참조하십시오.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ 가 Lambda 함수를 호출 AWS IoT 하려면 `lambda:InvokeFunction` 권한을 부여하는 정책을 구성해야 합니다 AWS IoT. Lambda 정책이 있는 AWS 리전 동일한에 정의된 Lambda 함수만 호출할 수 있습니다. Lambda 함수는 리소스 기반 정책을 사용합니다. 이때 정책은 Lambda 함수 자체에 직접 연결되어야 합니다.
다음 AWS CLI 명령을 사용하여 `lambda:InvokeFunction` 권한을 부여하는 정책을 연결합니다. 이 명령에서 다음과 같이 바꿉니다.
+ *function\$1name*을 Lambda 함수의 이름으로 대체합니다. 함수의 리소스 정책을 업데이트하려면 새 권한을 추가 합니다.
+ 함수 AWS 리전 의이 있는 *region*.
+ 규칙이 정의된 AWS 계정 번호가 포함된 *account-id*입니다.
+ *rule-name*을 Lambda 작업을 정의하려는 AWS IoT 규칙의 이름으로 바꿉니다.
+ *unique\$1id*를 고유 문 식별자로 대체합니다.
**중요**
`source-arn` 또는를 제공하지 않고 AWS IoT 보안 주체에 대한 권한을 추가하는 경우 Lambda 작업으로 규칙을 생성하는 `source-account`는 Lambda 함수를 호출 AWS 계정 하는 규칙을 활성화할 수 있습니다 AWS IoT.
자세한 내용은 [AWS Lambda 권한](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)을 참조하세요.
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ AWS IoT 콘솔을 사용하여 Lambda 규칙 작업에 대한 규칙을 생성하면 Lambda 함수가 자동으로 트리거됩니다. AWS CloudFormation 대신를와 함께 사용하는 경우 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html) 리소스를 추가[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html)해야 합니다. 그런 다음 추가된 리소스는 사용자에게 Lambda 함수를 트리거할 수 있는 권한을 부여합니다.
다음 코드는 이 리소스를 추가하는 방법을 보여주는 예제입니다. 대체 예시:
+ *function\$1name*을 Lambda 함수의 이름으로 대체합니다.
+ 함수 AWS 리전 의이 있는 *region*.
+ 규칙이 정의된 AWS 계정 번호가 포함된 *account-id*입니다.
+ *rule-name*을 Lambda 작업을 정의하려는 AWS IoT 규칙의 이름으로 바꿉니다.
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ AWS KMS 고객 관리형 AWS KMS key 를 사용하여 Lambda에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 AWS KMS key 를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *AWS Lambda 개발자 안내서*의 [저장 시 암호화](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`functionArn`
간접 호출할 Lambda 함수의 ARN은 함수를 간접 호출할 권한이 있어야 AWS IoT 합니다. 자세한 내용은 [요구 사항](#lambda-rule-action-requirements) 단원을 참조하십시오.
Lambda 함수의 버전 또는 별칭을 지정하지 않은 경우, 가장 최신 버전의 함수가 종료됩니다. 특정 버전의 Lambda 함수를 종료하고자 하는 경우 버전 또는 별칭을 지정하면 됩니다. 버전 또는 별칭을 지정하려면 Lambda 함수의 ARN에 버전 또는 별칭을 추가합니다.
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
버전 관리 및 별칭에 대한 자세한 내용은 [AWS Lambda 함수 버전 관리 및 별칭](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html)을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 Lambda 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 Lambda 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *AWS Lambda 개발자 안내서*의 [란 무엇입니까 AWS Lambda?](https://docs.aws.amazon.com/lambda/latest/dg/)
+ [자습서: AWS Lambda 함수를 사용하여 알림 형식 지정](iot-lambda-rule.md)
# Location
Location(`location`) 작업은 지리적 위치 데이터를 [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)로 전송합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `geo:BatchUpdateDevicePosition` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 AWS IoT 역할을 선택하거나 생성할 수 있습니다.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`deviceId`
위치 데이터를 제공하는 디바이스의 고유 ID입니다. 자세한 내용은 *Amazon Location Service API 참조*의 [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html) 섹션을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`latitude`
디바이스 위치의 위도를 나타내는 double 값으로 평가되는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`longitude`
디바이스 위치의 경도를 나타내는 double 값으로 평가되는 문자열입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
Amazon Location Service 도메인에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#location-rule-action-requirements) 단원을 참조하십시오.
`timestamp`
위치 데이터가 샘플링된 시간입니다. 기본값은 MQTT 메시지가 처리된 시간입니다.
`timestamp` 값은 다음 두 값으로 구성됩니다.
+ `value`: 긴 Epoch 시간 값을 반환하는 표현식입니다. [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 함수를 사용하여 메시지 페이로드에 전달된 날짜 또는 시간 값에서 유효한 타임스탬프를 만들 수 있습니다. [대체 템플릿](iot-substitution-templates.md) 지원: 예.
+ `unit`: (선택 사항) `value`에 설명된 표현식에서 기인하는 타임스탬프 값의 정밀도입니다. 유효한 값: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. 기본값은 `MILLISECONDS`입니다. [대체 템플릿](iot-substitution-templates.md): API 및 AWS CLI 만 지원합니다.
`trackerName`
위치가 업데이트되는 Amazon Location의 추적기 리소스 이름입니다. 자세한 정보는 *Amazon Location Service 개발자 안내서*의 [추적기](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview)를 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 Location 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿이 있는 위치 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
다음 MQTT 페이로드 예시는 위 예시의 대체 템플릿이 데이터에 액세스하는 방법을 보여줍니다. [https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) CLI 명령을 사용하여 MQTT 페이로드 데이터가 위치 추적기에 전달되는지 확인할 수 있습니다.
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## 다음 사항도 참조하세요.
+ *Amazon Location Service Developer Guide*(Amazon Location Service 개발자 안내서)의 [What is Amazon Location Service?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)(Amazon Location Service란 무엇인가요?)
# OpenSearch
OpenSearch(`openSearch`) 작업을 사용하여 MQTT 메시지의 데이터를 Amazon OpenSearch Service 도메인에 전송합니다. 그런 다음 OpenSearch 대시보드와 같은 도구를 사용하여 OpenSearch Service에서 데이터를 쿼리하고 시각화할 수 있습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `es:ESHttpPut` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
+ 고객 관리형 AWS KMS key 를 사용하여 OpenSearch Service에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 KMS 키를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon OpenSearch Service 개발자 안내서*의 [Amazon OpenSearch Service의 저장 시 데이터 암호화](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`endpoint`
Amazon OpenSearch Service 도메인의 엔드포인트입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`index`
데이터를 저장할 OpenSearch 인덱스입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`type`
저장 중인 문서의 유형입니다.
OpenSearch 버전이 1.0 이상인 경우 `type` 파라미터 값은 `_doc`여야 합니다. 자세한 내용은 [OpenSearch 설명서](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields)를 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`id`
각 문서의 고유 식별자입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleARN`
OpenSearch 도메인에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#opensearch-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 제한 사항
OpenSearch(`openSearch`) 작업은 VPC Elasticsearch 클러스터로 데이터를 전달하는 데 사용할 수 없습니다.
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 OpenSearch 작업을 정의하고 `OpenSearch` 작업에 대한 필드를 지정하는 방법을 정의합니다. 자세한 내용은 [OpenSearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_OpenSearchAction.html)을 참조하세요.
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 OpenSearch 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**참고**
대체 `type` 필드는 OpenSearch 버전 1.0에서 작동합니다. 1.0 이후 버전에서는 `type`의 값이 `_doc`여야 합니다.
## 다음 사항도 참조하세요.
*Amazon OpenSearch Service 개발자 가이드*의 [Amazon OpenSearch Service란 무엇입니까?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# 재게시
다시 게시(`republish`) 작업은 MQTT 메시지를 다른 MQTT 주제에 다시 게시합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `iot:Publish` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`headers`
MQTT 버전 5.0 헤더 정보입니다.
자세한 내용은 *AWS API 참조*의 [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) 및 [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html)를 참조하세요.
`topic`
메시지를 재게시할 MQTT 주제입니다.
`$`로 시작하는 예약된 주제에 게시하려면 대신 `$$`를 사용하세요. 예를 들어 디바이스 섀도우 주제 `$aws/things/MyThing/shadow/update`에 다시 게시하려면 주제를 `$$aws/things/MyThing/shadow/update`로 지정합니다.
[예약된 작업 주제](reserved-topics.md#reserved-topics-job)에 다시 게시하는 것은 지원되지 않습니다.
AWS IoT Device Defender 예약 주제는 HTTP 게시를 지원하지 않습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`qos`
(선택 사항) 메시지를 다시 게시할 때 사용할 서비스 품질(QoS) 수준입니다. 유효한 값: `0`, `1`. 기본값은 `0`입니다. MQTT QoS에 대한 자세한 내용은 [MQTT](mqtt.md) 섹션을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`roleArn`
가 MQTT 주제에 AWS IoT 게시하도록 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#republish-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 재게시 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 재게시 작업을 정의합니다.
```
{
"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"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙`headers`에서를 사용하여 재게시 작업을 정의합니다.
```
{
"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": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**참고**
원본 소스 IP는 [재게시 작업](#republish-rule-action)을 거쳐 전달되지 않습니다.
# S3
S3(`s3`) 작업은 MQTT 메시지의 데이터를 Amazon Simple Storage Service(Amazon S3) 버킷에 기록합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `s3:PutObject` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
+ AWS KMS customermanaged를 사용하여 Amazon S3의 저장 데이터를 암호화하는 경우 호출자를 대신하여 AWS KMS key 를 AWS KMS key 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon Simple Storage Service 개발자 안내서*의 [AWS 관리형 AWS KMS keys 및 고객 관리 AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks)형을 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`bucket`
데이터를 기록할 Amazon S3 버킷입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`cannedacl`
(선택 사항) 객체 키로 식별된 객체에 대한 액세스를 제어할 수 있도록 Amazon S3에서 미리 정의된 ACL입니다. 허용 값을 포함하여 자세한 내용은 [미리 정의된 ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl)을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`key`
데이터가 기록되는 파일의 경로입니다.
이 파라미터가 `${topic()}/${timestamp()}`이고 규칙이 주제가 `some/topic`인 메시지를 수신하는 예를 고려하세요. 현재 타임스탬프가 `1460685389`인 경우 이 작업은 S3 버킷의 `some/topic` 폴더에 있는 `1460685389`라는 파일에 데이터를 씁니다.
정적 키를 사용하는 경우는 규칙이 호출할 때마다 단일 파일을 AWS IoT 덮어씁니다. 메시지 타임스탬프 또는 다른 고유한 메시지 식별자를 사용하는 것이 좋습니다. 그러면 각 메시지가 수신될 때마다 Amazon S3에 새 파일이 저장됩니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
Amazon S3 버킷에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#s3-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 S3 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon Simple Storage Service 사용 설명서*의 [Amazon S3란 무엇입니까?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)
# Salesforce IoT
Salesforce IoT(`salesforce`) 작업은 규칙을 트리거한 MQTT 메시지의 데이터를 Salesforce IoT 입력 스트림에 전송합니다.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`url`
Salesforce IoT 입력 스트림에서 공개한 URL입니다. 이 URL은 입력 스트림을 만들 때 Salesforce IoT 플랫폼에서 제공합니다. 자세한 내용은 Salesforce IoT 설명서를 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`token`
지정된 Salesforce IoT 입력 스트림에 대한 액세스를 인증하는 데 사용되는 토큰입니다. 이 토큰은 입력 스트림을 만들 때 Salesforce IoT 플랫폼에서 제공합니다. 자세한 내용은 Salesforce IoT 설명서를 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 Salesforce IoT 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
}
```
# SNS
SNS(`sns`) 작업은 MQTT 메시지의 데이터를 Amazon Simple Notification Service(Amazon SNS) 푸시 알림으로서 전송합니다.
SNS 작업을 사용하여 규칙을 생성하고 테스트하는 방법을 보여주는 자습서를 따라할 수 있습니다. 자세한 내용은 [자습서: Amazon SNS 알림 전송](iot-sns-rule.md) 단원을 참조하세요.
**참고**
SNS 작업은 [Amazon SNS 주제 FIFO(선입선출)](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)를 지원하지 않습니다. 규칙 엔진은 완전 분산형 서비스이므로 SNS 작업이 호출되는 메시지 순서가 보장되지 않습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `sns:Publish` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
+ AWS KMS 고객 관리형 AWS KMS key 를 사용하여 Amazon SNS에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 AWS KMS key 를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 *Amazon Simple Notification Service 개발자 안내서*의 [키 관리](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`targetArn`
푸시 알림이 전송될 SNS 주제 또는 개별 디바이스입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`messageFormat`
(선택 사항) 메시지 형식입니다. Amazon SNS는 이 설정을 사용하여 페이로드를 구문 분석하고 페이로드의 해당 플랫폼별 부분을 추출할지 여부를 결정합니다. 유효한 값: `JSON`, `RAW`. 기본값은 `RAW`입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`roleArn`
SNS에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#sns-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제는 AWS IoT 규칙에서 SNS 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 SNS 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon Simple Notification Service 개발자 가이드*의 [Amazon Simple Notification Service란?](https://docs.aws.amazon.com/sns/latest/dg/)
+ [자습서: Amazon SNS 알림 전송](iot-sns-rule.md)
# SQS
SQS(`sqs`) 작업은 MQTT 메시지의 데이터를 Amazon Simple Queue Service(Amazon SQS) 대기열에 전송합니다.
**참고**
SQS 작업은 [Amazon SQS 대기열 FIFO(선입선출)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html)를 지원하지 않습니다. 규칙 엔진은 완전 분산형 서비스이므로 SQS 작업이 트리거되는 메시지 순서가 보장되지 않습니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `sqs:SendMessage` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
+ AWS KMS 고객 관리형를 사용하여 Amazon AWS KMS key SQS에서 저장 데이터를 암호화하는 경우 호출자를 대신하여 AWS KMS key 를 사용할 수 있는 권한이 서비스에 있어야 합니다. Amazon SQS 자세한 내용은 *Amazon Simple Queue Service 개발자 안내서*의 [키 관리](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)를 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`queueUrl`
데이터를 기록할 Amazon SQS 대기열의 URL입니다. 이 URL의 리전은 [AWS IoT 규칙](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) AWS 리전 과 같을 필요가 없습니다.
SQS 규칙 작업을 사용하여 데이터 전송 크로스 AWS 리전 에 대한 추가 요금이 발생할 수 있습니다. 자세한 내용은 [Amazon SQS 요금](https://aws.amazon.com/sqs/pricing/)을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`useBase64`
이 파라미터를 `true`로 설정하여 메시지 데이터가 Amazon SQS 대기열에 기록되기 전에 메시지 데이터를 base64로 인코딩하도록 규칙 작업을 구성합니다. 기본값은 `false`입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`roleArn`
Amazon SQS 대기열에 대한 액세스를 허용하는 IAM 역할입니다. 자세한 내용은 [요구 사항](#sqs-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 SQS 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
다음 JSON 예제에서는 AWS IoT 규칙에서 대체 템플릿을 사용하여 SQS 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *Amazon Simple Queue Service 개발자 안내서*의 [Amazon Simple Queue Service 란?](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/)
# 단계 함수
Step Functions(`stepFunctions`) 작업은 AWS Step Functions 상태 시스템을 시작합니다.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `states:StartExecution` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택하거나 생성할 수 AWS IoT 있습니다.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`stateMachineName`
시작할 Step Functions 상태 머신 이름.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`executionNamePrefix`
(선택 사항) 뒤에 UUID가 붙는 이 접두사로 이루어진 상태 머신 실행에 부여된 이름. Step Functions는 각 상태 머신 실행에 제공된 고유한 이름이 없는 경우 고유한 이름을 생성합니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
상태 시스템을 시작할 수 있는 AWS IoT 권한을 부여하는 역할의 ARN입니다. 자세한 내용은 [요구 사항](#stepfunctions-rule-action-requirements) 단원을 참조하십시오.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니오
## 예제
다음 JSON 예제에서는 AWS IoT 규칙에서 Step Functions 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## 다음 사항도 참조하세요.
+ *AWS Step Functions 개발자 안내서*의 [란 무엇입니까 AWS Step Functions?](https://docs.aws.amazon.com/step-functions/latest/dg/)
# Timestream
Timestream 규칙 작업은 MQTT 메시지의 속성(측정값)을 Amazon Timestream 테이블에 기록합니다. Amazon Timestream 에 대한 자세한 내용은 [Amazon Timestream 이란?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html)을 참조하세요.
**참고**
일부 AWS 리전에서는 Amazon Timestream을 사용할 수 없습니다. 리전에서 Amazon Timestream을 사용할 수 없는 경우 규칙 작업 목록에 해당 Timestream이 나타나지 않습니다.
이 규칙이 Timestream 데이터베이스에 저장하는 속성은 규칙의 쿼리 문에서 가져온 속성입니다. 쿼리 문의 결과에 있는 각 속성의 값은 데이터 유형을 추론하기 위해 구문 분석됩니다(예: [DynamoDBv2](dynamodb-v2-rule-action.md) 작업). 각 속성의 값은 Timestream 테이블의 자체 레코드에 기록됩니다. 속성의 데이터 유형을 지정하거나 변경하려면 쿼리 문에서 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 함수를 사용합니다. 각 Timestream 레코드의 내용에 대한 자세한 내용은 [Timestream 레코드 내용](#timestream-rule-action-data) 섹션을 참조하세요.
**참고**
SQL V2(2016-03-23)에서는 `10.0`과 같은 정수인 숫자 값이 정수 표현(`10`)으로 변환됩니다. [cast()](iot-sql-functions.md#iot-sql-function-cast) 함수를 사용하는 것과 같이 명시적으로 `Decimal` 값으로 캐스팅해도 결과는 바뀌지 않습니다. 결과는 여전히 `Integer` 값입니다. 이로 인해 형식 불일치 오류가 발생하여 Timestream 데이터베이스에 데이터가 기록되지 않을 수 있습니다. 정수 숫자 값을 `Decimal` 값으로 처리하려면 규칙 쿼리 문에 SQL V1(2015-10-08)을 사용하세요.
**참고**
Timestream 규칙 작업이 Amazon Timestream 테이블에 쓸 수 있는 최대 값 수는 100입니다. 자세한 내용은 [Amazon Timestream 할당량 참조](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default)를 참조하세요.
## 요구 사항
이 규칙 작업은 다음 요구 사항을 충족해야 합니다.
+ `timestream:DescribeEndpoints` 및 `timestream:WriteRecords` 작업을 수행하기 위해가 맡을 AWS IoT 수 있는 IAM 역할입니다. 자세한 내용은 [AWS IoT 규칙에 필요한 액세스 권한 부여](iot-create-role.md) 단원을 참조하십시오.
AWS IoT 콘솔에서가이 규칙 작업을 수행하도록 허용하는 역할을 선택, 업데이트 또는 생성할 수 AWS IoT 있습니다.
+ 고객-를 사용하여 Timestream에서 저장 데이터를 암호화하는 경우 호출 AWS KMS key 자를 대신하여 AWS KMS 를 사용할 수 있는 권한이 서비스에 있어야 합니다. 자세한 내용은 [AWS 서비스에서 AWS KMS를 사용하는 방법을](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html) 참조하세요.
## 파라미터
이 작업으로 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.
`databaseName`
이 작업에서 생성되는 레코드를 수신할 테이블이 있는 Amazon Timestream 데이터베이스의 이름입니다. 또한 `tableName` 단원도 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`dimensions`
각 측정값 레코드에 기록되는 시계열의 메타데이터 속성입니다. 예를 들어 EC2 인스턴스의 이름 및 가용 영역 또는 풍력 터빈 제조업체 이름은 차원입니다.
`name`
메타데이터 차원 이름입니다. 데이터베이스 테이블 레코드 열의 이름입니다.
차원 이름은 `measure_name`, `measure_value` 또는 `time`으로 지정할 수 없습니다. 이러한 이름은 예약되어 있습니다. 차원 이름은 `ts_` 또는 `measure_value`로 시작할 수 없으며 콜론(`:`) 문자를 포함할 수 없습니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`value`
데이터베이스 레코드의 이 열에 쓸 값입니다.
[대체 템플릿](iot-substitution-templates.md) 지원: 예
`roleArn`
Timestream 데이터베이스 테이블에 쓸 수 있는 권한을 AWS IoT 에 부여하는 역할의 Amazon 리소스 이름(ARN)입니다. 자세한 내용은 [요구 사항](#timestream-rule-action-requirements) 단원을 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: 아니요
`tableName`
측정값 레코드를 기록할 데이터베이스 테이블의 이름입니다. 또한 `databaseName` 단원도 참조하세요.
[대체 템플릿](iot-substitution-templates.md) 지원: API 및 AWS CLI 만 해당
`timestamp`
항목의 타임스탬프에 사용할 값입니다. 비워 두면 항목이 처리된 시간이 사용됩니다.
`unit`
`value`에 설명된 표현식에서 기인하는 타임스탬프 값의 정밀도입니다.
유효한 값: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. 기본값은 `MILLISECONDS`입니다.
`value`
긴 Epoch 시간 값을 반환하는 표현식입니다.
[time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 함수를 사용하여 메시지 페이로드에 전달된 날짜 또는 시간 값에서 유효한 타임스탬프를 만들 수 있습니다.
## Timestream 레코드 내용
이 작업을 통해 Amazon Timestream 테이블에 기록된 데이터에는 타임스탬프, Timestream 규칙 작업의 메타데이터 및 규칙 쿼리 문의 결과가 포함됩니다.
쿼리 문의 결과에 있는 각 속성(측정값)에 대해 이 규칙 작업은 지정된 Timestream 테이블에 레코드를 기록합니다.
| 열 이름 | 속성 유형 | 값 | 설명 |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSION | Timestream 규칙 작업 항목에 지정된 값입니다. | 규칙 작업 항목에 지정된 각 **차원**은 차원 이름을 사용하여 Timestream 데이터베이스에 열을 생성합니다. |
| measure\$1name | MEASURE\$1NAME | 속성의 이름 | `measure_value::data-type` 열에 값이 지정된 쿼리 문의 결과에 있는 속성의 이름입니다. |
| measure\$1value::*data-type* | MEASURE\$1VALUE | 쿼리 문의 결과에 있는 속성 값입니다. 속성의 이름은 `measure_name` 열에 있습니다. | 값은 해석되고\$1 `bigint`, `boolean`, `double` 또는 `varchar` 중 가장 일치하는 항목으로 캐스팅됩니다. Amazon Timestream은 각 데이터 유형에 대해 별도의 열을 생성합니다. 규칙의 쿼리 문에서 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 함수를 사용하여 메시지의 값을 다른 데이터 형식으로 캐스팅할 수 있습니다. |
| 시간 | TIMESTAMP | 데이터베이스에 있는 레코드의 날짜 및 시간입니다. | 이 값은 정의된 경우 규칙 엔진 또는 `timestamp` 속성에 의해 지정됩니다. |
\$1 메시지 페이로드에서 읽은 속성 값은 다음과 같이 해석됩니다. 이러한 각 경우에 대한 설명은 [예제](#timestream-rule-action-examples)를 참조하세요.
+ 인용되지 않은 값 `true` 또는 `false`는 `boolean` 유형으로 해석됩니다.
+ 십진수는 `double` 유형으로 해석됩니다.
+ 소수점이 없는 숫자 값은 `bigint` 유형으로 해석됩니다.
+ 따옴표로 묶인 문자열은 `varchar` 유형으로 해석됩니다.
+ 객체 및 배열 값은 JSON 문자열로 변환되어 `varchar` 유형으로 저장됩니다.
## 예제
다음 JSON 예제에서는 규칙에서 대체 템플릿을 사용하여 Timestream AWS IoT 규칙 작업을 정의합니다.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
다음 메시지 페이로드와 함께 이전 예에서 정의한 Timestream 주제 규칙 작업을 사용하면 다음 테이블에 Amazon Timestream 레코드가 작성됩니다.
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
다음 테이블에는 지정된 주제 규칙 작업을 사용하여 이전 메시지 페이로드를 처리하는 데이터베이스 열과 레코드가 표시됩니다. `device_firmware_sku` 및 `device_id` 열은 주제 규칙 작업에 정의된 DIMENSIONS입니다. Timestream 주제 규칙 작업은 `time` 열과 `measure_name` 및 `measure_value::*` 열을 생성하며, 이를 주제 규칙 작업의 쿼리 문의 결과 값으로 채웁니다.
| device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | 시간 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | string\$1value | - | 문자열 값 | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | 문자열 배열 | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| My Static Metadata | iotconsole-159EXAMPLE738-0 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## 규칙 문제 해결
규칙에 문제가 있는 경우 CloudWatch Logs를 활성화하는 것이 좋습니다. 로그를 분석하여 문제가 권한 부여인지 또는 예를 들어 WHERE 절 조건이 일치하지 않는지 여부를 확인할 수 있습니다. 자세한 내용은 [Amazon CloudWatch Logs 설정](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html)을 참조하세요.
# AWS IoT 규칙을 사용하여 교차 계정 리소스에 액세스
한 계정의 MQTT 주제에 수집된 데이터를 다른 계정의 Amazon SQS 및 Lambda와 같은 AWS 서비스로 라우팅할 수 있도록 교차 계정 액세스 AWS IoT 규칙을 구성할 수 있습니다. 다음은 한 계정의 MQTT 주제에서 다른 계정의 대상으로 교차 계정 데이터 수집 AWS IoT 규칙을 설정하는 방법을 설명합니다.
대상 리소스에 대한 [리소스 기반 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions)을 사용하여 교차 계정 규칙을 구성할 수 있습니다. 따라서 AWS IoT 규칙을 사용하여 교차 계정 액세스에는 리소스 기반 권한을 지원하는 대상만 활성화할 수 있습니다. 지원되는 대상에는 Amazon SQS, Amazon SNS, Amazon S3 및 AWS Lambda가 있습니다.
**참고**
Amazon SQS를 제외한 지원되는 대상의 경우 규칙 작업이 해당 리소스와 상호 작용할 수 있도록 다른 서비스의 리소스 AWS 리전 와 동일한에서 규칙을 정의해야 합니다. AWS IoT 규칙 작업에 대한 자세한 내용은 [AWS IoT 규칙 작업을](iot-rule-actions.md) 참조하세요. 규칙의 SQS 작업에 대한 자세한 내용은 [SQS](sqs-rule-action.md) 섹션을 참조하세요.
## 사전 조건
+ [AWS IoT 규칙](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) 숙지
+ IAM [사용자](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html), [역할](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 및 [리소스 기반 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions)에 대한 이해
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)가 설치되어 있음
## Amazon SQS에 대한 교차 계정 설정
시나리오: 계정 A는 MQTT 메시지의 데이터를 계정 B의 Amazon SQS 대기열에 전송합니다.
| AWS 계정 | 계정 이름 | 설명 |
| --- | --- | --- |
| 1111-1111-1111 | 계정 A | 규칙 작업: sqs:SendMessage |
| 2222-2222-2222 | 계정 B | Amazon SQS 대기열 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**참고**
대상 Amazon SQS 대기열이 [AWS IoT 규칙](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) AWS 리전 과 동일한에 있을 필요는 없습니다. 규칙의 SQS 작업에 대한 자세한 내용은 [SQS](sqs-rule-action.md) 섹션을 참조하세요.
**계정 A 태스크 수행**
**Note**
다음 명령을 실행하려면 규칙의 Amazon 리소스 이름(ARN)을 리소스로 사용하는 `iot:CreateTopicRule`에 대한 권한과 리소스를 역할의 ARN으로 사용하는 `iam:PassRole` 작업에 대한 권한이 IAM 사용자에게 있어야 합니다.
1. 계정 A의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. AWS IoT 규칙 엔진을 신뢰하고 계정 B의 Amazon SQS 대기열에 대한 액세스를 허용하는 정책을 연결하는 IAM 역할을 생성합니다. [필요한 액세스 권한 부여의 명령 및 정책 문서 예제 AWS IoT 를 참조하세요](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. 주제에 연결된 규칙을 생성하려면 [create-topic-rule 명령](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)을 실행합니다.
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
다음은 `iot/test` 주제에 전송된 모든 메시지를 지정된 Amazon SQS 대기열에 삽입하는 규칙이 있는 페이로드 파일의 예입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 Amazon SQS 대기열에 메시지를 추가할 수 있는 권한을 AWS IoT 에 부여합니다.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
AWS IoT 규칙에서 Amazon SQS 작업을 정의하는 방법에 대한 자세한 내용은 [AWS IoT 규칙 작업 - Amazon SQS](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)를 참조하세요.
**계정 B 태스크 수행**
1. 계정 B의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. Amazon SQS 대기열 리소스에 대한 권한을 계정 A에 부여하려면 [add-permission 명령](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html)을 실행합니다.
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Amazon SNS를 위한 교차 계정 설정
시나리오: 계정 A는 MQTT 메시지의 데이터를 계정 B의 Amazon SNS 주제에 전송합니다.
| AWS 계정 | 계정 이름 | 설명 |
| --- | --- | --- |
| 1111-1111-1111 | 계정 A | 규칙 작업: sns:Publish |
| 2222-2222-2222 | 계정 B | Amazon SNS 주제 ARN: arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**계정 A 태스크 수행**
**참고**
다음 명령을 실행하려면 규칙 ARN을 리소스로 사용하는 `iot:CreateTopicRule`에 대한 권한과 리소스를 역할 ARN으로 사용하는 `iam:PassRole` 작업에 대한 권한이 IAM 사용자에게 있어야 합니다.
1. 계정 A의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. AWS IoT 규칙 엔진을 신뢰하는 IAM 역할을 생성하고 계정 B의 Amazon SNS 주제에 대한 액세스를 허용하는 정책을 연결합니다. 예제 명령 및 정책 문서는 [필요한 액세스 권한 부여 AWS IoT 를 참조하세요](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. 주제에 연결된 규칙을 생성하려면 [create-topic-rule 명령](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)을 실행합니다.
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
다음은 `iot/test` 주제에 전송된 모든 메시지를 지정된 Amazon SNS 주제에 삽입하는 규칙이 있는 예제 페이로드 파일입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 Amazon SNS 주제에 메시지를 전송할 수 있는 권한을 AWS IoT 에 부여합니다.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
AWS IoT 규칙에서 Amazon SNS 작업을 정의하는 방법에 대한 자세한 내용은 [AWS IoT 규칙 작업 - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html)를 참조하세요.
**계정 B 태스크 수행**
1. 계정 B의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. Amazon SNS 주제 리소스에 대한 권한을 계정 A에 부여하려면 [add-permission 명령](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html)을 실행합니다.
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Amazon S3를 위한 교차 계정 설정
시나리오: 계정 A는 MQTT 메시지의 데이터를 계정 B의 Amazon S3 버킷에 전송합니다.
| AWS 계정 | 계정 이름 | 설명 |
| --- | --- | --- |
| 1111-1111-1111 | 계정 A | 규칙 작업: s3:PutObject |
| 2222-2222-2222 | 계정 B | Amazon S3 버킷 ARN: arn:aws:s3:::amzn-s3-demo-bucket |
**계정 A 태스크 수행**
**Note**
다음 명령을 실행하려면 규칙 ARN을 리소스로 사용하는 `iot:CreateTopicRule`에 대한 권한과 리소스를 역할 ARN으로 사용하는 `iam:PassRole` 작업에 대한 권한이 IAM 사용자에게 있어야 합니다.
1. 계정 A의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. AWS IoT 규칙 엔진을 신뢰하고 계정 B의 Amazon S3 버킷에 대한 액세스를 허용하는 정책을 연결하는 IAM 역할을 생성합니다. 예제 명령 및 정책 문서는 [필요한 액세스 권한 부여 AWS IoT 를 참조하세요](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. 대상 S3에 연결된 규칙을 생성하려면 [create-topic-rule 명령](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)을 실행합니다.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
다음 예제는 `iot/test` 주제에 전송된 모든 메시지를 지정된 Amazon S3 버킷에 삽입하는 규칙을 포함한 페이로드 파일입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 Amazon S3 버킷에 메시지를 추가할 수 있는 권한을 AWS IoT 에 부여합니다.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
AWS IoT 규칙에서 Amazon S3 작업을 정의하는 방법에 대한 자세한 내용은 [AWS IoT 규칙 작업 - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html)를 참조하세요.
**계정 B 태스크 수행**
1. 계정 B의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. 계정 A의 보안 주체를 신뢰하는 버킷 정책을 만듭니다.
다음 예제는 다른 계정의 보안 주체를 신뢰하는 버킷 정책을 정의하는 페이로드 파일입니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
자세한 정보는 [버킷 정책 예제](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1) 단원을 참조하세요.
1. 버킷 정책을 지정된 버킷에 연결하려면 [put-bucket-policy 명령](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html)을 실행합니다.
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. 교차 계정 액세스가 작동하도록 하려면 **모든 퍼블릭 액세스 차단(Block all public access)** 설정이 올바른지 확인하세요. 자세한 내용은 [Amazon S3 보안 모범 사례](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html)를 참조하세요.
## 에 대한 교차 계정 설정 AWS Lambda
시나리오: 계정 A는 계정 B의 AWS Lambda 함수를 호출하여 MQTT 메시지를 전달합니다.
| AWS 계정 | 계정 이름 | 설명 |
| --- | --- | --- |
| 1111-1111-1111 | 계정 A | 규칙 작업: lambda:InvokeFunction |
| 2222-2222-2222 | 계정 B | Lambda 함수 ARN: arn:aws:lambda:region:2222-2222-2222:function:example-function |
**계정 A 태스크 수행**
**참고**
다음 명령을 실행하려면 규칙 ARN을 리소스로 사용하는 `iot:CreateTopicRule`에 대한 권한과 리소스를 역할 ARN으로 사용하는 `iam:PassRole` 작업에 대한 권한이 IAM 사용자에게 있어야 합니다.
1. 계정 A의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. [create-topic-rule 명령](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)을 실행하여 계정 B의 Lambda 함수에 대한 교차 계정 액세스를 정의하는 규칙을 생성합니다.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
다음 예제는 `iot/test` 주제에 전송된 모든 메시지를 지정된 Lambda 함수에 삽입하는 규칙을 포함한 페이로드 파일입니다. SQL 문은 메시지를 필터링하고 역할 ARN은 Lambda 함수에 데이터를 전달할 수 있는 권한을 AWS IoT 에 부여합니다.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
규칙에서 AWS Lambda 작업을 정의하는 방법에 대한 자세한 내용은 [AWS IoT 규칙 작업 - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html)를 AWS IoT 참조하십시오.
**계정 B 태스크 수행**
1. 계정 B의 IAM 사용자를 사용하여 [AWS CLI를 구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)합니다.
1. [Lambda의 add-permission 명령을](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 실행하여 Lambda 함수를 활성화할 수 있는 권한을 AWS IoT 규칙에 부여합니다. 다음 명령을 실행하려면 IAM 사용자에게 `lambda:AddPermission` 작업에 대한 권한이 있어야 합니다.
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**옵션:**
**--principal**
이 필드는 AWS IoT (로 표시됨`iot.amazonaws.com`)에 Lambda 함수를 호출할 수 있는 권한을 부여합니다.
**--source-arn**
이 필드는 AWS IoT 의 `arn:aws:iot:region:1111-1111-1111:rule/example-rule`만 이 Lambda 함수를 트리거하고 동일하거나 다른 계정의 다른 규칙이 이 Lambda 함수를 활성화할 수 없도록 확정합니다.
**--source-account**
이 필드는이 `1111-1111-1111` 계정을 대신하여이 Lambda 함수를 AWS IoT 활성화함을 확인합니다.
**참고**
**구성** 아래의 AWS Lambda 함수 콘솔에서 "규칙을 찾을 수 없습니다"라는 오류 메시지가 표시되면 오류 메시지를 무시하고 연결 테스트를 진행하세요.
# 오류 처리(오류 작업)
가 디바이스에서 메시지를 AWS IoT 수신하면 규칙 엔진은 메시지가 규칙과 일치하는지 확인합니다. 일치할 경우에는 규칙의 쿼리 문을 평가하고, 규칙의 작업을 활성화한 다음 쿼리 문의 결과를 전달합니다.
작업 활성화 시 문제가 발생하면 해당 규칙에 지정되어 있는 경우에 한해 규칙 엔진이 오류 작업을 활성화합니다. 다음과 같은 경우가 이에 해당합니다.
+ Amazon S3 버킷에 액세스할 수 있는 권한이 규칙에 없는 경우.
+ 사용자 실수로 DynamoDB 프로비저닝 처리량을 초과하는 경우.
**참고**
이 주제에서 다루는 오류 처리는 [규칙 작업](iot-rule-actions.md)을 위한 것입니다. 외부 함수를 포함한 SQL 문제를 디버깅하려면 AWS IoT 로깅을 설정할 수 있습니다. 자세한 내용은 [AWS IoT 로깅 구성](configure-logging.md) 단원을 참조하십시오.
## 오류 작업 메시지 형식
규칙마다 생성되는 메시지는 1개입니다. 예를 들어 동일한 규칙에서 2개의 규칙 작업이 오류로 중단되더라도 오류 작업은 오류 2개가 모두 포함된 메시지 1개를 수신합니다.
오류 작업 메시지는 다음 예제와 같습니다.
```
{
"ruleName": "TestAction",
"topic": "testme/action",
"cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7",
"clientId": "iotconsole-1511213971966-0",
"base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9",
"failures": [
{
"failedAction": "S3Action",
"failedResource": "us-east-1-s3-verify-user",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y="
}
]
}
```
ruleName
오류 작업을 트리거한 규칙의 이름입니다.
주제
최초 메시지가 수신된 주제입니다.
cloudwatchTraceId
CloudWatch의 오류 로그를 참조하는 고유 ID입니다.
clientId
메시지 게시자의 클라이언트 ID입니다.
base64OriginalPayload
Base64로 인코딩된 최초의 메시지 페이로드입니다.
failures
failedAction
오류로 중단된 작업의 이름입니다(예: "S3Action").
failedResource
리소스 이름입니다(예: S3 버킷 이름).
errorMessage
오류에 대한 설명입니다.
## 오류 작업 예제
아래는 추가된 오류 작업을 포함한 규칙 예제입니다. 이 규칙에는 메시지 데이터를 DynamoDB 테이블에 기록하는 작업과 데이터를 Amazon S3 버킷에 기록하는 오류 작업이 있습니다.
```
{
"sql" : "SELECT * FROM ..."
"actions" : [{
"dynamoDB" : {
"table" : "PoorlyConfiguredTable",
"hashKeyField" : "AConstantString",
"hashKeyValue" : "AHashKey"}}
],
"errorAction" : {
"s3" : {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
, [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), , , , , , 등의 외부 [함수](iot-sql-functions.md)를 포함하여 오류 작업의 SQL 문에서 모든 함수 또는 [대체 템플릿을](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) 사용할 수 [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) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)있습니다[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 규칙 생성을 참조하세요](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html).
CloudWatch를 사용하여 규칙의 성공 또는 실패 여부를 모니터링하는 방법에 대한 자세한 내용은 [AWS IoT 지표 및 차원](metrics_dimensions.md) 단원을 참조하세요.
# Basic Ingest를 통한 메시징 비용 절감
기본 수집을 사용하면 [AWS IoT 규칙 작업](iot-rule-actions.md)에서 지원하는 AWS 서비스로 디바이스 데이터를 안전하게 전송할 수 있으며, 이때 [메시징 요금](https://aws.amazon.com/iot-core/pricing/)이 발생하지 않습니다. 기본 수집은 수집 경로에서 게시/구독 메시지 브로커를 제거해 데이터 흐름을 최적화합니다.
기본 수집은 디바이스 또는 애플리케이션에서 메시지를 전송할 수 있습니다. 메시지에는 처음 3개 수준에 대한 `$aws/rules/rule_name`으로 시작하는 주제 이름이 있으며, 여기서 `rule_name`은 호출하려는 AWS IoT 규칙의 이름입니다.
일반적으로 규칙을 호출하는 데 사용하는 메시지 주제에 기본 수집 접두사(`$aws/rules/rule_name`)를 추가하면 기본 수집과 함께 기존 규칙을 사용할 수 있습니다. 예를 들어, `Buildings/Building5/Floor2/Room201/Lights`(`"sql": "SELECT * FROM 'Buildings/#'"`)와 같은 주제가 포함된 메시지로 호출되는 `BuildingManager`라는 규칙이 있는 경우 `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights` 주제가 포함된 메시지를 전송해 기본 수집과 함께 동일한 규칙을 호출할 수 있습니다.
**참고**
디바이스 및 규칙은 Basic Ingest 예약 주제를 구독할 수 없습니다. 예를 들어 AWS IoT Device Defender 지표 `num-messages-received` 지표는 주제 구독을 지원하지 않으므로 내보내지지 않습니다. 자세한 내용은 [예약된 주제](reserved-topics.md) 단원을 참조하십시오.
메시지를 여러 구독자에게 배포하기 위해(예: 메시지를 다른 디바이스와 규칙 엔진으로 전달하기 위해) 게시/구독 브로커가 필요한 경우 계속해서 AWS IoT 메시지 브로커를 사용해 메시지 배포를 처리해야 합니다. 그러나 기본 수집 주제 이외의 주제에 대해 메시지를 게시해야 합니다.
## Basic Ingest 사용
기본 수집을 사용하기 전에 디바이스 또는 애플리케이션이 `$aws/rules/*`에 대한 게시 권한이 있는 [정책](iot-policies.md)을 사용하는지 확인하세요. 또는 정책에서 `$aws/rules/rule_name/*`을(를) 사용해 개별 규칙에 대한 권한을 지정할 수 있습니다. 그렇지 않은 경우 디바이스 및 애플리케이션은 계속해서 AWS IoT Core와의 기존 연결을 사용할 수 있습니다.
메시지가 규칙 엔진에 도달하면 기본 수집에서 호출된 규칙과 메시지 브로커 구독을 통해 호출된 규칙 간에 구현 또는 오류 처리에 아무런 차이가 없습니다.
Basic Ingest와 함께 사용할 규칙을 생성할 수 있습니다. 다음 사항에 유의하세요.
+ Basic Ingest 주제(`$aws/rules/rule_name`)의 최초 접두사는 [topic(Decimal)](iot-sql-functions.md#iot-function-topic) 함수에 사용할 수 없습니다.
+ 기본 수집으로만 호출되는 규칙을 정의하는 경우 `FROM` 절은 `rule` 정의의 `sql` 필드에서 선택적입니다. 이는 (예를 들어, 다른 메시지를 여러 구독자에게 배포해야 하기 때문에) 메시지 브로커를 통해 전송해야 하는 다른 메시지로도 해당 규칙이 호출될 경우에도 필요합니다. 자세한 내용은 [AWS IoT SQL 참조](iot-sql-reference.md) 단원을 참조하십시오.
+ Basic Ingest 주제(`$aws/rules/rule_name`)의 처음 3개 수준은 주제에 대한 8개 세그먼트 길이 제한 또는 256자의 총 문자 제한에 포함되지 않습니다. 그렇지 않으면 [AWS IoT 제한](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot)의 설명과 동일한 제한이 적용됩니다.
+ 비활성 규칙 또는 존재하지 않는 규칙을 지정하는 Basic Ingest 주제가 포함된 메시지가 수신되면 디버깅할 수 있도록 Amazon CloudWatch 로그에 오류 로그가 생성됩니다. 자세한 내용은 [Rules engine 로그 항목](cwl-format.md#rule-engine-logs) 단원을 참조하세요. `RuleNotFound` 측정치가 표시되어 이 측정치에 대한 경보를 생성할 수 있습니다. 자세한 내용은 [규칙 지표](metrics_dimensions.md#rulemetrics)의 규칙 지표를 참조하세요.
+ QoS 1을 사용해 Basic Ingest 주제에 대해 게시할 수 있습니다. 메시지가 규칙 엔진으로 성공적으로 전달되면 PUBACK이 수신됩니다. PUBACK을 수신했다고 해서 규칙 작업이 성공적으로 완료된 것은 아닙니다. 작업이 실행될 때 오류를 처리하도록 오류 작업을 구성할 수 있습니다. 자세한 내용은 [오류 처리(오류 작업)](rule-error-handling.md) 단원을 참조하십시오.
# 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]
```