> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# チャンネルサービス

> 理由を添えてチャンネルをサービス外にし、すべての停止期間を記録するインシデント履歴を確認します

故障中・保守中・その他の理由で使用できないチャンネルは**サービス外**に
マークでき、[ラボビュー](/ja/operate/lab-view)で利用可能な容量として
表示されなくなります。この状態への出入りはすべて**インシデント**として
記録され、チャンネルごとの停止履歴になります。

## チャンネルをサービス外にする

`out_of_commission` を切り替えると、チャンネルを削除せず、参照している過去の測定を壊さずに、プールから除外できます。`out_of_commission` の変更はすべて、チャンネルの[インシデント履歴](#チャンネルインシデント履歴)に停止レコードを開くか閉じるので、いつ — そしてなぜ — チャンネルが停止していたかを後から確認できます。

`out_of_commission` と一緒に、停止内容を説明する 3 つのオプションフィールドを渡せます:

| フィールド               | 適用タイミング    | 説明                                                                                               |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `incident_category` | サービス外にするとき | 停止の原因。`hardware_failure`、`maintenance`、`calibration`、`decommissioned`、`other` のいずれか。既定は `other`。 |
| `incident_notes`    | サービス外にするとき | 何が起きたかについての自由記述の詳細。                                                                              |
| `resolution_notes`  | サービスに戻すとき  | チャンネルを復旧させるために行った対応。                                                                             |

これら 3 つのフィールドは **`out_of_commission` の遷移にのみ注釈** を付けます — フラグを変えない PATCH では無視されます。チャンネルが既に持っている値を再送しても、新しい停止としては扱われず、no-op となります。

```python theme={null}
# チャンネルをサービス外にし、理由を記録する。
client.channel.update(
    channel_id,
    {
        "out_of_commission": True,
        "incident_category": "hardware_failure",
        "incident_notes": "セルホルダーが破損 — 交換部品を待機中",
    },
)

# 後で、サービスに戻して修理内容を記録する。
client.channel.update(
    channel_id,
    {
        "out_of_commission": False,
        "resolution_notes": "セルホルダーを交換し、再校正しました",
    },
)
```

進行中の測定があるかどうかに関係なく、ラボビューはチャンネルを `out_of_commission` として表示します。

<Note>
  `out_of_commission` はチャンネル作成時には設定できません — 作成エンドポイントは `BAD_REQUEST` で拒否します。まずチャンネルを作成し、その後 PATCH でサービス外にすることで、停止がインシデント履歴に記録されます。
</Note>

チャンネルで[時系列測定](/ja/data/measurements)がまだオープンなまま `out_of_commission` にしようとすると、`CONFLICT`（HTTP 409）が返ります — 先に測定をクローズしてください（`end_time` を PATCH します）。

修理中ではなく恒久的な退役の場合は、`incident_category` に `decommissioned` を使用します: インシデントは無期限にオープンのままとなり、修理時間の統計から除外されます。

## チャンネルインシデント履歴

`out_of_commission` の遷移はすべて **インシデント** として記録されます — 1 回の停止につき 1 行で、チャンネルが停止したときに開かれ、復旧したときに閉じられます。この履歴を使って、ダウンタイムを監査したり、停止を原因に紐付けたり、チャンネル単位の平均修理時間を算出したりできます。

1 つのチャンネルにつき、同時にオープンにできるインシデントは 1 つだけです（現在進行中の停止）。既に停止しているチャンネルに `out_of_commission: true` を送っても no-op となり、既存の停止を新しい行に分割することはありません。

### インシデントのフィールド

| フィールド              | 説明                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------- |
| `id`               | インシデントの一意な識別子。                                                                        |
| `channel_id`       | サービス外になったチャンネル。                                                                       |
| `category`         | 停止の原因: `hardware_failure`、`maintenance`、`calibration`、`decommissioned`、`other` のいずれか。 |
| `notes`            | チャンネル停止時に記録された自由記述の詳細（`incident_notes` から）。                                           |
| `started_at`       | チャンネルがサービス外になった日時。                                                                    |
| `started_by`       | チャンネルをサービス外にしたユーザー（システム操作の場合は `null` になり得ます）。                                         |
| `resolved_at`      | チャンネルがサービスに戻った日時。`null` は停止がまだオープンであることを意味します。                                        |
| `resolved_by`      | チャンネルをサービスに戻したユーザー。                                                                   |
| `resolution_notes` | 復旧のために行った対応。                                                                          |
| `is_estimated`     | `true` は、`started_at` がチャンネルの最終更新時刻から導出された上限値であるバックフィル行です。修理時間のメトリクスからは除外されます。        |

### インシデント履歴を読み取る

HTTP API を使ってチャンネルのインシデントを一覧できます。新しい停止の順に返されます:

```bash theme={null}
GET /channels/{channel_id}/incidents?limit=20&offset=0
```

```python theme={null}
# 専用のサブクライアントはまだないため、エンドポイントを直接呼び出します。
# `client.get` はパスのみを受け取るので、クエリパラメータは文字列に含めます。
history = client.get(f"/channels/{channel_id}/incidents?limit=20")

for incident in history["items"]:
    span = incident["resolved_at"] or "still open"
    print(f"{incident['started_at']} → {span}  ({incident['category']})")

print(f"{history['count']} of {history['total']} incidents shown")
```

レスポンスはページング形式のエンベロープ（`items`、`count`、`total`）です。より長い履歴をページングするには、`limit`（1〜100、既定 20）と `offset` を渡してください。

<Note>
  インシデント履歴が導入される前から存在していたチャンネルには、`is_estimated: true` のバックフィル行が 1 行あります。その `started_at` はチャンネルの最終更新時刻であり、実際に停止が始まった時刻の上限にすぎません — これらの行は「遅くともこの時点までにはダウンしていた」という情報として扱い、修理時間の統計を計算する際にはスキップしてください。
</Note>

## 次のステップ

<CardGroup cols={2}>
  <Card title="装置" icon="server" href="/ja/operate/equipment">
    サイト、サイクラー、チャンネルと、測定との紐付け。
  </Card>

  <Card title="ラボビュー" icon="grid-2" href="/ja/operate/lab-view">
    プロジェクトのライブなチャンネル占有状況。
  </Card>
</CardGroup>