# デバイス統合の概要

本セクションは、ハードウェアを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認証で使用してください。

```text
Authorization: Basic <base64(apiKey:apiSecret)>
```

デバイス用のAPIキー作成については[APIキーの管理](../deployment/emqx_fleets_manage_deployment.md#deployment-api-keys)を参照してください。

## 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_integration.md)：シャドウ、コマンド、ジョブのMQTTセットアップ、サブスクリプション、パブリッシュ形式、フローダイアグラム
- [HTTPS統合](./https_integration.md)：HTTPSのみを使用するデバイス向けThingDatas APIリファレンス
- [デバイスシャドウ同期](./device_shadow_sync.md)：デバイス視点のシャドウ同期フローのステップバイステップ