> ## 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.

# Python API クライアント

> ionworks-api Python パッケージのインストールと設定: 認証、データフレームバックエンド、リトライ、サブクライアントリファレンス

[`ionworks-api`](https://github.com/ionworks/ionworks-api) Python パッケージは、Ionworks Studio でリソースの管理、シミュレーションの実行、パイプラインの送信、データのアップロードを行うためのプログラマブルなインターフェースを提供します。

<Tip>
  コーディングエージェントから Ionworks を操作しますか？[Ionworks エージェントツールキット](/ja/agents) は、Claude Code、Codex、その他のエージェント向けに SDK 対応のスキルを提供します。このページのセットアップを代行する `install` スキルも含まれています。
</Tip>

## インストール

リポジトリからパッケージをインストールします:

```bash theme={null}
pip install ionworks-api
```

## 認証

Ionworks のアカウント設定から API キーを取得し、設定します:

```python theme={null}
from ionworks import Ionworks

# Option 1: Environment variable (recommended)
# Set IONWORKS_API_KEY in your shell environment before constructing the client
client = Ionworks()

# Option 2: Direct configuration
client = Ionworks(api_key="your_key")

# Option 3: Custom timeout and retry settings
client = Ionworks(
    timeout=30,       # Request timeout in seconds (default: 10)
    max_retries=3     # Max retries on failure (default: 5)
)
```

<Warning>
  API キーをバージョン管理にコミットしないでください。資格情報の管理には環境変数またはシークレットマネージャを使用してください。
</Warning>

<Note>
  `ionworks-api` 0.10.0 以降、`ionworks` をインポートしても `.env` ファイルは自動的に読み込まれなくなりました。クライアントを構築する前に、シェル環境で `IONWORKS_API_KEY` を設定するか、[python-dotenv](https://pypi.org/project/python-dotenv/) などを使って自分で `.env` ファイルを読み込むか、`api_key=` を `Ionworks(...)` に明示的に渡してください。
</Note>

### API キーを検証する

`client.whoami()` を使用して、設定された API キーがどのユーザーと組織に解決されるかを確認します。これは `401`/`403` エラーをデバッグしたり、間違った組織のデータが表示される理由を確認したりするための推奨方法です。

```python theme={null}
me = client.whoami()
print(me["email"], me["authorized_organization"])
# alice@example.com {'id': 'org_abc123', 'name': 'Acme Battery'}
```

レスポンスには 2 つの組織フィールドがあり、その違いは重要です:

* `authorized_organization` — このリクエストが **認可されている** 組織。SDK 呼び出しの場合、これは設定された API キーが発行された組織であり、クライアントが行うすべてのリクエストの権限チェックに使用される唯一の情報源です。組織コンテキストを解決できない場合は `None` になります。
* `organizations` — ユーザーの完全なメンバーシップリスト（所属するすべての組織）。これは別の情報であり、権限チェックには **使用されません**。

`authorized_organization` の `id` または `name` が期待と異なる場合は、誤ったキーが使用されています。[アカウント設定](https://app.ionworks.com/dashboard/settings)から正しい組織用に再生成してください。

## デフォルトプロジェクト

ほとんどのサブクライアント（pipelines、studies、optimizations、cell specifications、...）は[プロジェクト](/ja/core-concepts/projects-studies)内で動作します。すべての呼び出しに `project_id` を渡す代わりに、クライアントに一度デフォルトを設定できます。`project_id` 引数を取るサブクライアントメソッドは、明示的に渡されない場合このデフォルトにフォールバックします。

クライアントはデフォルトを次の順序で解決します:

1. `Ionworks(...)` に渡される `project_id=` 引数。
2. `IONWORKS_PROJECT_ID` 環境変数。
3. それ以外の場合、デフォルトは設定されません。プロジェクトを必要とするメソッドは、呼び出し時に `project_id` が渡されない限り `ValueError` を発生させます。

```python theme={null}
# Option 1: Environment variable (recommended)
# Set IONWORKS_PROJECT_ID in your environment or .env file
client = Ionworks()

# Option 2: Pass to the client constructor
client = Ionworks(project_id="your-project-id")

# Override on a per-call basis when needed
client.study.list(project_id="other-project-id")
```

プロジェクト ID はプロジェクト設定ページの URL で確認できます: `https://app.ionworks.com/dashboard/projects/<project-id>/settings`。

<Note>
  `PROJECT_ID` 環境変数は後方互換のため引き続き受け入れられますが、非推奨です。代わりに `IONWORKS_PROJECT_ID` を設定してください。古い名前を使用すると `DeprecationWarning` が発生し、将来のリリースで動作しなくなります。
</Note>

### 環境変数

クライアントは構築時に、以下の変数をシェル環境から読み取ります。`.env` ファイルは **自動的には** 読み込まれません。ファイルを source するか、クライアントを構築する前に [python-dotenv](https://pypi.org/project/python-dotenv/) を呼び出すなどして、環境を自分で設定してください。

| 変数                           | 必須                  | デフォルト                      | 説明                                       |
| ---------------------------- | ------------------- | -------------------------- | ---------------------------------------- |
| `IONWORKS_API_KEY`           | はい                  | —                          | アカウント設定からの API キー。                       |
| `IONWORKS_API_URL`           | いいえ                 | `https://api.ionworks.com` | API ベース URL。                             |
| `IONWORKS_PROJECT_ID`        | プロジェクトスコープの呼び出しでは必須 | —                          | サブクライアントメソッドのデフォルトプロジェクト ID。             |
| `IONWORKS_DATAFRAME_BACKEND` | いいえ                 | `polars`                   | DataFrame バックエンド: `polars` または `pandas`。 |

## DataFrame バックエンド

デフォルトでは、クライアントはデータを [polars](https://pola.rs/) DataFrame として返します。ワークフローで必要な場合は [pandas](https://pandas.pydata.org/) に切り替えられます。

```python theme={null}
# Option 1: Set via constructor
client = Ionworks(dataframe_backend="pandas")

# Option 2: Set via environment variable
# IONWORKS_DATAFRAME_BACKEND=pandas

# Option 3: Set at runtime
from ionworks import set_dataframe_backend, get_dataframe_backend

set_dataframe_backend("pandas")
print(get_dataframe_backend())  # "pandas"
```

DataFrame を返すすべてのメソッド（時系列、ステップ、サイクル）はこの設定に従います。

## タイムアウトとリトライの挙動

クライアントは接続エラー、タイムアウト、サーバーエラー（5xx）で失敗したリクエストを自動的にリトライします。デフォルトでは:

* リクエストは **10 秒** でタイムアウト
* 失敗したリクエストは指数バックオフで最大 **5 回** リトライ
* **接続切断**（リクエストがアプリケーションに到達する前にサーバーがソケットをクローズした場合 — 再利用された keep-alive 接続で発生しやすい）は、**POST と PATCH を含むすべてのメソッド**でリトライされます。リクエストがサーバーに到達していないため、再送信しても安全です。
* **読み取りタイムアウト**と **5xx 応答**は、冪等なメソッド（**GET** と **DELETE**）に対してのみリトライされます。サーバーが POST や PATCH をすでに処理している可能性があり、再送信すると操作が重複するおそれがあります。

これらの設定はカスタマイズできます:

```python theme={null}
# Longer timeout for large uploads
client = Ionworks(timeout=60)

# Disable retries
client = Ionworks(max_retries=0)
```

## サブクライアント

`Ionworks` クライアントはドメイン固有のサブクライアントを公開しています:

| サブクライアント             | アクセス                         | ドキュメント                                                    |
| -------------------- | ---------------------------- | --------------------------------------------------------- |
| Projects             | `client.project`             | [プロジェクト API](/ja/core-concepts/api)                       |
| Models               | `client.model`               | [Build API](/ja/build/api)                                |
| Parameterized models | `client.parameterized_model` | [Build API](/ja/build/api)                                |
| Studies              | `client.study`               | [Simulate API](/ja/simulate/api)                          |
| Protocols            | `client.protocol`            | [Simulate API](/ja/simulate/api)                          |
| Simulations          | `client.simulation`          | [Simulate API](/ja/simulate/api)                          |
| Pipelines            | `client.pipeline`            | [Simulate API](/ja/simulate/api)                          |
| Simple pipelines     | `client.simple_pipeline`     | [Simulate API](/ja/simulate/api#running-simple-pipelines) |
| Optimizations        | `client.optimization`        | [Optimize API](/ja/optimize/api)                          |
| Cell specifications  | `client.cell_spec`           | [データのアップロード](/ja/data/uploading)                          |
| Cell instances       | `client.cell_instance`       | [データのアップロード](/ja/data/uploading)                          |
| Cell measurements    | `client.cell_measurement`    | [測定](/ja/data/measurements)                               |
| Sites                | `client.site`                | [ラボビュー](/ja/data/lab)                                     |
| Cyclers              | `client.cycler`              | [ラボビュー](/ja/data/lab)                                     |
| Channels             | `client.channel`             | [ラボビュー](/ja/data/lab)                                     |
| Lab occupancy        | `client.lab`                 | [ラボビュー](/ja/data/lab#sdk-から占有状況を照会する)                     |
| Analyses             | `client.analysis`            | [解析](/ja/data/analyses)                                   |
| Jobs                 | `client.job`                 | [ジョブのキャンセル](#ジョブのキャンセル)                                   |
| Web アプリの URL         | `client.urls`                | [Web アプリ URL ヘルパー](#web-アプリ-url-ヘルパー)                     |

## API のディスカバリ

`client.capabilities()` と `client.schema(name)` は、`discover-api`
[エージェントスキル](/ja/agents) が利用するのと同じコンテンツを返します。
ノートブックやスクリプトから呼び出して、プラットフォームのデータ階層を
把握したり、測定や UCP プロトコルの正規の JSON Schema を取得したりでき
ます。コーディングエージェントを駆動する際にも同様に利用できます。

```python theme={null}
caps = client.capabilities()
print(caps["domain_context"]["hierarchy"])
# organization -> project -> cell_specification -> cell_instance
# -> cell_measurement -> [time_series, steps, cycles, analysis] ...

# 標準の time-series カラム名、必須フィールド、符号規約
data_schema = client.schema("data")

# UCP の JSON Schema と実行可能なサンプル
protocol_schema = client.schema("protocol")
```

`capabilities()` は OpenAPI 仕様 (`/openapi.json`) や、リソースごとの JSON
Schema エンドポイントへのポインタも `caps["schemas"]` に含めて返すため、
エージェントは create/update ペイロードの正確な形状を事前に取得できます。

<Tip>
  Ionworks を駆動するコーディングエージェントは、リクエストボディを生成
  する前に `client.capabilities()` と `client.schema(name)` を呼び出して
  ください。レスポンスは稼働中のサーバーを反映するため、エンドポイントの
  形状やカラム名を推測する必要がありません。
</Tip>

## Web アプリ URL ヘルパー

`client.urls` は、エンティティ ID から URL を手作業で組み立てなくても、Ionworks Web アプリ（Ionworks Studio）のリソースページへのリンクを構築します。ノートブック、スクリプト、ダッシュボード、Slack/メールのレポートからクリック可能なリンクを表示し、共同作業者がリソースに直接ジャンプできるようにする場合に便利です。

各ヘルパーは完全にローカルで動作し、ネットワーク呼び出しは発生しません。例外は `client.urls.simulation()` で、`parameterized_model_id` を指定しない場合に一度だけシミュレーションを取得します（下記参照）。

```python theme={null}
client = Ionworks(project_id="proj_abc")

client.urls.study("study_xyz")
# https://app.ionworks.com/dashboard/projects/proj_abc/studies/study_xyz

client.urls.parameterized_model("pm_123")
# https://app.ionworks.com/dashboard/projects/proj_abc/parameterized-models/pm_123
```

各ヘルパーは、リソース自身の ID と、ルートが必要とする親 ID を受け取ります。`project_id` はオプションで、省略するとクライアントに設定された[デフォルトプロジェクト](#デフォルトプロジェクト)にフォールバックします。

| ヘルパー                                                                                  | 返されるリンク先                         |
| ------------------------------------------------------------------------------------- | -------------------------------- |
| `client.urls.project(project_id=None)`                                                | プロジェクトのランディングページ（studies 一覧）。    |
| `client.urls.study(study_id, project_id=None)`                                        | スタディの詳細ページ。                      |
| `client.urls.model(model_id, project_id=None)`                                        | モデルの詳細ページ。                       |
| `client.urls.parameterized_model(parameterized_model_id, project_id=None)`            | パラメータ化モデルの詳細ページ。                 |
| `client.urls.simulation(simulation_id, parameterized_model_id=None, project_id=None)` | シミュレーションの詳細ページ（パラメータ化モデルの下にネスト）。 |
| `client.urls.protocol(protocol_id, project_id=None)`                                  | プロトコルの詳細ページ。                     |
| `client.urls.pipeline(pipeline_id, project_id=None)`                                  | パイプラインの詳細ページ。                    |
| `client.urls.optimization(optimization_id, project_id=None)`                          | 最適化の詳細ページ。                       |
| `client.urls.material(material_id, project_id=None)`                                  | 材料の詳細ページ。                        |
| `client.urls.cell_specs(project_id=None)`                                             | セル仕様の一覧ページ。                      |
| `client.urls.cell_instances(spec_id, project_id=None)`                                | 仕様の下にネストされたセルインスタンスの一覧ページ。       |
| `client.urls.measurement(measurement_id, project_id=None)`                            | 測定の詳細ページ。                        |

### シミュレーションの URL

シミュレーションの Web アプリのルートは、そのパラメータ化モデルの下にネストされています。`parameterized_model_id` がすでに分かっている場合は、ネットワーク呼び出しを避けるために渡してください:

```python theme={null}
client.urls.simulation("sim_1", parameterized_model_id="pm_123")
```

そうでない場合、ヘルパーは値を取得するためにシミュレーションをフェッチします:

```python theme={null}
# client.simulation.get(simulation_id) を 1 回呼び出してから URL を構築します。
client.urls.simulation("sim_1")
```

シミュレーションに `parameterized_model_id` がない場合（例: study 専用シミュレーション）、ヘルパーは `ValueError` を発生させます。その場合は親を明示的に渡してください。

## ジョブのキャンセル

Python API を使用して、実行中のジョブ（シミュレーション、パイプライン、最適化）をキャンセルできます。各ジョブには一意の ID があり、それを使用してキャンセルできます。

```python theme={null}
# Cancel a job by ID
client.job.cancel(job_id="job_abc123")
```

親ジョブをキャンセルすると、そのすべての子ジョブも自動的にキャンセルされます。例えば、パイプラインをキャンセルすると、実行中のすべての要素がキャンセルされます。

## 失敗したパイプラインの再投入

最初に失敗した要素を投入できなかったためにパイプラインが停止した場合
（`error_code = SUBMISSION_FAILED`）、構成を再構築せずに再投入できます。
完了済みの要素は保持され、実行は失敗した要素から再開されます。

Python クライアントはまだ再投入メソッドを公開していないため、暫定的な回避策として
REST エンドポイントを直接呼び出してください。再投入は汎用のジョブエンドポイントを
経由し、パイプラインはそのジョブ ID で識別されます（`client.pipeline.get(...)`
に渡すものと同じ ID です）。

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  https://api.ionworks.com/jobs/{pipeline_id}/resubmit
```

再投入は `SUBMISSION_FAILED` エラーにのみ適用されます。実行タイムアウトや構成ミスの場合は、
修正した構成で新しいパイプラインを作成してください。内部エラーの場合は、しばらく待ってから、
問題が解消しないときに新しいパイプラインを作成してください。詳細は
[パイプライン失敗への対処](/guide/pipelines/overview#handling-pipeline-failures)
を参照してください。

## ジョブメタデータの読み取り

`client.job.get_metadata(job_id)` を使用して、ジョブの `metadata.json.gz` blob の解析済みコンテンツを取得します。これは、ジョブレコード自体に収まらない大きなペイロード（特にパイプライン検証で生成される `validation_results` や `validation_plot_config`）を取得する手段です。

```python theme={null}
metadata = client.job.get_metadata("job_abc123")

# Validation payloads, when present
results = metadata.get("validation_results")
plot_config = metadata.get("validation_plot_config")
```

戻り値はジョブのメタデータ blob から解析された通常の `dict` です。ジョブにメタデータファイルがない場合（例えばメタデータが書き込まれる前に失敗した場合）、呼び出しはエラーを発生させます。多数のジョブを反復処理する場合は `try`/`except` で囲んでください。