# CoAP クライアント接続ガイド

## 接続の作成

`Connection Mode` のみ利用可能です。

このインターフェースは、CoAP ゲートウェイへのクライアント接続を作成するために使用します。CoAP ゲートウェイの認証が有効な場合、このリクエストで提供された `clientid`、`username`、`password` をゲートウェイが検証し、不正なユーザーを防止します。

**リクエストパラメータ:**

- メソッド: `POST`
- URI: `mqtt/connection{?QueryString*}`、`QueryString` は以下の通りです:
  - `clientid`: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
  - `username`: 任意パラメータ、UTF-8 文字列。接続認証に使用します。
  - `password`: 任意パラメータ、UTF-8 文字列。接続認証に使用します。
- ペイロード: 空

**レスポンス:**

- ステータスコード:
  - `2.01`: 接続が正常に作成されました。この接続に使用するトークン文字列がメッセージ本文に返されます。
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.01` の場合は `Token`、それ以外は `ErrorMessage`。
  - `Token`: 後続リクエストで使用するトークン文字列。
  - `ErrorMessage`: エラー内容の説明。

`libcoap` を例にすると：

```bash
# clientid=123、username/password=admin/public で接続を作成
# トークンを返す: 3404490787
coap-client -m post -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&username=admin&password=public"

3404490787

```

::: tip

接続が正常に作成されると、対応するデプロイメントの CoAP ゲートウェイページのクライアントリストで確認できます。

:::

## 接続の切断

`Connection Mode` のみ利用可能です。

このインターフェースは、CoAP 接続を切断するために使用します。

**リクエストパラメータ:**

- メソッド: `DELETE`
- URI: `mqtt/connection{?QueryString*}`、`QueryString` は以下の通りです:
  - `clientid`: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
  - `token`: 必須パラメータ、接続作成リクエストで返されたトークン文字列を使用します。
- ペイロード: 空

**レスポンス:**

- ステータスコード:
  - `2.01`: 接続が正常に切断されました。
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.01` の場合は `Token`、それ以外は `ErrorMessage`。

例：

```bash
coap-client -m delete -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&token=3404490787"
```

## ハートビート

`Connection Mode` のみ利用可能です。

このインターフェースは、CoAP クライアントとゲートウェイ間の接続維持に使用します。ハートビートが期限切れになると、ゲートウェイはセッションとサブスクリプションを削除し、そのクライアントのすべてのリソースを解放します。

**リクエストパラメータ:**

- メソッド: `PUT`
- URI: `mqtt/connection{?QueryString*}`、`QueryString` は以下の通りです:
  - `clientid`: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
  - `token`: 必須パラメータ、接続作成リクエストで返されたトークン文字列を使用します。
- ペイロード: 空

**レスポンス:**

- ステータスコード:
  - `2.01`: 接続が正常に維持されました。
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.01` の場合は `Token`、それ以外は `ErrorMessage`。

例：

```bash
coap-client -m put -e "" "coap://${your-deployment-connection-address}/mqtt/connection?clientid=123&token=3404490787"
```

:::tip

ハートビート間隔は CoAP ゲートウェイ設定の `heartbeat` オプションで設定可能で、デフォルトは 30 秒です。

:::

## メッセージのパブリッシュ

このインターフェースは、CoAP クライアントが指定したトピックにメッセージをパブリッシュするために使用します。`Connection Mode` が有効な場合は追加の識別情報を付与する必要があります。

**リクエストパラメータ:**

- メソッド: `POST`
- URI: `ps/{+topic}{?QueryString*}`
  - `{+topic}` はパブリッシュするトピックです。例えば `coap/test` にパブリッシュする場合、URI は `ps/coap/test` となります。
  - `{?QueryString}` はリクエストパラメータ:
    - `clientid`: `Connection Mode` では必須、`Connectionless Mode` では任意。
    - `token`: `Connection Mode` のみ、必須パラメータ。
    - `retain`（任意）: リテインメッセージとしてパブリッシュするかどうか。真偽値、デフォルトは `false`。
    - `qos`: メッセージの QoS（サービス品質）。メッセージの QoS レベルを示し、MQTT クライアントの受信方法にのみ影響します。値は `0`、`1`、`2` のいずれか。
    - `expiry`: メッセージの有効期限（秒単位）。デフォルトは 0（期限なし）。
- ペイロード: メッセージペイロード

**レスポンス:**

- ステータスコード:
  - `2.04`: パブリッシュ成功
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.04` の場合は空、それ以外は `ErrorMessage`。

