# EMQXエージェントをEMQXフリートに接続する

EMQXフリートコネクターは、エージェントがデバイスレジストリ、デバイスシャドウ、コマンド、ジョブ、グループ、タグ、保存されたクエリ、およびデバイス検索と連携できるようにします。このコネクターを使用してデバイス操作を自動化し、フリートの状態をMQTTや外部サービスのワークフローと組み合わせることができます。

## 主なユースケース

- 保存されたクエリやタグに一致するデバイスを検索する。
- コマンドを送信するかどうか判断する前にデバイスシャドウを読み取る。
- デバイスグループの望ましいシャドウ状態を更新する。
- デバイスジョブとその実行状況を作成または確認する。
- デバイス状態をSlack、メール、チケット通知と組み合わせる。

チャットプロンプトの例：

```text
production-fleetsコネクターを使用してcold-storageタグ付きのデバイスを検索します。シャドウを読み取り、報告された温度が8度を超えるデバイスをリストアップしてください。
```

## 前提条件

コネクターを追加する前に、以下を準備してください：

- EMQXフリートのAPIエンドポイント
- APIキーとAPIシークレット
- ワークフローで必要なフリートのデプロイメントバージョンおよびAPI権限
- ワークフローで使用するthing名、thing ID、グループID、タグ名、またはジョブID

## EMQXフリートコネクターの追加

1. 左側のナビゲーションメニューで**Connectors**をクリックします。
2. **Available**タブで**EMQX Fleets**を見つけて**Add**をクリックします。
3. コネクターの各フィールドを設定します。
4. **Confirm**をクリックします。
5. **Added**タブでコネクターがリストに表示されていることを確認します。

| フィールド | 必須 | 説明 |
|---|---|---|
| **Type** | はい | 選択されたコネクタータイプ、`EMQX Fleets`。 |
| **Name** | はい | 表示名（例：`production-fleets`）。 |
| **API Endpoint** | はい | フリートAPIエンドポイント（例：`https://example.fleets.mqttce.net:8443`）。 |
| **API Key** | はい | フリートAPI認証に使用するAPIキー。 |
| **API Secret** | はい | フリートAPI認証に使用するAPIシークレット。 |
| **Timeout (seconds)** | いいえ | リクエストのタイムアウト。デフォルトは`10`秒。 |
| **Verify TLS/SSL Certificate** | いいえ | フリートAPI接続時にTLS証明書を検証します。デフォルトで有効。 |

## EMQXフリートコネクターの編集

1. **Added**タブでEMQXフリートコネクターの編集アイコンをクリックします。
2. **Edit Connector**パネルで以下のフィールドを更新します：
   - **Name**
   - **API Endpoint**
   - **API Key**
   - **API Secret**
   - **Timeout (seconds)**
   - **Verify TLS/SSL Certificate**
3. **Confirm**をクリックします。

**Type**フィールドは読み取り専用で変更できません。

## サポートされている操作

コネクターは`fleets.tools`プロバイダーを通じてフリートの操作を公開します。

### 読み取り操作

- APIのヘルスチェック、バージョン、デプロイメント概要の確認
- thing、thingタイプ、thingグループ、グループメンバー、タグの一覧取得および取得
- thingタグとデバイスシャドウの読み取り
- デバイス検索および保存されたクエリの一覧
- ジョブ、ジョブ実行、コマンド、thingイベントの一覧取得

### 書き込み操作

- 対応するレジストリリソースの作成、更新、削除
- タグの追加または削除
- 望ましいデバイスシャドウの更新またはクリア
- コマンドの送信
- ジョブおよびジョブ実行の作成、更新、キャンセル、削除

### 書き込み操作の承認

フリートの書き込み操作はデフォルトで明示的な承認が必要です。書き込み操作を実行する前に：

1. `dry_run=true`で操作を実行するか、承認なしで呼び出して、EMQXフリートにリクエストを送信せずに`planned_action`を生成します。
2. `planned_action`で操作内容、対象リソース、リクエストボディを確認します。
3. 明示的に計画された操作を承認します。
4. `approved=true`で操作を実行します。

承認が必要で提供されていない場合、ツールはリクエストを送信せずに`approval_required=true`と計画された操作を返します。

::: warning 重要なお知らせ
コマンド、シャドウの更新、レジストリの変更、ジョブ操作はデバイスやフリートの状態に影響を与える可能性があります。操作を承認する前に対象デバイスと計画された操作を必ず確認してください。
:::

<!-- TODO: コンソールでのフリート書き込み操作のドライラン計画および承認要求の表示方法を確認し、承認がユーザーに見える場合はスクリーンショットを追加してください。 -->

## 権限とセキュリティ

- 必要なフリート操作とリソースに限定したAPIキーを使用してください。
- チャットプロンプトやエージェントの指示にAPIキーやAPIシークレットを含めないでください。
- フリート操作では異なる識別子が必要になる場合があるため、thing名とthing IDを慎重に解決してください。
- 書き込み操作の対象デバイス数を制限してください。

## 制限事項

- 利用可能な操作はフリートのデプロイメントバージョンやAPIキーの権限によって異なる場合があります。
- 保存されたクエリや一部のグローバルジョブ実行ルートはすべてのデプロイメントで利用できない場合があります。
- コネクターはAPIキーのライフサイクル管理、セットアップ、証明書、リスナー、デバイスなりすまし操作を公開しません。

## トラブルシューティング

| 症状 | 解決策 |
|---|---|
| コネクターがEMQXフリートに接続できない。 | APIエンドポイント、TLS検証設定、ネットワークアクセスを確認してください。 |
| APIが認証または認可エラーを返す。 | APIキー、APIシークレット、権限を確認してください。 |
| thing、グループ、ジョブが見つからない。 | 操作にIDまたは名前が必要かを確認し、リソースを解決してから再試行してください。 |
| 操作が利用できない。 | フリートのデプロイメントバージョンとAPIキーの権限を確認してください。 |

## 関連リンク

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)