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

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

ファイル転送プロセス

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

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

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は即時の失敗を示し、ゼロの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