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

# 사용자 가져오기

> 필수 열, 유효성 검사 규칙, 다시 업로드 동작 및 대신 HR 동기화를 사용해야 하는 경우와 함께 CSV 파일에서 Iru Identity 사용자를 일괄 생성하고 업데이트합니다.

한 번에 여러 명의 사용자를 추가하거나 업데이트해야 하는 경우 **CSV** 파일에서 사용자를
일괄로 가져오세요. 가져온 각 사용자에게는 **`csv`** 소스 태그가 지정되며, 업데이트된
파일을 다시 업로드하면 동기화된 상태로 유지됩니다. CSV 가져오기는 초기 로드 및 일회성
업데이트에 적합합니다. HR 시스템이 지속적인 신뢰할 수 있는 정보 소스인 경우 대신
[HR 동기화](#when-to-use-hr-sync-instead)를 사용하세요.

정의한 [사용자 지정 속성](/ko/identity/directory/schema#custom-attributes)을 파일의 열로
포함할 수도 있습니다. **Directory → Users**에서 **+ User** 옆의 화살표를 선택한 다음
**Import via CSV**를 선택합니다.

<Note>
  목록이 변경될 때마다 다시 업로드하세요. CSV 가져오기와 HR 동기화를 결합할 수
  있습니다. 많은 팀이 CSV로 디렉터리를 초기 구성한 다음 HR 시스템을 연결하여 최신 상태로
  유지합니다. [HR 동기화를 사용해야 하는 경우](#when-to-use-hr-sync-instead)를
  참조하세요.
</Note>

## 파일 요구 사항

| 요구 사항 | 세부 정보 |
| - | - |
| **형식** | 쉼표로 구분된 값(`.csv`). |
| **인코딩** | UTF-8. 선행 바이트 순서 표시(Excel이 추가하는 것)는 허용되며 무시됩니다. |
| **첫 번째 행** | 열 이름을 지정하는 **헤더 행**. |
| **헤더 이름(핵심 열)** | **대/소문자를 구분**하며 정확히 일치해야 합니다(`ExternalID`가 아닌 `externalId`). |
| **헤더 이름(사용자 지정 속성)** | `categorySlug.attributeSlug`를 사용합니다. 헤더의 대/소문자와 공백은 무시됩니다. |
| **최대 행 수** | 업로드당 50,000개의 데이터 행. |
| **최대 파일 크기** | 16MB. |

<Warning>
  가져오기는 **전부 아니면 전무** 방식입니다. 파일에 구조적 문제가 있거나 행 하나라도
  유효성 검사에 실패하면 **아무것도 가져오지 않습니다**. Iru는 모든 문제에 대한 보고서를
  반환하므로 파일을 수정하고 다시 업로드할 수 있습니다.
</Warning>

## 열

가져오기 대화 상자에는 파일에 포함할 수 있는 모든 열(필수 핵심 열, 선택적 핵심 열 및
[스키마](/ko/identity/directory/schema)의 사용자 지정 속성 열)이 나열됩니다.
**Download sample.csv**의 샘플을 헤더 템플릿으로 사용하세요. 열 이름이 샘플과 일치하면
각 행의 값이 `externalId`로 식별된 사용자의 일치하는 프로필 필드를 채웁니다.

### 필수

모든 행에는 다음 각 열에 대해 비어 있지 않은 값이 포함되어야 합니다.

| 열 | 설명 | 규칙 | 예 |
| - | - | - | - |
| `externalId` | 사용자에 대한 안정적인 식별자로, 다시 업로드할 때 행을 매칭하는 데 사용됩니다. | 비어 있지 않음, **파일 내에서 고유**. | `EMP-10482` |
| `username` | 사용자의 로그인 사용자 이름. | 비어 있지 않음. | `jane.doe` |
| `email` | 사용자의 기본 이메일 주소. | 유효한 **단순** 주소(표시 이름 없음, `Jane <jane@example.com>`은 거부됨). | `jane.doe@example.com` |
| `firstName` | 이름. | 비어 있지 않음. | `Jane` |
| `lastName` | 성. | 비어 있지 않음. | `Doe` |

### 선택 사항

값이 필요하지 않은 경우 셀을 비워 두거나 열을 완전히 생략하세요. `domain`이 비어 있으면
Iru가 이메일 주소에서 도출합니다.

| 열 | 설명 | 규칙 | 예 |
| - | - | - | - |
| `domain` | 사용자의 도메인. | 비어 있으면 `email`의 `@` 뒤 부분에서 도출됩니다. 달라야 하는 경우에만 설정하세요. | `example.com` |
| `streetAddress` | 주소의 도로명 줄. | 자유 텍스트. | `123 Main St` |
| `locality` | 시 또는 읍. | 자유 텍스트. | `San Francisco` |
| `region` | 주, 도 또는 지역. | 자유 텍스트. | `CA` |
| `postalCode` | 우편번호 또는 ZIP 코드. | 자유 텍스트. | `94105` |
| `country` | 국가. | 자유 텍스트(예: ISO 국가 코드). | `US` |
| `phone` | 전화번호. | E.164로 정규화됩니다. [전화번호](#phone-numbers)를 참조하세요. | `+14155550101` |

### 사용자 지정 속성

스키마에서 사용자 지정 속성을 정의하면 가져오기 대화 상자의 **Custom attribute columns**
아래에 카테고리 슬러그와 속성 슬러그로 구성된 `categorySlug.attributeSlug` 이름으로
나열됩니다. 예를 들어 슬러그가 `extrainfo`인 카테고리의 `department`와 `title`은
`extrainfo.department` 및 `extrainfo.title`로 표시됩니다.

CSV 헤더에 속성당 하나의 열을 추가하세요. 핵심 열 이름은 정확히 일치해야 하며, 사용자
지정 속성 열 이름은 대/소문자와 공백을 무시합니다.

### 샘플 파일

가져오기 대화 상자에서 **Download sample.csv**를 선택하면 모든 핵심 열과 예제 사용자
한 명이 포함된 시작 파일을 받을 수 있습니다. 스키마에 사용자 지정 속성이 포함된 경우
**Download sample.csv** 옆의 화살표를 선택한 다음 **With custom attributes**를 선택합니다.
이 샘플은 스키마의 각 사용자 지정 속성에 대한 열을 추가하고 예제 행에서 해당 셀을 비워
두어 직접 채울 수 있도록 합니다. 핵심 열과 예제 사용자는 동일하게 유지됩니다.

예제 사용자를 자신의 행으로 바꾸고 헤더 이름은 변경하지 마세요.

<Expandable title="선택적 열 변형">
  모든 행에 모든 선택적 열이 필요한 것은 아닙니다. 행에는 필수 열만 포함하거나, 부분
  주소를 포함하거나, 국가 코드가 있거나 없는 전화번호를 포함할 수 있습니다. 이메일 주소와
  일치해야 하는 경우 `domain`을 비워 두고, 사용자에 대한 값이 없으면 사용자 지정 속성
  셀을 비워 두세요.
</Expandable>

## 필드 동작

### 도메인 도출

* `domain`이 **비어 있으면** Iru가 이메일 주소에서 가져옵니다(`jane.doe@example.com`은
  `example.com`이 됨).
* `domain`이 **제공되면** 해당 값이 그대로 사용됩니다.
* 아직 존재하지 않는 도메인은 자동으로 생성됩니다.

### 전화번호

전화번호 값은 Iru Identity의 다른 모든 곳에서 전화번호가 저장되는 방식과 동일하게
**E.164**(선행 `+`, 국가 코드, 숫자로 구성되며 공백이나 구두점 없음)로 정규화됩니다.

| 입력 값 | 저장 값 | 이유 |
| - | - | - |
| `4155550101` | `+14155550101` | 국가 코드 없음. 기본값 **`+1`**(북미)이 추가됩니다. |
| `(415) 555-0101` | `+14155550101` | 구분 기호가 제거되고 `+1`이 추가됩니다. |
| `14155550101` | `+14155550101` | 이미 `1`을 포함하는 북미 번호로 인식됩니다. |
| `+14155550101` | `+14155550101` | 이미 E.164 형식이므로 그대로 유지됩니다. |
| `+44 7911 123456` | `+447911123456` | 국제 번호(`+` 있음). 국가 코드는 유지되고 구분 기호는 제거됩니다. |
| `1-800-FLOWERS` | *거부됨* | 문자가 포함되어 있습니다. |
| `555-0101` | *거부됨* | 유효한 번호가 되기에는 숫자가 너무 적습니다. |

<Tip>
  북미 이외 지역의 번호에는 `+`와 국가 코드(예: `+44…`)가 포함되어야 합니다. 선행 `+`가
  없으면 번호는 10자리 북미 번호로 간주되어 `+1`이 추가됩니다.
</Tip>

### 주소

Iru는 주소 열 중 **하나라도** 값이 있으면 주소를 저장합니다. 부분 주소(예: `locality`와
`country`만)도 괜찮으며, 누락된 부분은 비어 있는 상태로 유지됩니다. 모든 주소 열이 비어
있으면 주소가 저장되지 않습니다.

## 가져오기 실행

**Import users via CSV** 대화 상자에는 필수 및 선택적 핵심 열, 스키마의 사용자 지정 속성
열, 그리고 **With custom attributes** 화살표가 있는 **Download sample.csv**가 표시됩니다.
파일을 업로드 영역으로 끌어다 놓거나 찾아보기로 선택하세요.

<Steps>
  <Step title="가져오기 시작">
    **Directory → Users**에서 **+ User** 옆의 화살표를 선택한 다음 **Import via CSV**를
    선택합니다. 대화 상자의 열 목록을 위 표와 비교하여 검토합니다.
  </Step>

  <Step title="파일 준비">
    **Download sample.csv**를 선택하여 핵심 열과 예제 사용자 한 명이 포함된 파일을
    받습니다. 파일에 사용자 지정 속성 열이 포함된 경우 **Download sample.csv** 옆의
    화살표를 선택한 다음 **With custom attributes**를 선택합니다. 예제 사용자를 자신의
    행으로 바꾸고 샘플 헤더 이름을 유지하여 각 행이 올바른 사용자 및 프로필 필드에
    매핑되도록 합니다.
  </Step>

  <Step title="파일 선택">
    CSV를 선택하거나 업로드 영역으로 끌어다 놓습니다.
  </Step>

  <Step title="업로드 및 유효성 검사">
    Iru는 먼저 전체 파일의 유효성을 검사합니다. 유효성 검사를 통과하면 행이 수락되고
    백그라운드에서 사용자가 생성되거나 업데이트됩니다. 유효성 검사에 실패하면 대화 상자에
    보고서가 표시되고 아무것도 가져오지 않습니다.
  </Step>

  <Step title="결과 검토">
    업로드에 성공하면 스테이징된 사용자 수가 보고되고 가져오기가 기록에 추가되며, 여기에서
    각 행의 결과를 검토할 수 있습니다.
  </Step>

  <Step title="사용자 초대">
    가져오기로 생성된 사용자는 설정을 완료할 때까지 **pending** 상태입니다. 사용자 목록에서
    [일괄](/ko/identity/directory/users#resend-invites-in-bulk)로 초대하거나 사용자
    레코드에서
    [한 명씩](/ko/identity/directory/users#resend-an-invite-for-one-user) 초대하세요.
    초대가 전송되는 이메일을 포함하여 초대 작동 방식은
    [사용자 초대](/ko/identity/directory/users#inviting-users)를 참조하세요.
  </Step>
</Steps>

업로드한 후 Iru는 전체 파일의 유효성을 검사합니다. 유효성 검사에 실패하면 아무것도
가져오지 않습니다. 보고된 문제를 수정하고 다시 업로드하세요. 유효성 검사를 통과하면 행이
수락되고 스테이징되며, 백그라운드에서 사용자가 생성되거나 업데이트됩니다. 기록에서
가져오기를 확인하여 각 행을 확인하세요. 파일이 수락된 후에도 적용 시점에 행이 실패할 수
있습니다. 해당 행을 수정하고 다시 가져오세요. 두 단계의 검사에 대해서는
[유효성 검사 및 오류](#validation-and-errors)를 참조하세요.

## 생성 대 업데이트: 다시 업로드

사용자는 `csv` 소스 내에서 `externalId`로 매칭됩니다.

* \*\*새 `externalId`\*\*는 **`end-user`** 역할을 가진 새 사용자를 생성합니다.
* \*\*기존 `externalId`\*\*는 행에서 해당 사용자의 프로필을 업데이트합니다. 역할과 그룹
  멤버십은 변경되지 않습니다.

언제든지 수정되거나 확장된 CSV를 다시 업로드하여 가져온 사용자를 동기화된 상태로
유지하세요. 파일의 모든 `externalId`는 고유해야 합니다.

<Note>
  변경한 행만이 아니라 현재 **전체** 파일을 매번 다시 업로드하세요. 각 가져오기는
  `externalId`로 매칭됩니다.
</Note>

## 유효성 검사 및 오류

유효성 검사는 두 단계로 실행됩니다. 파일이 완전히 수락될 때까지 **아무것도 가져오지
않습니다**.

<AccordionGroup>
  <Accordion title="파일 문제(전체 파일이 거부됨)">
    파일을 처리할 수 없습니다. 일반적인 원인으로는 중복 열, 누락된 필수 열, 빈 파일,
    데이터 행이 없는 헤더 또는 제한을 초과하는 행 수가 있습니다. 파일을 수정하고 다시
    업로드하세요.
  </Accordion>

  <Accordion title="행 문제(여전히 아무것도 가져오지 않음)">
    파일 형식은 올바르지만 하나 이상의 행이 유효하지 않습니다. Iru는 모든 문제를
    **줄**(헤더가 1번 줄이므로 첫 번째 데이터 행은 2번 줄), 문제가 있는 **열**(전체 행
    문제의 경우 비어 있음) 및 **메시지**와 함께 반환합니다. 예:

    | Line | Column | Message |
    | - | - | - |
    | 3 | `email` | is not a valid email address |
    | 5 | `username` | is required |
    | 8 | `phone` | is not a valid phone number |
    | 9 | `externalId` | is duplicated in this file |

    나열된 행을 수정하고 다시 업로드하세요.
  </Accordion>

  <Accordion title="적용 오류(정상 파일이 수락된 후)">
    파일이 수락되면 행이 백그라운드에서 적용됩니다. 예를 들어 이메일이 이미 다른 사용자에
    의해 사용 중이거나 값이 [고유 속성](/ko/identity/directory/schema)과 충돌하는 경우
    이 단계에서도 행이 실패할 수 있습니다. 이러한 **적용 오류**는 행의 `externalId`,
    `username` 및 오류 세부 정보와 함께 가져오기 배치에 기록됩니다. 해당 행을 수정하고
    다시 가져오세요.
  </Accordion>
</AccordionGroup>

## HR 동기화를 사용해야 하는 경우

목록이 변경될 때마다 CSV를 다시 업로드하면 Iru가 모든 행을 다시 검사합니다. 지속적이고
수동 개입 없는 프로비저닝을 위해서는 대신 HR 시스템을 신뢰할 수 있는 기록으로 연결하세요.

| | CSV 가져오기 | HR 시스템 동기화 |
| - | - | - |
| **트리거** | 파일을 업로드할 때 | 일정에 따라 자동 실행 |
| **최신 상태 유지?** | 다시 업로드할 때 | 예(자동으로 다시 동기화) |
| **생성 / 업데이트** | 둘 다, `externalId`로 매칭 | 둘 다, 자동 |
| **제거** | 수동 | 오프보딩 시 사용자 제거 가능 |
| **적합한 용도** | 초기 로드, 임시 추가 | 지속적인 수명 주기 자동화 |

<Note>
  둘 다 사용할 수 있습니다. HR 동기화 설정은
  [Directory Sync](/ko/identity/directory/directory-sync)에서 다룹니다.
</Note>

## 다음 단계

<CardGroup cols={2}>
  <Card title="HR 시스템 연결" icon="building-user" href="/ko/identity/directory/directory-sync">
    일정에 따라 생성, 업데이트 및 제거를 자동화합니다.
  </Card>

  <Card title="먼저 스키마 설계" icon="table-list" href="/ko/identity/directory/schema">
    가져오기 전에 필수 속성과 고유 속성을 정의합니다.
  </Card>

  <Card title="개별 사용자 관리" icon="user" href="/ko/identity/directory/users">
    가져온 사용자를 편집, 일시 중지 및 초대합니다.
  </Card>

  <Card title="그룹으로 구성" icon="users" href="/ko/identity/directory/groups">
    가져온 사용자를 할당 가능한 그룹으로 만듭니다.
  </Card>
</CardGroup>