例：`Connectionless Mode` でメッセージをパブリッシュする場合：

```bash
coap-client -m post -e "Hi, this is libcoap" "coap://${your-deployment-connection-address}/ps/coap/test"
```

または、`Connection Mode` で `clientid` と `token` を付与する場合：

```bash
coap-client -m post -e "Hi, this is libcoap" "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"
```

## トピックのサブスクライブ

このインターフェースは、CoAP クライアントがトピックをサブスクライブするために使用します。`Connection Mode` が有効な場合は追加の識別情報を付与する必要があります。

**リクエストパラメータ:**

- メソッド: `GET`
- オプション: `observer` を `0` に設定
- URI: `ps/{+topic}{?QueryString*}`
  - `{+topic}` はサブスクライブするトピックです。例えば `coap/test` をサブスクライブする場合、URI は `ps/coap/test` となります。
  - `{?QueryString}` はリクエストパラメータ:
    - `clientid`: `Connection Mode` では必須、`Connectionless Mode` では任意。
    - `token`: `Connection Mode` のみ、必須パラメータ。
    - `qos`: サブスクライブの QoS。ゲートウェイが CoAP クライアントにメッセージを配信する際に使用するメッセージタイプ（`CON` または `NON`）を示します。値は以下の通り：
      - `0`: `NON` メッセージを使用して配信
      - `1` または `2`: `CON` メッセージを使用して配信
- ペイロード: 空

**レスポンス:**

- ステータスコード:
  - `2.05`: サブスクライブ成功
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.05` の場合は空、それ以外は `ErrorMessage`。

例：`Connectionless Mode` で `coap/test` をサブスクライブする場合：

```bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://${your-deployment-connection-address}/ps/coap/test"
```

または、`Connection Mode` で `clientid` と `token` を付与してサブスクライブする場合：

```bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"
```

## トピックのサブスクライブ解除

このインターフェースは、CoAP クライアントがトピックのサブスクライブを解除するために使用します。

現状の実装では、サブスクライブ解除操作は `Connection Mode` のみで利用可能です。

**リクエストパラメータ:**

- メソッド: `GET`
- URI: `ps/{+topic}{?QueryString*}`
  - `{+topic}` はサブスクライブ解除するトピックです。例えば `coap/test` の場合、URI は `ps/coap/test` となります。
  - `{?QueryString}` はリクエストパラメータ:
    - `clientid`: `Connection Mode` では必須、`Connectionless Mode` では任意。
    - `token`: `Connection Mode` のみ、必須パラメータ。
- ペイロード: 空

**レスポンス:**

- ステータスコード:
  - `2.07`: サブスクライブ解除成功
  - `4.00`: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
  - `4.01`: 認可されていません。リクエスト形式は正しいものの認可に失敗しました。
- ペイロード: ステータスコードが `2.07` の場合は空、それ以外は `ErrorMessage`。

例：`Connection Mode` で `coap/test` のサブスクライブを解除する場合：

```bash
coap-client -m get -O 6,0x01 "coap://${your-deployment-connection-address}/ps/coap/test?clientid=123&token=3404490787"
```

## 短縮パラメータ名

メッセージサイズを削減するため、CoAP ゲートウェイは短縮パラメータ名をサポートしています。例えば、`clientid=barx` は `c=bar` と書くことができます。サポートされている短縮パラメータ名は以下の表の通りです：

| パラメータ名   | 短縮名  |
| :------------- | :------- |
| `clientid`     | `c`      |
| `username`     | `u`      |
| `password`     | `p`      |
| `token`        | `t`      |
| `qos`          | `q`      |
| `retain`       | `r`      |