기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

InfluxDB

디바이스 원격 측정에서 운영 추세를 쿼리하거나 시계열 데이터를 실시간으로 모니터링하려면이 작업을 선택합니다. 클라이언트 측 또는 서버 측 일괄 처리를 사용하여 하나의 쓰기 요청에서 여러 지점을 결합할 수 있습니다.는 각 메시지를 InfluxDB 라인 프로토콜로 AWS IoT Core 변환하고 지정된 데이터베이스 및 테이블에 씁니다. 형식에 대한 자세한 내용은 InfluxData 설명서의 InfluxDB 라인 프로토콜을 참조하세요. InfluxData 관리형 클러스터에 대한 자세한 내용은 Amazon Timestream for InfluxDB를 참조하세요.

사전 조건

이 규칙 작업에는 다음과 같은 사전 조건이 있습니다.

InfluxDB 작업 대상

InfluxDB 규칙 작업을 사용하려면 먼저 InfluxDB 작업 대상을 생성해야 합니다. 대상은 InfluxDB 인스턴스의 연결 파라미터를 정의 AWS IoT Core 한 다음 엔드포인트 소유권을 검증합니다.

대상 생성

CreateTopicRuleDestination API를 사용하여 InfluxDB 대상을 생성합니다.

{
  "destinationConfiguration": {
    "influxDBConfiguration": {
      "endpoint": "https://my-instance.timestream-influxdb.us-west-2.amazonaws.com:8086",
      "influxDBVersion": "V2",
      "secretId": "arn:aws:secretsmanager:us-west-2:111122223333:secret:my-influxdb-credentials-AbCdEf"
    }
  }
}

대상 파라미터

엔드포인트 소유권 검증

InfluxDB 작업 대상을 생성할 때는 제공한 자격 증명을 사용하여 InfluxDB API에 대해 인증하여 엔드포인트 소유권을 AWS IoT Core 검증합니다.

응답 성공(2xx)은 대상 상태를 로 설정합니다ENABLED. 실패 시 상태를 로 AWS IoT Core 설정합니다ERROR. 검증을 다시 시도하려면 상태가 UpdateTopicRuleDestination로 설정된 상태에서를 호출합니다IN_PROGRESS.

InfluxDB 용어 매핑

다음 용어는 InfluxDB V2와 V3 간에 다릅니다.

파라미터

InfluxDB 작업을 사용하여 AWS IoT 규칙을 생성할 때 다음 정보를 지정해야 합니다.

배칭

InfluxDB 작업은 두 가지 일괄 처리 모드를 지원합니다.

클라이언트 측 일괄 처리

IoT 디바이스는 시계열 데이터를 JSON 배열로 일괄 처리하여 단일 MQTT 메시지로 게시합니다. 클라이언트 측 일괄 처리를 사용하면 각 배열 요소가 단일 쓰기 요청에서 하나의 라인 프로토콜 포인트가 됩니다. 추가 구성은 필요하지 않습니다.

서버 측 일괄 처리

InfluxDB에 메시지를 쓰기 전에 서버 측 일괄 처리를 사용하여 개별 메시지를 그룹화합니다. batchConfig 파라미터를 사용하여 서버 측 일괄 처리를 구성합니다. 구성된 제한(maxBatchSize, maxBatchOpenMs또는 maxBatchSizeBytes)에 먼저 도달하면 배치가 플러시됩니다.

InfluxDB 작업은 아웃바운드 페이로드 크기를 기준으로 5KiB 단위로 측정됩니다. 라인 프로토콜 변환 실패도 측정됩니다.

배열 페이로드를 위한 요소별 템플릿

IoT 디바이스가 배치화된 시계열 데이터를 JSON 배열로 전송할 때 “요소별 대체 템플릿”을 사용하여 각 개별 배열 요소의 값을 확인할 수 있습니다. 이렇게 하면 각 데이터 포인트가 다른 테이블로 라우팅되거나 요소별 태그가 적용됩니다. 자세한 내용은 요소별 템플릿을 참조하세요.

두 대체 템플릿의 구문

tableName 및 태그 값@{...}에서를 사용하여 각 배열 요소에 대한 표현식을 개별적으로 확인합니다.

예제

다음 디바이스 페이로드(JSON 배열)가 주어짐:

[
  {"measurement_type": "temperature", "room": "kitchen", "timestamp": 1700000000000, "value": 23.5},
  {"measurement_type": "humidity", "room": "bedroom", "timestamp": 1700000001000, "value": 60.1}
]

