# HTTPS 統合

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

::: warning 制限事項

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

:::

## 前提条件

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

## 認証

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

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

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

## シャドウ状態の報告

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

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

```bash
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 は各報告後にシャドウの差分を再計算します。

## 現在のシャドウの取得

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

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

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

レスポンス例：
```json
{
  "reported": { "temperature": 21.5 },
  "desired": { "targetTemperature": 24 },
  "delta": { "targetTemperature": 24 },
  "version": 5,
  "updatedAt": "2026-05-27T10:05:00Z"
}
```

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

## イベントのパブリッシュ

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

```text
POST /api/v1/thing-datas/events
```

```bash
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 経由で応答を送信します。

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

```bash
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 を介してジョブプロトコルに参加し、ポーリングと同期的なステータス報告が可能です。

### 保留中ジョブの取得

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

```bash
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"}'
```

### 次の保留中ジョブの開始

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

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

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

```bash
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 統合](./mqtt_integration.md)
- [デバイスシャドウ同期](./device_shadow_sync.md)