HTTPS 統合

このページでは、HTTPS のみ（ThingDatas API）を使用してデバイスを EMQX Fleets に統合する方法について説明します。永続的な MQTT 接続を維持せず、データのアップロードと望ましい状態のポーリングのみが必要なデバイスにこの方法を使用してください。

制限事項

HTTPS のみのデバイスはリアルタイムのコマンドやジョブ通知を受信できません。Fleets からのインバウンドメッセージ（シャドウの望ましい状態、コマンド、ジョブのディスパッチ）は MQTT 経由で配信されます。これらを受信する必要がある場合は、MQTT 統合を単独または組み合わせて使用してください。

前提条件

• デバイスは Fleets のデプロイメントで Thing として登録されていること。
• /api/v1/thing-datas へのアクセス権限を持つデプロイメント API キーがあること。詳細は API キーの管理 を参照してください。

認証

すべての ThingDatas API リクエストには、デプロイメント API キーを用いた Basic 認証が必要です。

Authorization: Basic <base64(apiKey:apiSecret)>

例：

AUTH="Basic $(printf '%s:%s' 'ak_yourApiKey' 'your-api-secret' | base64)"

シャドウ状態の報告

デバイスの現在の状態を報告します。

POST /api/v1/thing-datas/shadow/reported

curl -X POST https://{fleets-host}/api/v1/thing-datas/shadow/reported \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "state": {
      "reported": {
        "temperature": 21.5,
        "humidity": 58
      }
    },
    "clientToken": "tok-001",
    "version": 0
  }'

• clientToken：任意。レスポンスでエコーバックされ、相関付けに使用されます。
• version：任意。シャドウのバージョンによる楽観的ロック。0 を指定すると自動インクリメントされます。

報告された状態は GreptimeDB（履歴）および PostgreSQL（最新）に保存されます。Fleets は各報告後にシャドウの差分を再計算します。

現在のシャドウの取得

起動時や保留中の望ましい状態を確認するために、デバイスの現在のシャドウを取得します。

GET /api/v1/thing-datas/{thingName}/shadow

curl https://{fleets-host}/api/v1/thing-datas/thermostat-001/shadow \
  -H "Authorization: $AUTH"

レスポンス例：

{
  "reported": { "temperature": 21.5 },
  "desired": { "targetTemperature": 24 },
  "delta": { "targetTemperature": 24 },
  "version": 5,
  "updatedAt": "2026-05-27T10:05:00Z"
}

delta が空でなければ、望ましい値を適用し、更新された状態を報告してください。

イベントのパブリッシュ

デバイスのイベントを報告します。

POST /api/v1/thing-datas/events

curl -X POST https://{fleets-host}/api/v1/thing-datas/events \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "eventType": "highTemperature",
    "severity": "warn",
    "timestamp": 1748390400000,
    "data": { "currentTemp": 45.2 }
  }'

• timestamp：Unix ミリ秒。必須。
• severity：info、warn、error。任意。
• appId：任意。マルチアプリケーションデプロイメントでのアプリ識別子。

コマンド応答の送信

MQTT 経由でコマンドを受信した場合、HTTPS 経由で応答を送信します。

POST /api/v1/thing-datas/command/response

curl -X POST https://{fleets-host}/api/v1/thing-datas/command/response \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "executionId": "8d88790c-9171-4526-8637-e6d6168bce22",
    "status": "SUCCEEDED",
    "result": { "currentTemperature": 24 },
    "timestamp": 1748390405
  }'

HTTPS 経由のジョブ

デバイスは HTTPS を介してジョブプロトコルに参加し、ポーリングと同期的なステータス報告が可能です。

保留中ジョブの取得

POST /api/v1/thing-datas/jobs/get

curl -X POST https://{fleets-host}/api/v1/thing-datas/jobs/get \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{"thingName": "thermostat-001", "clientToken": "req-1"}'

次の保留中ジョブの開始

POST /api/v1/thing-datas/jobs/start-next

ジョブ実行ステータスの報告

POST /api/v1/thing-datas/jobs/{jobId}/update

curl -X POST https://{fleets-host}/api/v1/thing-datas/jobs/{jobId}/update \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "status": "SUCCEEDED",
    "statusDetails": { "installedVersion": "2.0.0" },
    "expectedVersion": 1,
    "clientToken": "req-3"
  }'

ThingDatas API リファレンス

エンドポイント	メソッド	用途
/api/v1/thing-datas/shadow/reported	POST	シャドウ状態の報告
/api/v1/thing-datas/{thingName}/shadow	GET	現在のシャドウの取得
/api/v1/thing-datas/events	POST	イベントのパブリッシュ
/api/v1/thing-datas/command/response	POST	コマンド応答の送信
/api/v1/thing-datas/jobs/get	POST	保留中ジョブの取得
/api/v1/thing-datas/jobs/start-next	POST	次の保留中ジョブの開始
/api/v1/thing-datas/jobs/{jobId}/get	POST	特定ジョブ実行の取得
/api/v1/thing-datas/jobs/{jobId}/update	POST	ジョブ実行ステータスの報告

次のステップ

• MQTT 統合
• デバイスシャドウ同期