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

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

ファイル転送プロセス

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

リスナーマウントポイントとの非互換性

ファイル転送は、マウントポイントが設定されたリスナー経由で接続されたクライアントでは動作しません。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のコマンド実行結果の確認を待ってから次の処理を行います。
  • 非同期転送：クライアントはコマンド実行結果の確認を待たずに次のコマンドを送信できるため、処理が高速化されます。
• 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 Code参照
reason_description	実行結果の説明

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

注意事項

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

クライアントコード例

各種言語およびクライアントライブラリのファイル転送クライアントコード例を参照できます。

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