IoT Hub 데이터 평면 MQTT 5 API 참조(미리 보기)

이 문서에서는 IoT Hub 데이터 평면 API 버전 2.0(api-version: 2020-10-01-preview)에서 사용할 수 있는 작업을 정의합니다.

참고 항목

IoT Hub는 MQTT에 대한 제한된 기능 지원을 제공합니다. 솔루션에 MQTT v3.1.1 또는 v5 지원이 필요한 경우 Azure Event Grid에서 MQTT 지원을 권장합니다. 자세한 내용은 IoT Hub 및 Event Grid에서 MQTT 지원 비교를 참조 하세요.

작업

트윈 가져오기

트윈 상태 가져오기

Request

토픽 이름:$iothub/twin/get

속성: 없음

페이로드: 비어 있음

성공 응답

속성: 없음

페이로드: 트윈

대체 응답

상태	이름	설명
0100	Bad Request	작업 메시지가 잘못되어 처리할 수 없습니다.
0101	권한 없음	클라이언트는 작업을 수행할 권한이 없습니다.
0102	허용 안함	작업이 허용되지 않습니다.
0501	Throttled	요청 속도가 SKU당 너무 높음
0502	할당량 초과	현재 SKU당 일일 할당량을 초과함
0601	서버 오류	내부 서버 오류
0602	Timeout	작업이 완료되기 전에 시간 초과됨
0603	서버 작업 중	서버 사용 중

의사 코드 샘플

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

패치 트윈이 보고됨

패치 트윈 보고됨 상태

Request

토픽 이름:$iothub/twin/patch/reported

Properties:

이름	종류	필수	설명
if-version	u64	아니요

페이로드: TwinState

성공 응답

Properties:

이름	종류	필수	설명
version	u64	예	패치가 적용된 후 보고된 상태의 버전

페이로드: 비어 있음

대체 응답

상태	이름	설명
0104	Precondition Failed	사전 조건이 충족되지 않아 요청이 취소됨
0100	Bad Request	작업 메시지가 잘못되어 처리할 수 없습니다.
0101	권한 없음	클라이언트는 작업을 수행할 권한이 없습니다.
0102	허용 안함	작업이 허용되지 않습니다.
0501	Throttled	요청 속도가 SKU당 너무 높음
0502	할당량 초과	현재 SKU당 일일 할당량을 초과함
0601	서버 오류	내부 서버 오류
0602	Timeout	작업이 완료되기 전에 시간 초과됨
0603	서버 작업 중	서버 사용 중

의사 코드 샘플

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

수신 명령

명령 수신 및 처리

메시지

토픽 이름:$iothub/commands

Properties:

이름	종류	필수	설명
sequence-no	u64	예	메시지의 시퀀스 번호
enqueued-time	time	예	메시지가 시스템에 들어온 시점의 타임스탬프
배달 수	u32	예	메시지 배달을 시도한 횟수
생성 시간	time	아니요	메시지를 만든 시간의 타임스탬프(보낸 사람이 제공)
message-id	string	아니요	메시지 ID(보낸 사람 제공)
user-id	string	아니요	사용자 ID(보낸 사람 제공)
correlation-id	string	아니요	상관 관계 ID(보낸 사람 제공)
콘텐츠 유형	string	아니요	는 페이로드의 콘텐츠 형식을 결정합니다.
content-encoding	string	아니요	는 페이로드의 콘텐츠 인코딩을 결정합니다.

페이로드: 임의의 바이트 시퀀스

성공 승인

클라이언트에서 처리할 수 있는 명령이 허용되었음을 나타냅니다.

속성: 없음

페이로드: 비어 있음

대체 승인

이유 코드	상태	이름	설명
131	0603	중단	현재 명령이 처리되지 않으며 나중에 다시 배달되어야 했음을 나타냅니다.
131	0100	거부	클라이언트가 명령을 거부했으며 다시 시도해서는 안 됨을 나타냅니다.

의사 코드 샘플

-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

직접 메서드 받기

직접 메서드 호출 수신 및 처리

Request

토픽 이름:$iothub/methods/{name}

속성: 없음

페이로드: 임의의 바이트 시퀀스

성공 응답

Properties:

이름	종류	필수	설명
response-code	u32	예

페이로드: 임의의 바이트 시퀀스

대체 응답

상태	이름	설명
06A0	사용할 수 없음	이 연결을 통해 클라이언트에 연결할 수 없음을 나타냅니다.

의사 코드 샘플

-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

트윈 원하는 상태 변경 받기

트윈의 원하는 상태에 대한 업데이트 받기

메시지

토픽 이름:$iothub/twin/patch/desired

Properties:

이름	종류	필수	설명
version	u64	예	이 업데이트와 일치하는 원하는 상태의 버전

