# 연결의 속성 매핑 교체

`PUT /v1/connections/{connection_id}/attribute-mappings` · 권한 `connections:write`

기업 연결의 속성 매핑 목록 전체를 교체합니다. 규칙의 순서는 중요하지 않으며, 응답은 대상별로 정렬됩니다. `If-Match`는 필수입니다. 없으면 요청이 `428`로 실패합니다. 읽은 이후 목록이 변경되었거나 값이 일치하지 않으면 `412`로 실패하며 아무것도 기록되지 않습니다. 같은 목록을 보내면 아무것도 기록되지 않습니다. 변경 사항은 다음 로그인부터 적용되며, 마지막으로 통과한 연결 테스트를 무효화하지 않습니다. 쓰기는 `connection.attribute_mappings_replaced`로 감사 기록됩니다(추가, 삭제, 변경된 대상). 로그인에서 얻은 속성 값은 감사 로그에 절대 기록되지 않습니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `connection_id` | 경로 | 예 | 기업 연결 ID(`conn_…`). |
| `If-Match` | 헤더 | 예 | 마지막 조회에서 받은 `ETag`. 없으면 `428`; 오래되었으면 `412`. |
| `attribute_mappings` | 배열 | 예 | 새 전체 목록. 최대 28개 규칙. |
| `attribute_mappings[].target` | 문자열 | 예 | `email`(모든 목록에 필수), `given_name`, `family_name`, `name`, `locale`, `zoneinfo`, `phone`, `groups` 또는 `user_metadata.<key>`(키는 `[a-z0-9_]{1,40}`; 등록된 OIDC 클레임 이름과 `idp_` 접두사는 허용되지 않음; 최대 20개 키). 대상당 규칙 하나. 매핑으로는 `app_metadata`를 쓸 수 없습니다. |
| `attribute_mappings[].source_name` | 문자열 | 예 | 1~512바이트, 제어 문자나 양방향 문자가 없어야 하며, 앞뒤 공백이 없어야 합니다. |
| `attribute_mappings[].source_name_format` | 문자열 \| null | 아니요 | SAML `NameFormat`(절대 URI). 하나의 소스 이름은 하나의 형식으로만 읽을 수 있습니다. |
| `attribute_mappings[].overwrite` | 문자열 | 예 | `always`, `if_empty` 또는 `never`. |
| `attribute_mappings[].profile` | 문자열 | 아니요 | 사전 설정 이름; 생략하면 `generic`. |

## 응답

저장된 목록([속성 매핑 조회](get.md) 참조)과 새 `ETag`가 포함된 `200 OK`.

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 404 | `not_found` | 이 환경에 연결이 없거나 기업 연결이 아닙니다. |
| 409 | `conflict` | 연결의 프로토콜에는 속성 매핑이 없습니다(LDAP). |
| 412 | `precondition_failed` | `If-Match`가 현재 버전과 일치하지 않거나, 목록이 동시에 변경되었습니다. |
| 422 | `validation_failed` | 규칙이 위의 규칙을 위반합니다. 위반된 각 규칙은 `/attribute_mappings/<index>/<field>`를 가리키는 `errors[]` 항목 하나가 되며, 목록 수준 규칙(`email_required`, `too_many_metadata_keys`)은 `/attribute_mappings`를 가리킵니다. |
| 428 | `precondition_required` | `If-Match` 헤더가 없습니다. |
| 400 | `unknown_field` | 요청 본문에 알 수 없는 필드가 있습니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나 잘못되었거나 폐기되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간이 지난 후 다시 시도하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간이 지난 후 다시 시도하십시오. |

## 예시

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "6f1c…"' \
  -d '{"attribute_mappings":[{"target":"email","source_name":"email","overwrite":"always"},{"target":"user_metadata.department","source_name":"department","overwrite":"if_empty"}]}'
```

```bash
keenauth connections attribute-mappings put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @mappings.json --if-match '"6f1c…"'
```