ファイル転送クライアント開発

このページでは、クライアント視点からのファイル転送プロセスの概要と、EMQXへのファイルアップロード用コマンドの詳細情報を提供します。クライアント側のファイル転送機能開発の支援を目的としています。

ファイル転送プロセス

既存のMQTT接続を再利用しながら、クライアントは特定のプレフィックスを持つトピックにあらかじめ定められたメッセージをパブリッシュすることで、ファイル転送セッションを制御できます。

Listenerのマウントポイントとの非互換性

ファイル転送は、マウントポイントが設定されたリスナー経由で接続されたクライアントでは動作しません。EMQXは$file/および$file-async/コマンドプレフィックスのマッチング前にマウントポイントを適用するため、ファイル転送コマンドはマウントされたリテラルトピックへの通常メッセージとしてルーティングされます。$file-response/レスポンストピックへのサブスクライブもマウントされるため、クライアントはEMQXからのコマンド結果メッセージを受信できません。クライアントにはエラーは報告されません。

クライアント側のファイル転送プロセスは以下の通りです：

1. 転送準備：クライアントデバイスはアップロードするファイルを選択し、転送セッションを識別するための一意のfile_idを生成します。
2. ファイル転送の初期化：クライアントは$file/{file_id}/initトピックにinitコマンドをパブリッシュします。メッセージはJSON形式で、ファイル名、サイズ、チェックサムなどのファイルメタデータを含みます。
3. 分割ファイル転送：クライアントは連続して$file/{file_id}/{offset}[/{checksum}]トピックにメッセージをパブリッシュし、ファイルの各セグメントのデータブロックを転送します。メッセージ内容は現在のファイルセグメントのデータブロックで、オプションでデータブロックのチェックサムを含むchecksumフィールドがあります。
4. ファイル転送の完了：クライアントは$file/{file_id}/fin/{file_size}[/{checksum}]トピックにfinコマンドをパブリッシュし、ファイル転送の完了を示します。メッセージ内容は空で、file_sizeパラメータはファイルの合計サイズを示し、checksumフィールドはファイル全体のチェックサムです。

転送コマンドの各ステップの詳細な説明と注意事項については、以下のセクションを参照してください。

ファイル転送コマンド

ファイル転送コマンドは、特定のトピック形式とメッセージ内容を持つMQTTメッセージです：

• トピック：トピックプレフィックスには$file/と$file-async/があり、それぞれ同期転送と非同期転送に使用されます。クライアントは同一ファイル転送セッション内で異なるコマンドに対して混在して使用可能です。
  • 同期転送：クライアントはEMQXがコマンドの実行結果を確認するまで待機し、その後に次の操作を行います。
  • 非同期転送：クライアントはEMQXのコマンド実行確認を待つ必要がなく、コマンド送信後すぐに新たなコマンドを送信できるため、処理が高速化されます。
• QoS：すべてのコマンドはQoSレベル1でパブリッシュされ、信頼性を確保します。
• メッセージ本文：JSON形式またはデータブロックを含むメッセージ本文。

各コマンドパブリッシュ後、コマンド実行結果はPUBACKメッセージまたはレスポンストピックを通じて取得できます。詳細はコマンド実行結果の取得を参照してください。

TIP

1. すべてのファイル転送コマンドはEMQXブローカーで処理され、他のMQTTクライアントには送信されません。
2. 非同期転送モードはEMQX v5.3.2以降で利用可能です。
3. MQTT v3.1/v3.1.1クライアントはPUBACK Reason Codeが利用できないため、非同期転送モードの使用を推奨します。

init コマンド

initコマンドはファイル転送セッションの初期化に使用されます。

• トピック：$file/{file_id}/init または $file-async/{file_id}/init

• メッセージ本文：以下のフィールドを持つJSONオブジェクト

  {
    "name": "{name}",
    "size": {size},
    "checksum": "{checksum}",
    "expire_at": {expire_at},
    "segments_ttl": {segments_ttl},
    "user_data": {user_data}
  }

フィールド	説明
file_id	ファイル転送セッションの一意識別子。
name	ファイル名。予約名（例："."、".."）と競合する場合や特殊文字を含む場合はパーセントエンコードされます。ファイル名のバイナリ長は240バイトを超えないようにしてください。
size	ファイルサイズ。
checksum	ファイルのSHA256チェックサム（任意）。指定するとEMQXはファイルのチェックサムを検証します。
expire_at	ファイルがストレージから削除される可能性のあるタイムスタンプ（エポック秒）。
segments_ttl	ファイルセグメントの有効期間（秒）。minimum_segments_ttlとmaximum_segments_ttlで制限されます。詳細はセグメントストレージを参照してください。
user_data	ファイルに関する追加情報やメタデータを格納する任意のJSONオブジェクト。

