MQTT Reason Code の紹介と参考資料

Reason Code

MQTTの Reason Code の主な目的は、より詳細なフィードバックをクライアントとサーバーに提供することです。たとえば、間違ったユーザー名またはパスワードに対応する Reason Code を CONNACK パケットでクライアントにフィードバックすると、クライアントは接続できない理由を知ることができます。

MQTT 3.1.1 の Reason Code

MQTT 3.1.1 はすでに Reason Code をサポートしていますが、利用可能な Reason Code の多くは定義されていません。実際、それらは非常に限られています。

Reason Code をサポートする2 つのMQTT パケットのうち、CONNACK パケットには失敗を示す Reason Code が 5 つだけあります。また、SUBACK パケットには失敗を示す Reason Code が 1 つだけあり、サブスクリプション失敗の理由についての詳細を提供することさえできません。さらに、 Reason Code をサポートしていない公開や購読解除などの操作の場合、操作が成功したかどうかさえ判断できません。これにより、開発デバッグが不親切になり、堅牢なコードの実装が妨げられます。

MQTT 5.0 の Reason Code

そのため、MQTT 5.0 では、使用可能な Reason Code の数が 43 に拡張され、0x80 未満の Reason Code は成功を示すために使用され、0x80 以上の Reason Code は失敗を示すために使用されることが指定されています。MQTT 3.1.1 とは異なり、0x80 未満の Reason Code も失敗を示す可能性があります。これにより、クライアントは操作が成功したかどうかを迅速に判断できるようになります。

さらに、MQTT 5.0 では、 Reason Code のサポートが、CONNACK、PUBACK、PUBREC、PUBREL、PUBCOMP、SUBACK、UNSUBACK、DISCONNECT、および AUTH のパケットに拡張されています。現在では、メッセージのパブリッシュが成功したかどうかを判断できるだけでなく、一致するサブスクライバーが存在しない、特定のトピックにパブリッシュするための権限が不十分であるなど、失敗の理由も理解できるようになりました。

SUBACK と UNSUBACK を除き、ほとんどの MQTT パケットには Reason Code が 1 つだけ含まれます。これは、SUBSCRIBE パケットと UNSUBSCRIBE パケットには複数のトピック フィルターを含めることができ、各トピック フィルターには操作の結果を示す対応する Reason Code が必要であるためです。したがって、SUBACK および UNSUBACK パケットは複数の Reason Code に対応する必要があります。そのため、他のパケットの Reason Code は変数ヘッダーに配置され、SUBACK および UNSUBACK の Reason Code はペイロードに配置されます。

この記事の最後の Reason Code クイック リファレンス テーブルでは、MQTT 5.0 の各 Reason Code の詳細な説明と使用例を提供しました。詳細については、こちらをご覧ください。

接続が切断された理由をクライアントに示します

MQTT 3.1 および 3.1.1 では、DISCONNECT パケットはクライアントによってのみ送信できました。したがって、クライアントが特定の制限に違反した場合、サーバーは追加情報をクライアントに提供せずにネットワーク接続を直接閉じることしかできませんでした。このため、切断の原因を調査することが困難になりました。

MQTT 5.0 では、サーバーはネットワーク接続を閉じる前に DISCONNECT パケットをクライアントに送信できるようになりました。クライアントは、DISCONNECT パケット内の Reason Code を使用して、パケットが大きすぎる、サーバーがビジーであるなど、接続が切断された理由を取得できます。

Reason String

Reason String は MQTT 5.0 の Reason Code を補完するもので、診断目的で設計された人間が判読できる文字列を提供します。 Reason Code はほとんどのエラー理由を示すことができますが、開発者やオペレーターはさらに直感的なコンテキスト情報を必要とする場合があります。

たとえば、サーバーが Reason Code (0x8F) を使用してクライアントに無効なトピック フィルターを示した場合、開発者はその理由に関する具体的な情報をまだ持っていません。トピックレベルの最大数を超えているか、サーバーで受け入れられない文字が含まれていることが原因ですか? ただし、サーバーが「トピック レベルの数が制限を超えています。最大は 10 です」のような Reason Stringを返すことができれば、開発者は理由をすぐに理解し、調整することができます。

実際の使用では、Reason String の内容はクライアントとサーバーの特定の実装によって異なります。したがって、正しく実装された受信側は、Reason String の内容を解析しようとするべきではありません。推奨される使用法には、例外をスローするときやログに書き込むときに Reason Stringを使用することが含まれますが、これに限定されません。

最後に、Reason String はオプションの機能であり、Reason String が受信されるかどうかは、ピアがそれをサポートしているかどうかによって決まります。

MQTT 5.0 Reason Code の参考テーブル