> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.
# ジョブの作成と照会
> Starfort バッチ非個人化のジョブ API。POST /v1/guard/s3 でジョブ作成、GET でステータスをポーリングし、長時間処理を安定運用するパターンを示します (Starfort v1.4 版)
バッチ連携の骨格は、**ジョブの作成 → 定期照会（ポーリング）→ 成果物の回収**という 3 ステップです。どちらの API も[同一の API Key](/ja/v1.4/api/authentication) で認証します。
## ジョブ作成 API
```
POST https://bastion-guardian-api.starfort.io/v1/guard/s3
```
**リクエストヘッダー**
| ヘッダー | 必須 | 説明 |
| -------------------------- | -- | ------------------ |
| `X-Starfort-Guard-Api-Key` | はい | `sf_` で始まる発行済みキー |
| `Content-Type` | はい | `application/json` |
**リクエストボディ**
```json theme={"dark"}
{
"src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx",
"tgt_s3_url": "s3://your-bucket/deidentified/",
"process_type": "INPUT",
"options": { "on_pass": "copy_original" }
}
```
| フィールド | 必須 | 説明 |
| ----------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `src_s3_url` | はい | 原本ファイルのアドレス。`s3://<バケット>/<オブジェクトキー>` の形式で**1 つのファイル**を指し（1 ジョブ = 1 オブジェクト）、[Storage Connection](/ja/v1.4/api/batch/storage-connection) の読み取り許可範囲内である必要があります。 |
| `tgt_s3_url` | はい | 結果の保存先。`/` で終わる場合は**フォルダ**と解釈され、原本のファイル名のまま保存されます。そうでない場合は**その名前のファイル**として保存されます。書き込み許可範囲内である必要があります。 |
| `process_type` | はい | どのポリシーセットで検査するかを決める処理タイプ（例: `"INPUT"`）です。対象 Guardian が宣言した範囲内である必要があり、大文字小文字を区別しません。 |
| `options.on_pass` | いいえ | PASS 判定時の成果物 — `"copy_original"`（デフォルト、原本のコピーを保存）／`"skip"`（保存しない）。 |
バッチのリクエストボディは **snake\_case**（`process_type`）を使用します — インライン [Guard API](/ja/v1.4/api/request-format) の `processType`（camelCase）とは表記が異なります。
**レスポンス — `202 Accepted`**
```json theme={"dark"}
{ "job_id": "cmd8h2xk10003abcdxyz01234", "status": "PENDING" }
```
`job_id` を保管し、照会に使用します。
**検証のタイミング** — 受付時点では、認証・Kill Switch・`process_type`・許可範囲のみを同期的に検証します（失敗するとジョブは作成されず、即時に拒否されます）。原本の存在・サイズ・形式は処理時点で検査され、問題があればジョブが `FAILED` として確定します。[バッチのエラー](/ja/v1.4/api/batch/errors)を参照してください。
**リトライと重複** — 冪等トークンはありません。同一のリクエストを再送信すると、それぞれ別のジョブが作成されます。レスポンスの喪失時には重複受付が起こり得ますが、同じ入力・ポリシーの成果物が同じ名前でアトミックに上書きされるため、`tgt` の最終状態は同一です。受付済みジョブの `job_id` を失った場合は、後述の原本アドレス検索で復旧してください。
## ジョブ照会 API
```
GET https://bastion-guardian-api.starfort.io/v1/guard/s3/jobs/{job_id}
```
**レスポンス — `200`**
```json theme={"dark"}
{
"job_id": "cmd8h2xk10003abcdxyz01234",
"status": "COMPLETED",
"action": "MASK",
"src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx",
"tgt_s3_url": "s3://your-bucket/deidentified/contract-001.docx",
"results": [
{
"policy_name": "PII Masking Policy", "policy_type": "PII", "action": "MASK",
"detected_items": [
{ "rule_type": "regex", "rule_name": "my_number:_japan_individual_number", "action": "MASK", "confidence": 1.0, "mask_word": "MY_NUMBER_1", "alert_message": "マイナンバーを検知しました" }
]
}
],
"error": null,
"created_at": "2026-07-23T09:00:00.000Z",
"completed_at": "2026-07-23T09:00:41.000Z"
}
```
| フィールド | 説明 |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | ジョブの状態 4 種 — `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED`。[バッチ概要](/ja/v1.4/api/batch/overview)を参照してください。 |
| `action` | `COMPLETED` のときの判定（`PASS` / `MASK` / `BLOCK`）、それ以外は `null`。[アクション](/ja/v1.4/concepts/actions-pass-mask-block)を参照してください。 |
| `tgt_s3_url` | **実際に保存された結果ファイルの確定アドレス**（フォルダで指定した場合はファイル名まで含む）。保存されたファイルがなければ `null`。 |
| `results` | ポリシーごとの検出結果（ヒットしたポリシー・検出項目・マスキングトークン・信頼度） — [Guard API レスポンス](/ja/v1.4/api/response-format)の結果構造と同一で、**成果物の本文は含みません**（本文はバケットにのみあります）。 |
| `error` | `FAILED` のときの理由（`code` / `message` / `details`）。[バッチのエラー](/ja/v1.4/api/batch/errors)を参照してください。 |
| `created_at` / `completed_at` | 受付時刻／確定時刻。 |
* 照会は、そのジョブを**作成したプロジェクトの API Key でのみ**可能です。
* [Kill Switch](/ja/v1.4/admin/kill-switch) の発動中は、ジョブの作成と照会がどちらも拒否されます。
* ジョブ照会の保持期間は運用ポリシーに従い、過去のジョブの履歴は [Opticon](/ja/v1.4/admin/monitoring-opticon) で確認します — 各ジョブのトレースに受付情報（`src_s3_url`・`tgt_s3_url`・`process_type`・`job_id`）と判定・エラーが併せて記録されます。
### 原本アドレスによるジョブ検索
`job_id` を失った場合は、原本アドレスから直近のジョブを検索して復旧します:
```
GET /v1/guard/s3/jobs?src_s3_url=s3://your-bucket/inbox/2026/contract-001.docx
```
該当の原本オブジェクトで受け付けられた**直近のジョブ一覧**を新しい順に返します（デフォルト最大 20 件、`results` は含まれません — 詳細は `job_id` の単体照会で確認してください）。
```json theme={"dark"}
{ "jobs": [ { "job_id": "cmd8h2xk10003abcdxyz01234", "status": "COMPLETED", "action": "MASK", "src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx", "tgt_s3_url": "s3://your-bucket/deidentified/contract-001.docx", "error": null, "created_at": "2026-07-23T09:00:00.000Z", "completed_at": "2026-07-23T09:00:41.000Z" } ] }
```
## ポーリングパターン
`POST /v1/guard/s3` を呼び出し、レスポンスの `job_id` を保管します。
`GET /v1/guard/s3/jobs/{job_id}` を定期的に呼び出します。`status` が `PENDING` / `PROCESSING` の間は待機を続けます。
`COMPLETED` なら `action` で分岐し（`PASS` / `MASK` は `tgt_s3_url` から成果物を回収、`BLOCK` は成果物なし — 理由は `results`）、`FAILED` なら `error.code` で分岐します。
```bash theme={"dark"}
curl -X POST https://bastion-guardian-api.starfort.io/v1/guard/s3 \
-H "X-Starfort-Guard-Api-Key: sf_xxxx..." -H "Content-Type: application/json" \
-d '{ "src_s3_url": "s3://your-bucket/inbox/customer-list.xlsx", "tgt_s3_url": "s3://your-bucket/deidentified/", "process_type": "INPUT" }'
# → 202 { "job_id": "cmd8h2xk1...", "status": "PENDING" }
curl https://bastion-guardian-api.starfort.io/v1/guard/s3/jobs/cmd8h2xk1... \
-H "X-Starfort-Guard-Api-Key: sf_xxxx..."
# → 200 { "status": "COMPLETED", "action": "MASK", "tgt_s3_url": "s3://your-bucket/deidentified/customer-list.xlsx", ... }
```