페이로드: TwinState

의사 코드 샘플

-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

원격 분석 전송

원격 분석 채널에 메시지 게시 - 기본적으로 Event Hubs 또는 라우팅 구성을 통해 다른 엔드포인트.

메시지

토픽 이름:$iothub/telemetry

Properties:

이름	종류	필수	설명
콘텐츠 유형	string	아니요	게시된 메시지에서 content-type 시스템 속성으로 변환
content-encoding	string	아니요	게시된 메시지에서 content-encoding 시스템 속성으로 변환
message-id	string	아니요	게시된 메시지에서 message-id 시스템 속성으로 변환
user-id	string	아니요	게시된 메시지에서 user-id 시스템 속성으로 변환
correlation-id	string	아니요	게시된 메시지에서 correlation-id 시스템 속성으로 변환
생성 시간	time	아니요	게시된 메시지에서 iothub-creation-time-utc 속성으로 변환

팁

형식 creation-time 은 표준 시간대 정보가 없는 UTC여야 합니다. 예를 들어 2021-04-21T11:30:16Z는 유효하고 2021-04-21T11:30:16-07:00은 잘못된 것입니다.

페이로드: 임의의 바이트 시퀀스

성공 승인

메시지가 원격 분석 채널에 성공적으로 게시되었습니다.

속성: 없음

페이로드: 비어 있음

대체 승인

이유 코드	상태	이름	설명
131	0100	Bad Request	작업 메시지가 잘못되어 처리할 수 없습니다.
135	0101	권한 없음	클라이언트는 작업을 수행할 권한이 없습니다.
131	0102	허용 안함	작업이 허용되지 않습니다.
131	0601	서버 오류	내부 서버 오류
151	0501	Throttled	요청 속도가 SKU당 너무 높음
151	0502	할당량 초과	현재 SKU당 일일 할당량을 초과함
131	0602	Timeout	작업이 완료되기 전에 시간 초과됨
131	0603	서버 작업 중	서버 사용 중

의사 코드 샘플

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

응답

Bad Request

작업 메시지가 잘못되어 처리할 수 없습니다.

이유 코드:131

상태:0100

Properties:

이름	종류	필수	설명
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

충돌

작업이 진행 중인 다른 작업과 충돌합니다.

이유 코드:131

상태:0103

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

허용 안함

작업이 허용되지 않습니다.

이유 코드:131

상태:0102

Properties:

이름	종류	필수	설명
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

권한 없음

클라이언트는 작업을 수행할 권한이 없습니다.

이유 코드:135

상태:0101

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID

페이로드: 비어 있음

Not Found

요청된 리소스가 없습니다.

이유 코드:131

상태:0504

Properties:

이름	종류	필수	설명
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

Not Modified

제공된 사전 조건에 따라 리소스가 수정되지 않았습니다.

이유 코드:0

상태:0001

속성: 없음

페이로드: 비어 있음

Precondition Failed

사전 조건이 충족되지 않아 요청이 취소됨

이유 코드:131

상태:0104

속성: 없음

페이로드: 비어 있음

할당량 초과

현재 SKU당 일일 할당량을 초과함

이유 코드:151

상태:0502

속성: 없음

페이로드: 비어 있음

리소스가 소진됨

리소스에 작업을 완료할 수 있는 용량이 없음

이유 코드:131

상태:0503

Properties:

이름	종류	필수	설명
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

서버 작업 중

서버 사용 중

이유 코드:131

상태:0603

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID

페이로드: 비어 있음

서버 오류

내부 서버 오류

이유 코드:131

상태:0601

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID

페이로드: 비어 있음

대상 실패

대상이 응답했지만 응답이 잘못되었거나 잘못된 형식임

이유 코드:131

상태:06A2

Properties:

이름	종류	필수	설명
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

대상 시간 제한

대상이 요청을 완료할 때까지 기다리는 동안 시간 초과됨

이유 코드:131

상태:06A1

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID
reason	string	아니요	에는 메시지에 대해 특별히 유효하지 않은 항목에 대한 정보가 포함되어 있습니다.

페이로드: 비어 있음

대상을 사용할 수 없음

대상에 연결할 수 없도록 하여 요청을 완료합니다.

이유 코드:131

상태:06A0

속성: 없음

페이로드: 비어 있음

Throttled

요청 속도가 SKU당 너무 높음

이유 코드:151

상태:0501

속성: 없음

페이로드: 비어 있음

Timeout

작업이 완료되기 전에 시간 초과됨

이유 코드:131

상태:0602

Properties:

이름	종류	필수	설명
trace-id	string	아니요	오류에 대한 다른 진단 상관 관계에 대한 추적 ID

페이로드: 비어 있음