デバイス統合の概要

本セクションは、ハードウェアをEMQX Fleetsと統合するデバイスおよびファームウェア開発者向けです。デバイスがFleetsバックエンドとどのように接続し、認証し、データを交換するかについて説明します。

2つの統合パス

デバイスはMQTTまたはHTTPS（または両方）を介してFleetsと通信できます。

	MQTT	HTTPS
接続タイプ	長時間接続、双方向	リクエストごと、リクエスト-レスポンスのみ
クラウドからデバイスへのメッセージ受信	可能（トピックをサブスクライブ）	プッシュ不可；GETリクエストによるポーリング
オフラインメッセージキュー	あり（永続的なMQTTセッションで）	なし
シャドウの更新	デルタトピックのサブスクライブで受信	GET /api/v1/thing-datas/{thingName}/shadow でポーリング
コマンド	コマンドトピックのサブスクライブで受信	インバウンドコマンドは未対応
ジョブ通知	jobs/notify トピックで受信	POST /api/v1/thing-datas/jobs/get でポーリング
状態／イベントの報告	MQTTトピックにパブリッシュ	ThingDatas APIエンドポイントにPOST
プロトコルオーバーヘッド	低い	高い（リクエストごとのTLSハンドシェイク）
必要なSDK	MQTTクライアントライブラリ	標準HTTPクライアント

クラウドからのコマンド受信、シャドウの望ましい状態、ジョブ通知のプッシュが必要な場合はMQTTを使用してください。これはほとんどのIoTデバイスに推奨されるパスです。

デバイスがデータ（イベント、シャドウ状態）の報告のみを行い、望ましい状態の変更をポーリングで取得できる場合はHTTPSを使用してください。リソース制約のあるデバイスや永続的なTCP接続が困難な環境に適しています。

デバイスの識別

デバイスがFleetsと通信する前に、Thingとして登録されている必要があります。通信に関連する識別フィールドは以下の2つです。

フィールド	用途
Thing名	すべてのMQTTシステムトピックおよびThingDatas APIリクエストボディの {thingName}
MQTTクライアントID	MQTT CONNECTパケットのクライアントID。ライフサイクルイベントの追跡に使用

これらの値は同じでも異なっていてもかまいません。トピックパスやAPIペイロードではThing名を一貫して使用してください。

認証

EMQXブローカーへのMQTT接続

デバイスはFleetsデプロイメントに関連付けられたEMQXブローカーに標準のMQTT認証で接続します。ホスト、ポート、認証情報はデプロイメントの接続設定を参照してください。

HTTPS（ThingDatas API）

すべての /api/v1/thing-datas/* エンドポイントは認証が必要です。Deployment APIキーをBasic認証で使用してください。

Authorization: Basic <base64(apiKey:apiSecret)>

デバイス用のAPIキー作成についてはAPIキーの管理を参照してください。

MQTTシステムトピック

すべてのFleetsシステムトピックは $emqx/ プレフィックスを使用します。カスタムテレメトリトピック（設定されている場合）はアプリケーション定義のパスを使用します。

トピックパターン	方向	用途
$emqx/things/{name}/shadow/update	双方向	シャドウ状態（クラウドからの望ましい状態、デバイスからの報告状態）
$emqx/things/{name}/shadow/update/delta	クラウド → デバイス	デルタ通知
$emqx/things/{name}/events/{type}	デバイス → クラウド	イベント（QoS 1）
$emqx/commands/things/{name}/executions/{id}/request	クラウド → デバイス	コマンドリクエスト
$emqx/commands/things/{name}/executions/{id}/response	デバイス → クラウド	コマンドレスポンス
$emqx/things/{name}/jobs/notify	クラウド → デバイス	保留中ジョブの変更通知
$emqx/things/{name}/jobs/notify-next	クラウド → デバイス	次の保留中ジョブの変更通知
$emqx/things/{name}/jobs/get	デバイス → クラウド	保留中ジョブ一覧のリクエスト
$emqx/things/{name}/jobs/start-next	デバイス → クラウド	次の保留中ジョブの開始
$emqx/things/{name}/jobs/{jobId}/get	デバイス → クラウド	特定ジョブ実行の取得
$emqx/things/{name}/jobs/{jobId}/update	デバイス → クラウド	ジョブ実行状況の報告

次のステップ

• MQTT統合：シャドウ、コマンド、ジョブのMQTTセットアップ、サブスクリプション、パブリッシュ形式、フローダイアグラム
• HTTPS統合：HTTPSのみを使用するデバイス向けThingDatas APIリファレンス
• デバイスシャドウ同期：デバイス視点のシャドウ同期フローのステップバイステップ