그리고 다음 작업 구성:

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/abc123",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "room": "@{room}"
    },
    "timestampUnit": "ms"
  }
}

결과 라인 프로토콜 출력에는 다음 두 점이 포함됩니다.

temperature,room=kitchen value=23.5 1700000000000
humidity,room=bedroom value=60.1 1700000001000

제한 사항

InfluxDB 레코드 콘텐츠

SQL 후 쿼리 결과의 각 레코드에 대해 결과 InfluxDB 라인 프로토콜 포인트에는 다음 구성 요소가 포함됩니다.

데이터 유형 변환

AWS IoT Core 는 다음과 같이 JSON 값을 InfluxDB 라인 프로토콜 유형으로 변환합니다.

이름 지정 제한

예약 키

라인 프로토콜 변환 중에 필드 세트에서 다음 페이로드 키가 제거됩니다.

오류 작업

InfluxDB 작업이 실패하면 구성된 오류 작업이 트리거됩니다.

InfluxDB를 오류 작업으로 사용

InfluxDB 작업을 모든 규칙에 대한 오류 작업으로 구성할 수 있습니다. 전체 페이로드는 하나의 레코드tableName로 단일에 기록됩니다. 메시지 범위 대체 템플릿(${...})은 오류 작업의 tableName 및에서 지원됩니다tags.

오류 작업 출력

오류 작업이 트리거되면 출력 페이로드에는 ruleName, , cloudwatchTraceId, topicclientId, sourceIp, base64OriginalPayload (Base64 인코딩 원본 메시지) 및 각 항목에 failedAction, failedResource및가 있는 failures 배열이 포함됩니다errorMessage.

서버 측 일괄 처리를 사용하면 페이로드가 각 개별 인바운드 MQTT 메시지에 대해 하나의 항목payloadsWithMetadata과 함께를 사용합니다. 각 실패 값은 해당 메시지 항목의 id 값을 affectedIds 나타내며 포인트 인덱스가 아닙니다. 클라이언트 측 JSON 배열은 여러 InfluxDB 포인트를 생성하더라도 하나의 인바운드 메시지입니다. 전체 페이로드 형식은 섹션을 참조하세요일괄 처리를 위한 오류 작업.

재시도 가능한 오류(503)는 지수 백오프로 재시도됩니다. HTTP 401 응답의 경우는에서 토큰을 AWS IoT Core 다시 로드 AWS Secrets Manager 하고 요청을 한 번 재시도합니다. 재시도할 수 없는 오류(404, 422)는 오류 작업을 즉시 트리거합니다. 재시도 제한은 AWS IoT Core 서비스 할당량을 참조하세요.

예제

InfluxDB 규칙 작업

{
  "topicRulePayload": {
    "sql": "SELECT * FROM 'devices/+/telemetry'",
    "ruleDisabled": false,
    "awsIotSqlVersion": "2016-03-23",
    "actions": [
      {
        "influxDB": {
          "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/a1b2c3d4",
          "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
          "organization": "my-org",
          "databaseName": "sensor_data",
          "tableName": "device_metrics",
          "tags": {
            "device_id": "${clientid()}",
            "location": "building-a"
          },
          "timestampUnit": "ms"
        }
      }
    ]
  }
}

샘플 페이로드:

{
  "timestamp": 1700000000000,
  "temperature": 23.5,
  "humidity": 60.1,
  "pressure": 1013.25,
  "battery_level": 87
}

결과 행 프로토콜:

device_metrics,device_id=myDevice123,location=building-a temperature=23.5,humidity=60.1,pressure=1013.25,battery_level=87i 1700000000000

출력의 필드 순서는 다를 수 있습니다. 필드는 알파벳순으로 정렬되지 않습니다.

요소별 템플릿을 사용한 클라이언트 배치 배열 페이로드

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/a1b2c3d4",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "organization": "my-org",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "sensor_id": "@{sensor_id}",
      "location": "${topic(2)}"
    },
    "timestampUnit": "ns"
  }
}

샘플 페이로드(에 게시됨devices/floor3/telemetry):

[
  {"measurement_type": "temperature", "sensor_id": "sensor-42", "timestamp": 1700000000000000000, "value": 23.5},
  {"measurement_type": "humidity", "sensor_id": "sensor-42", "timestamp": 1700000001000000000, "value": 60.1},
  {"measurement_type": "pressure", "sensor_id": "sensor-43", "timestamp": 1700000002000000000, "value": 1013.25}
]

