다음을 통해 공유

IoT Hub 데이터 평면 MQTT 5 API 참조(사용되지 않음)

  • 아티클

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

참고 항목

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

작업

트윈 가져오기

트윈 상태 가져오기

요청

토픽 이름: $iothub/twin/get

속성: 없음

페이로드: 비어 있음

성공 응답

속성: 없음

페이로드: 트윈

대체 응답

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

의사 코드 샘플


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

패치 트윈이 보고됨

패치 트윈 보고됨 상태

요청

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

Properties:

속성 Type 필수 설명
if-version u64 아니요

페이로드: TwinState

성공 응답

Properties:

속성 Type 필수 설명
version u64 예 패치가 적용된 후 보고된 상태의 버전

페이로드: 비어 있음

대체 응답

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

의사 코드 샘플


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

수신 명령

명령 수신 및 처리

메시지

토픽 이름: $iothub/commands

Properties:

속성 Type 필수 설명
sequence-no u64 예 메시지의 시퀀스 번호
enqueued-time 시간 예 메시지가 시스템에 들어온 시점의 타임스탬프
delivery-count u32 예 메시지 배달을 시도한 횟수
creation-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

직접 메서드 받기

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

요청

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

속성: 없음

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

성공 응답

Properties:

속성 Type 필수 설명
response-code u32 예

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

대체 응답

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

의사 코드 샘플


-> 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:

속성 Type 필수 설명
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:

속성 Type 필수 설명
콘텐츠 유형 string 아니요 게시된 메시지에서 content-type 시스템 속성으로 변환
content-encoding string 아니요 게시된 메시지에서 content-encoding 시스템 속성으로 변환
message-id string 아니요 게시된 메시지에서 message-id 시스템 속성으로 변환
user-id string 아니요 게시된 메시지에서 user-id 시스템 속성으로 변환
correlation-id string 아니요 게시된 메시지에서 correlation-id 시스템 속성으로 변환
creation-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 정체됨 요청 속도가 SKU당 너무 높음
151 0502 할당량이 초과됨 현재 SKU당 일일 할당량을 초과함
131 0602 시간 제한 작업이 완료되기 전에 시간 초과됨
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:

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

페이로드: 비어 있음

충돌

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

이유 코드: 131

상태: 0103

Properties:

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

페이로드: 비어 있음

허용 안함

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

이유 코드: 131

상태: 0102

Properties:

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

페이로드: 비어 있음

권한 없음

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

이유 코드: 135

상태: 0101

Properties:

속성 Type 필수 설명
추적 ID string 아니요 오류에 대한 다른 진단과의 상관 관계에 대한 추적 ID

페이로드: 비어 있음

Not Found

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

이유 코드: 131

상태: 0504

Properties:

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

페이로드: 비어 있음

Not Modified

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

이유 코드: 0

상태: 0001

속성: 없음

페이로드: 비어 있음

Precondition Failed

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

이유 코드: 131

상태: 0104

속성: 없음

페이로드: 비어 있음

할당량이 초과됨

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

이유 코드: 151

상태: 0502

속성: 없음

페이로드: 비어 있음

리소스가 소진됨

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

이유 코드: 131

상태: 0503

Properties:

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

페이로드: 비어 있음

서버 작업 중

서버 사용 중

이유 코드: 131

상태: 0603

Properties:

속성 Type 필수 설명
추적 ID string 아니요 오류에 대한 다른 진단과의 상관 관계에 대한 추적 ID

페이로드: 비어 있음

서버 오류

내부 서버 오류

이유 코드: 131

상태: 0601

Properties:

속성 Type 필수 설명
추적 ID string 아니요 오류에 대한 다른 진단과의 상관 관계에 대한 추적 ID

페이로드: 비어 있음

대상 실패

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

이유 코드: 131

상태: 06A2

Properties:

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

페이로드: 비어 있음

대상 시간 제한

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

이유 코드: 131

상태: 06A1

Properties:

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

페이로드: 비어 있음

대상을 사용할 수 없음

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

이유 코드: 131

상태: 06A0

속성: 없음

페이로드: 비어 있음

정체됨

요청 속도가 SKU당 너무 높음

이유 코드: 151

상태: 0501

속성: 없음

페이로드: 비어 있음

시간 제한

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

이유 코드: 131

상태: 0602

Properties:

속성 Type 필수 설명
추적 ID string 아니요 오류에 대한 다른 진단과의 상관 관계에 대한 추적 ID

페이로드: 비어 있음