# 監査エクスポートをダウンロードする

`GET /v1/audit-exports/{export_id}/download` · 権限 `audit-exports:read`

完了したエクスポートジョブのパッケージへの、1回限り有効なリンクを返します。APIキー（シークレットキーまたは制限付きキー）とダッシュボードのユーザーがダウンロードできます。ダッシュボードからダウンロードする場合は、直近のサインイン（5分以内のステップアップ認証）が必要です。リンクを発行する前に、すべての呼び出しで `audit_export.downloaded` レコードが `admin` ストリームに書き込まれます。

## リクエスト

| パラメータ | 位置 | 必須 | 説明 |
|---|---|---|---|
| `export_id` | パス | はい | エクスポートジョブのIDです。接頭辞は `aex_` です。 |

`include_ip: true` で作成されたジョブでは、ダウンロードするキーにも `audit-events:read_ip` が必要です。

## レスポンス

レスポンスは `Accept` ヘッダーによって異なります。どちらの形式にも `Cache-Control: no-store`、`Referrer-Policy: no-referrer`、`Vary: Accept` が含まれ、どちらも同じ `audit_export.downloaded` レコードを書き込みます。

- **`Accept` で `application/json` を指定**（明示的に指定し、`q` は 0 以外にします。`*/*` は対象外です）: JSON ボディとともに `200 OK` を返します。ブラウザや、クロスオリジンのリダイレクトを読み取れないクライアントではこの形式を使用してください。`url` を読み取り、そのリンクを開きます。

  | フィールド | 型 | 説明 |
  |---|---|---|
  | `url` | string | 同じホスト上の相対リンク、`/downloads/audit-exports/{environment_id}/{export_id}/{token}`。 |
  | `expires_at` | string (date-time) | リンクが無効になる日時です（発行から15分後）。 |

- **それ以外の `Accept`**: 空のボディで `302 Found` を返します。`Location` には同じ相対リンクが入ります。

- リンクの有効期間は15分で、一度だけ使用できます。トークンは、転送が中断された場合でも最初のリクエストで消費されます。新しいリンクが必要な場合は、この操作をもう一度呼び出してください。
- リンクに認証情報は不要です。トークンだけが認証情報です。`Location`（または `url`）は秘密にし、ログに出力しないでください。
- ファイルは環境の鍵で保存時に暗号化されているため、ストレージの事前署名 URL は使用しません。KeenAuth がファイルを復号してストリーミングします。

リンクにアクセスすると、`200 OK` が `Content-Type: application/x-tar`、`Content-Length`、`Content-Disposition: attachment; filename="audit-export-aex_….tar"` とともに返されます。tar パッケージには次のファイルが含まれます:

| ファイル | 内容 |
|---|---|
| `records.ndjson.gz` | 対象となる各時間帯のすべてのチェーンレコードを、シーケンス順に 1 行に 1 つの JSON オブジェクトとして格納します。条件に一致するレコードは全体を、それ以外のレコードは内容を含まないプレースホルダー（`"omitted": true`）として格納します。内容を明かさずにハッシュチェーンを再構築できるようにするためです。 |
| `manifest.json` | フィルター、件数、ファイルのハッシュ、および対象時間帯ごとの署名付きチェックポイントと包含証明を格納します。正規化 JSON（RFC 8785）です。 |
| `manifest.jws` | `manifest.json` に対する ES256 署名です。`audit-jwks.json` の公開鍵で検証できます。 |

`Content-Length` バイトを受信する前に接続が切断された場合、パッケージは不完全です。破棄して新しいリンクを取得してください。無効、使用済み、または期限切れのリンクには `404 not_found` が返されます。

## エラー

すべてのエラーは、安定した `code` を含む `application/problem+json` ボディとして返されます。

| HTTP | `code` | 発生条件 |
|---|---|---|
| 401 | `unauthenticated` | APIキーが指定されていない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | キーに `audit-exports:read` がない、ジョブが `include_ip` で作成されているのにキーに `audit-events:read_ip` がない（`required_permissions` に両方が一覧されます）、または呼び出し元が APIキーでもダッシュボードのユーザーでもない。 |
| 404 | `not_found` | ジョブが存在しない、別の環境に属している、またはIDの形式が不正。リンクの場合は、トークンが無効、使用済み、または期限切れ。 |
| 409 | `conflict` | ジョブがまだ完了していない、またはファイルの有効期限が切れている。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。後で再試行してください。 |

## 例

```bash
curl -L -o audit-export.tar \
  https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

`Accept: application/json` を指定すると、リダイレクトではなく JSON でリンクが返されます:

```bash
curl https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Accept: application/json"
```

SDK は JSON 形式を使用し、`url` と `expires_at` を返します。CLI はリンクを自分で読み取り、パッケージをファイルに書き込みます（標準出力には決して書き込みません）。既存のファイルは上書きせず、書き込んだデータのサイズと SHA-256 を表示します:

```bash
keenauth audit-exports download aex_01j9xk3m7q8r2s4t6v8w0y2z4e --file audit-export.tar
```

## 個人データ

このエンドポイントは個人データ、つまり監査イベントを扱います。[KeenAuth API における個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法について説明しています。いずれのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。