メッセージ本文で必須なのはnameフィールドのみです。

例：

{
  "name": "ml-logs-data.log",
  "size": 12345,
  "checksum": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "expire_at": 1696659943,
  "segments_ttl": 600
}

segment コマンド

segmentコマンドはファイルのデータブロックをアップロードするために使用されます。

• トピック：$file/{file_id}/{offset}[/{checksum}] または $file-async/{file_id}/{offset}[/{checksum}]
• メッセージ本文：ファイルブロックのバイナリデータ

フィールド	説明
file_id	ファイル転送セッションの一意識別子。
offset	ファイルブロックの開始オフセット（バイト単位）、ファイル先頭からの位置。
checksum	ファイルブロックのSHA256チェックサム（任意）。

fin コマンド

finコマンドはファイル転送セッションの完了を示します。

• トピック：$file/{file_id}/fin/{file_size}[/{checksum}] または $file-async/{file_id}/fin/{file_size}[/{checksum}]
• メッセージ本文：空のメッセージ本文

フィールド	説明
file_id	ファイル転送セッションの一意識別子。
file_size	ファイルの合計サイズ（バイト単位）。
checksum	ファイル全体のSHA256チェックサム（任意）。指定された場合、initコマンドのchecksumより優先されます。

finコマンド受信後、EMQXはファイル組み立てに必要なすべてのセグメントが受信済みか検証します。ファイルが正常にエクスポートされ、チェックサムが有効な場合、EMQXは成功のReason Codeで応答します。エラーがある場合は適切なエラー応答が送信されます。

コマンド実行結果の取得

コマンド実行結果はMQTTのPUBACK Reason Codeで示されます：

• 同期転送：PUBACKのReason Codeが操作の最終結果を表します。
• 非同期転送：非ゼロのPUBACK Reason Codeは即時の失敗を示し、ゼロはコマンドが処理のため受理されたことを示します。処理完了後、結果はレスポンスメッセージで返されます。

PUBACK Reason Code

Reason Code	MQTTでの意味	ファイル転送での意味
None		0x00と同じ意味。
0x00	成功	ファイルブロックが正常にパーシステンスされた。
0x10	該当するサブスクライバーなし	サーバーはクライアントにすべてのファイルブロックの再送を要求。
0x80	不特定エラー	segmentコマンドでは現在のファイルブロックの再送を要求。finコマンドではすべてのファイルブロックの再送を要求。
0x83	特定エラー	サーバーはクライアントに送信のキャンセルを要求。
0x97	クォータ超過	サーバーはクライアントに送信の一時停止を要求。クライアントは再送まで待機すべき。

レスポンスメッセージ

• トピック：$file-response/{clientId}（clientIdはクライアントID）
• メッセージ：レスポンス結果を含むJSONオブジェクト

例：

{
  "vsn": "0.1",
  "topic": "$file-async/[COMMAND]",
  "packet_id": 1,
  "reason_code": 0,
  "reason_description": "success"
}

フィールド	説明
vsn	レスポンスメッセージフォーマットのバージョン
topic	応答対象のコマンドトピック（例：$file-async/somefileid/init）
packet_id	応答対象のコマンドのMQTTメッセージID
reason_code	コマンドの実行結果コード。詳細はReason Codes参照
reason_description	実行結果の説明

クライアントは同期・非同期に関わらず、$file-response/{clientId}トピックを通じてコマンドの実際の操作結果を取得できます。

注意事項

1. ファイル転送中にクライアントが切断された場合や、優先度の高いメッセージ送信のために転送を中断する必要がある場合は、未アックのデータブロックやコマンドを転送再開後に再送するだけで構い、ファイル全体の再送は不要です。これにより転送効率が向上します。
2. EMQXは受信したファイルセグメントからファイルを組み立てて設定済みストレージにエクスポートするため、finコマンドの処理に時間がかかる場合があります。この間、クライアントは他のコマンド送信を継続できます。finコマンド処理中に切断が発生した場合は、単にコマンドを再送して転送を再開できます。ファイル転送が完了している場合は、EMQXは即座に成功応答を返します。

クライアントコード例

さまざまな言語とクライアントライブラリによるファイル転送クライアントコード例を参照できます：

• C - Paho
• Python3 - Paho
• Java - Paho
• Golang - Paho
• Node.js - MQTT.js