결과 행 프로토콜:

temperature,location=floor3,sensor_id=sensor-42 value=23.5 1700000000000000000
humidity,location=floor3,sensor_id=sensor-42 value=60.1 1700000001000000000
pressure,location=floor3,sensor_id=sensor-43 value=1013.25 1700000002000000000

InfluxDB를 사용한 서버 측 일괄 처리

InfluxDB 작업에 서버 측 일괄 처리를 추가하려면 작업 구성batchConfig에를 포함합니다.

"batchConfig": {
  "maxBatchSize": 50,
  "maxBatchOpenMs": 1000,
  "maxBatchSizeBytes": 65536,
  "batchAcrossTopics": false
}

규칙 작업 역할에 대한 IAM 정책

신뢰 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"Service": "iot.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }
  ]
}

권한 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-west-2:111122223333:secret:my-influxdb-secret-a1b2c3"
    }
  ]
}

클라이언트 측 및 서버 측 일괄 처리 결합(포인트 재정렬)

클라이언트 측 일괄 처리(JSON 배열 페이로드)와 서버 측 일괄 처리()를 모두 활성화하면 서버 측 일괄 처리가 클라이언트 측 일괄 처리 페이로드에서 지점을 재정렬할 수 batchConfig있습니다. 규칙 엔진은 여러 수신 메시지의 포인트를 단일 서버 측 배치로 누적합니다. 메시지는 서로 다른 디바이스 또는 주제에서 비동기적으로 도착하기 때문에 원래 클라이언트 페이로드 내에서 정렬된 포인트는 최종 쓰기 시 다른 메시지의 포인트와 인터리브될 수 있습니다.

작업 구성:

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/abc123",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "device_id": "${topic(2)}",
      "floor": "@{floor}"
    },
    "timestampUnit": "ms",
    "batchConfig": {
      "maxBatchSize": 100,
      "maxBatchOpenMs": 500,
      "maxBatchSizeBytes": 65536,
      "batchAcrossTopics": true
    }
  }
}

디바이스 A는 시간 Tdevices/deviceA/telemetry에에 게시합니다.

[
  {"measurement_type": "temperature", "floor": "1", "timestamp": 1700000000000, "value": 22.1},
  {"measurement_type": "temperature", "floor": "2", "timestamp": 1700000000100, "value": 23.4},
  {"measurement_type": "humidity", "floor": "1", "timestamp": 1700000000200, "value": 55.0}
]

디바이스 B는 T+10ms devices/deviceB/telemetry 시점에에 게시합니다.

[
  {"measurement_type": "temperature", "floor": "3", "timestamp": 1700000000050, "value": 21.8},
  {"measurement_type": "humidity", "floor": "3", "timestamp": 1700000000150, "value": 62.3}
]

두 메시지 모두 500ms 배치 기간(maxBatchOpenMs) 내에 도착하므로 규칙 엔진은 5개 지점을 모두 단일 서버 측 배치로 결합합니다.

결과 라인 프로토콜(서버 측 배치 쓰기):

temperature,device_id=deviceB,floor=3 value=21.8 1700000000050
temperature,device_id=deviceA,floor=1 value=22.1 1700000000000
temperature,device_id=deviceA,floor=2 value=23.4 1700000000100
humidity,device_id=deviceB,floor=3 value=62.3 1700000000150
humidity,device_id=deviceA,floor=1 value=55.0 1700000000200

포인트는 더 이상 각 클라이언트 페이로드에 표시된 순서대로 표시되지 않습니다. 디바이스 A의 세 지점(타임스탬프 1700000000000, 1700000000100, 1700000000200)은 디바이스 B의 두 지점(타임스탬프 1700000000050, 1700000000150)과 인터리브됩니다. 서버 측 배치는 각 메시지 내에서 원래 순서를 보장하지 않습니다. InfluxDB는 타임스탬프 필드를 사용하여 타임라인에 각 점을 배치하므로 재정렬해도 쿼리 정확성에 영향을 주지 않습니다. 그러나 애플리케이션이 쓰기 순서 의미 체계를 사용하는 경우(예: 필드 유형 충돌 또는 동일한 밀리초 내의 last-write-wins스 중복 제거 처리) 효과적인 쓰기 순서는 게시 순서와 다를 수 있습니다.