> ## 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 S3 비식별화 배치의 전체 흐름. src·tgt 버킷 참조로 구동되는 비동기 처리를 작업 제출·폴링·결과 수집 단계로 설명합니다 (Starfort v1.4 문서)

**S3 연계 비식별화 배치**는 버킷에 이미 저장된 파일을 위치만 지정해 비식별화하는 **비동기** 처리 경로입니다. 원본 주소(`src_s3_url`)와 결과 저장 주소(`tgt_s3_url`)만 전달하면, Starfort가 버킷에서 원본을 직접 읽어 개인정보(PII)·민감 주제(Topic)를 탐지하고, 비식별화(마스킹)된 파일을 지정 위치에 저장합니다.

**데이터 전달의 주체는 Starfort입니다.** Starfort가 S3 표준 오퍼레이션(GetObject / PutObject)으로 `src`를 읽고 `tgt`에 씁니다. 호출자가 할 일은 세 가지뿐입니다 — 파일을 버킷에 두고, 접근 권한을 부여하고, 결과를 `tgt`에서 수거하는 것. 전송 로직을 직접 구현할 필요가 없습니다.

## 인라인 Guard API와의 관계

배치는 기존 [Guard API](/ko/v1.4/api/quickstart) **옆에 추가되는** 경로입니다. 기존 동기 API는 그대로 유지되며, 기존 호출자에게 영향이 없습니다.

| 축     | 인라인 Guard API           | S3 연계 비식별화 배치                                                          |
| ----- | ----------------------- | ---------------------------------------------------------------------- |
| 파일 전달 | 요청 본문에 base64로 동봉       | **버킷 참조** — `src` 주소만 전달                                               |
| 처리 모델 | 동기 1턴 (응답이 곧 완료)        | **비동기 작업(job)** — 접수와 완료가 분리                                           |
| 결과 전달 | 응답 본문으로 반환              | **`tgt`에 직접 기록** — 판정별 [산출물 규칙](/ko/v1.4/api/batch/outputs-and-limits) |
| 요청 크기 | 입력 수신 상한과 base64 팽창의 제약 | 본문에 파일이 없어 **요청 크기 제약 없음**                                             |

검사 자체는 달라지지 않습니다 — 배치도 인라인과 동일한 Guardian 엔진이 동일한 정책·판정 규칙으로 검사합니다. 검사 정책은 요청이 아니라 **서버(프로젝트 설정)가 결정**하며, 배치 전용 정책 체계는 없습니다.

## 사전 준비

<Steps>
  <Step title="프로젝트와 Guardian 준비">콘솔에서 프로젝트와, 어떤 정책으로 검사할지 정의한 Guardian을 준비합니다.</Step>
  <Step title="Storage Connection 등록">Starfort가 버킷에 접근하기 위한 연계 설정을 프로젝트에 등록합니다 — 접속 정보, 접근 자격증명, 허용 대상(읽기/쓰기 범위). [Storage Connection](/ko/v1.4/api/batch/storage-connection)을 참고하세요.</Step>
  <Step title="API Key 발급">프로젝트의 API Keys 메뉴에서 발급합니다. [API 키 관리](/ko/v1.4/admin/api-keys)를 참고하세요.</Step>
</Steps>

원본 입력 폴더(예: `inbox/`)와 결과 출력 폴더(예: `deidentified/`)를 분리해 정하는 것을 권장합니다.

## 인증

기존 Guard API와 **동일한 API Key 체계**입니다. `sf_`로 시작하는 키를 `X-Starfort-Guard-Api-Key` 헤더로 전송하며, 작업은 그 키가 가리키는 Project Guardian 스코프로 귀속됩니다. [인증](/ko/v1.4/api/authentication)을 참고하세요.

## 작업 상태

배치 작업의 상태는 4종입니다:

| 상태           | 의미                                                    |
| ------------ | ----------------------------------------------------- |
| `PENDING`    | 접수되어 대기 중입니다.                                         |
| `PROCESSING` | 처리 중입니다. 내부 재시도는 노출되지 않고 처리 중이 유지됩니다.                 |
| `COMPLETED`  | 검사를 완수했습니다 — 판정(`PASS` / `MASK` / `BLOCK`)이 함께 확정됩니다. |
| `FAILED`     | 검사를 완수하지 못했습니다 — 실패 사유(`error`)가 함께 확정됩니다.            |

`PENDING → PROCESSING` 이후 `COMPLETED` 또는 `FAILED`로 확정되며, 확정된 상태는 최종입니다.

* **작업은 접수 순서대로 처리됩니다(선입선출).** 별도의 우선순위 계층은 없습니다.
* **완료 확인은 주기 조회(polling)입니다.** [작업 조회 API](/ko/v1.4/api/batch/jobs)로 상태를 확인하세요.

## BLOCK은 실패가 아닙니다

**BLOCK**은 검사가 정상 완료되어 차단 판정이 난 것이므로 `COMPLETED` + `action: "BLOCK"`으로 표현됩니다. `FAILED`는 검사를 완수하지 못한 경우이며, 결과 파일을 저장하지 않고 실패가 "탐지 없음"으로 처리되지 않습니다 — 인라인 API의 [fail-closed 원칙](/ko/v1.4/api/errors)과 같은 갈래입니다.

<Note>
  [Kill Switch](/ko/v1.4/admin/kill-switch)가 발동 중이면 작업 생성과 조회가 모두 거부되고, 대기·진행 중이던 작업은 산출물 없이 실패로 확정됩니다. 이미 `tgt`에 기록된 산출물은 소급 회수되지 않습니다.
</Note>

## 다음 단계

* [작업 생성·조회 API](/ko/v1.4/api/batch/jobs) — 엔드포인트, 요청/응답 필드, 폴링 패턴
* [Storage Connection](/ko/v1.4/api/batch/storage-connection) — S3 연계 설정과 허용 범위
* [산출물 규칙과 한도](/ko/v1.4/api/batch/outputs-and-limits) — 판정별 `tgt` 산출물, 지원 형식, 한도
* [배치 오류](/ko/v1.4/api/batch/errors) — 접수 시점 HTTP 오류와 처리 시점 실패 코드