IoT Hub 메시지 만들기 및 읽기
프로토콜 간 상호 운용성을 지원하기 위해 IoT Hub는 모든 디바이스 연결 프로토콜에서 사용할 수 있는 일반적인 메시징 기능 집합을 정의합니다. 이러한 기능은 디바이스-클라우드 메시지와 클라우드-디바이스 메시지 모두에서 사용할 수 있습니다.
참고 항목
클라우드-디바이스 메시지, 디바이스 트윈스, 디바이스 관리 등 이 문서에 언급된 일부 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.
IoT Hub는 스트리밍 메시징 패턴을 사용하여 디바이스-클라우드 메시징을 구현합니다. IoT Hub의 디바이스-클라우드 메시지는 여러 판독기에서 읽을 수 있는 서비스를 통과하는 많은 양의 이벤트가 있다는 측면에서 Service Bus 메시지보다 Event Hubs 이벤트와 비슷합니다.
IoT Hub 메시지는 다음으로 구성됩니다.
이 문서의 뒷부분에 설명된 대로 미리 정해진 시스템 속성 집합입니다.
애플리케이션 속성집합. 메시지 본문을 역직렬화할 필요 없이 애플리케이션이 정의하고 액세스할 수 있는 문자열 속성 사전입니다. IoT Hub는 절대로 이러한 속성을 수정하지 않습니다.
모든 형식의 데이터일 수 있는 메시지 본문입니다.
각 디바이스 프로토콜은 다양한 방법으로 설정 속성을 구현합니다. 자세한 내용은 MQTT 프로토콜 가이드 및 AMQP 프로토콜 가이드 개발자 가이드를 참조하세요.
HTTPS 프로토콜을 사용하여 디바이스-클라우드 메시지를 보내거나 클라우드-디바이스 메시지를 보내는 경우 속성 이름 및 값에는 ASCII 영숫자 문자 ! # $ % & ' * + - . ^ _ ` | ~ 만 포함될 수 있습니다.
IoT Hub를 사용한 디바이스-클라우드 메시징의 특징은 다음과 같습니다.
디바이스-클라우드 메시지는 영구적이며 IoT Hub의 기본 messages/events 엔드포인트에 최대 7일 동안 보관됩니다.
디바이스-클라우드 메시지는 최대 256KB까지 가능하며 보내기를 최적화하기 위해 일괄 처리로 그룹화할 수 있습니다. Batch는 최대 256KB가 될 수 있습니다.
IoT Hub는 임의의 분할을 허용하지 않습니다. 디바이스-클라우드 메시지는 원래 deviceId와 관련하여 분할됩니다.
IoT Hub에 대한 액세스 제어에서 설명한 것처럼, IoT Hub는 디바이스 단위 인증 및 액세스 제어를 허용합니다.
애플리케이션 속성에 제공되는 정보를 사용하여 메시지를 스탬프할 수 있습니다. 자세한 내용은 메시지 보강을 참조하세요.
참고 항목
각 IoT Hub 프로토콜은 데이터를 사용자 지정 엔드포인트로 라우팅할 때 적용되는 메시지 콘텐츠 형식 속성을 제공합니다. 데이터가 대상에서 올바르게 처리되도록 하려면(예: JSON이 Base64로 인코딩된 이진 데이터 대신 구문 분석 가능한 문자열로 처리됨) 메시지에 적절한 콘텐츠 형식과 문자 집합을 제공합니다.
IoT Hub 라우팅 쿼리에서 메시지 본문을 사용하려면 메시지에 유효한 JSON 개체를 제공하고 메시지의 콘텐츠 형식 속성을 application/json;charset=utf-8로 설정합니다.
다음 예제에서는 유효한 라우팅 가능한 메시지 본문을 보여 줍니다.
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
디바이스-클라우드 메시지의 시스템 속성
| 속성 | 설명 | 사용자 설정 가능? | 라우팅 쿼리 키워드 |
|---|---|---|---|
| message-id | 사용자가 설정할 수 있는 메시지에 대한 식별자는 요청-회신 패턴에 사용됩니다. 형식: ASCII 7비트 영숫자 문자와 - : . + % _ # * ? ! ( ) , = @ ; $ '함께 대/소문자를 구분하는 문자열(최대 128자 길이)입니다. |
예 | messageId |
| iothub-enqueuedtime | IoT Hub에서 디바이스-클라우드 메시지를 수신한 날짜 및 시간입니다. | 예 | enqueuedTime |
| user-id | 메시지의 원본을 지정하는 데 사용되는 ID입니다. | 예 | userId |
| iothub-connection-device-id | IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 deviceId를 포함합니다. | 예 | connectionDeviceId |
| iothub-connection-module-id | IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 moduleId를 포함합니다. | 예 | connectionModuleId |
| iothub-connection-auth-generation-id | IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 connectionDeviceGenerationId(디바이스 ID 속성당)를 포함합니다. | 예 | connectionDeviceGenerationId |
| iothub-connection-auth-method | IoT Hub에서 디바이스-클라우드 메시지에 설정하는 인증 방법입니다. 이 속성에는 메시지를 보내는 디바이스를 인증하는 데 사용되는 인증 방법에 대한 정보가 포함됩니다. | 예 | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | 일괄 처리로 데이터를 보내는 경우 디바이스에서 이벤트 생성 시간을 보낼 수 있습니다. | 예 | creation-time-utc |
| iothub-creation-time-utc | 한 번에 하나의 메시지를 보내는 경우 디바이스에서 이벤트 생성 시간을 보낼 수 있습니다. | 예 | creation-time-utc |
| dt-dataschema | 이 값은 디바이스-클라우드 메시지의 IoT 허브에 의해 설정됩니다. 디바이스 연결에 설정된 디바이스 모델 ID 세트를 포함합니다. | 예 | $dt-dataschema |
| dt-subject | 디바이스-클라우드 메시지를 전송하는 구성 요소의 이름입니다. | 예 | $dt-subject |
디바이스-클라우드 메시지의 애플리케이션 속성
애플리케이션 속성의 일반적인 용도는 iothub-creation-time-utc 속성을 사용하여 디바이스에서 메시지를 보낸 시간을 기록하는 타임스탬프를 디바이스에서 보내는 것입니다. 이 타임스탬프의 형식은 표준 시간대 정보가 없는 UTC여야 합니다. 예를 들어 2021-04-21T11:30:16Z는 유효하지만 2021-04-21T11:30:16-07:00는 유효하지 않습니다.
{
"applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
클라우드-디바이스 메시지의 시스템 속성
| 속성 | 설명 | 사용자 설정 가능 여부 |
|---|---|---|
| message-id | 사용자가 설정할 수 있는 메시지에 대한 식별자는 요청-회신 패턴에 사용됩니다. 형식: ASCII 7비트 영숫자 문자와 - : . + % _ # * ? ! ( ) , = @ ; $ '함께 대/소문자를 구분하는 문자열(최대 128자 길이)입니다. |
예 |
| sequence-number | 숫자(디바이스 큐 별로 고유함)는 IoT Hub에서 각 클라우드-디바이스 메시지에 할당됩니다. | 예 |
| to | 클라우드-디바이스 메시지에 지정된 대상입니다. | 예 |
| absolute-expiry-time | 메시지 만료 날짜 및 시간입니다. | 예 |
| correlation-id | 일반적으로 요청-응답 패턴으로 요청의 MessageId가 포함된 응답 메시지의 String 속성입니다. | 예 |
| user-id | 메시지의 원본을 지정하는 데 사용되는 ID입니다. IoT Hub에서 메시지를 생성할 때 사용자 ID는 IoT Hub 이름입니다. | 예 |
| iothub-ack | 피드백 메시지 생성기입니다. 이 속성은 디바이스에서 소비하는 메시지의 결과로 피드백 메시지를 생성하는 IoT Hub를 요청하기 위해 클라우드-디바이스 메시지에서 사용됩니다. 가능한 값: none(기본값): 피드백 메시지가 생성되지 않습니다. positive: 메시지가 완료된 경우 피드백 메시지를 받습니다. negative: 디바이스에서 완료되지 않고 메시지가 만료(또는 최대 전달 횟수에 도달)되면 피드백 메시지를 받습니다. full: positive 및 negative 모두입니다. | 예 |
시스템 속성 이름
시스템 속성 이름은 메시지가 라우팅되는 엔드포인트에 따라 다릅니다.
| 시스템 속성 이름 | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| 메시지 ID | message-id | messageId | MessageId | message-id |
| User id | user-id | userId | 사용자 ID | user-id |
| Connection device id | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Connection module id | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Connection auth generation id | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Connection auth method | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | 해당 없음 | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
메시지 크기
IoT Hub는 실제 페이로드만을 고려하여 프로토콜 진단 방식으로 메시지 크기를 측정합니다. 크기(바이트 단위)는 다음 값의 합계로 계산됩니다.
- 본문 크기(바이트)입니다.
- 모든 메시지 시스템 속성 값의 크기(바이트)입니다.
- 모든 사용자 속성 이름 및 값의 크기(바이트 단위)
속성 이름과 값은 ASCII 문자로 제한되므로 문자열의 길이는 바이트 단위의 크기와 같습니다.
스푸핑 방지 속성
디바이스-클라우드 메시지에서 스푸핑된 디바이스를 피하려면 IoT Hub는 다음 속성을 사용하여 모든 메시지를 보여줍니다.
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
처음 두 가지는 디바이스 ID 속성에 따라 원래 디바이스의 deviceId 및 generationId를 포함합니다.
iothub-connection-auth-method 속성은 다음 속성을 가진 JSON으로 직렬화된 개체를 포함합니다.
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
다음 단계
- IoT Hub의 메시지 크기 제한에 대한 자세한 내용은 IoT Hub 할당량 및 제한을 참조하세요.
- 다양한 프로그래밍 언어로 IoT Hub 메시지를 만들고 읽는 방법을 알아보려면 빠른 시작을 참조하세요.
- IoT Hub에서 생성된 비원격 분석 이벤트의 구조에 대해 알아보려면 IoT Hub 비원격 분석 이벤트 스키마를 참조하세요.