# Bağlantının öznitelik eşlemelerini değiştir

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

Kurumsal bağlantının öznitelik eşleme listesini tamamen değiştirir. Kuralların sırası önemsizdir; yanıt hedefe göre sıralıdır. `If-Match` zorunludur: yoksa istek `428` ile, liste okunduktan sonra değiştiyse (ya da değer eşleşmiyorsa) `412` ile başarısız olur ve hiçbir şey yazılmaz. Aynı listeyi göndermek yazma yapmaz. Değişiklik bir sonraki girişten itibaren geçerlidir ve son başarılı bağlantı testini geçersiz kılmaz. Yazma `connection.attribute_mappings_replaced` olarak audit'e düşer (eklenen, silinen ve değişen hedefler); girişlerden gelen öznitelik değerleri audit'e asla yazılmaz.

## İstek

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `connection_id` | yol | evet | Kurumsal bağlantı kimliği (`conn_…`). |
| `If-Match` | başlık | evet | Son okumadaki `ETag`. Yoksa `428`, eskiyse `412`. |
| `attribute_mappings` | dizi | evet | Tam yeni liste, en çok 28 kural. |
| `attribute_mappings[].target` | string | evet | `email` (her listede zorunlu), `given_name`, `family_name`, `name`, `locale`, `zoneinfo`, `phone`, `groups` ya da `user_metadata.<anahtar>` (anahtar `[a-z0-9_]{1,40}`; kayıtlı OIDC claim adları ve `idp_` öneki kullanılamaz; en çok 20 anahtar). Hedef başına tek kural. `app_metadata` eşlemeyle yazılamaz. |
| `attribute_mappings[].source_name` | string | evet | 1–512 bayt; denetim ya da çift yönlü metin karakteri, baş ve sonda boşluk yok. |
| `attribute_mappings[].source_name_format` | string \| null | hayır | SAML `NameFormat` (mutlak URI). Bir kaynak adı yalnız tek biçimle okunabilir. |
| `attribute_mappings[].overwrite` | string | evet | `always`, `if_empty` ya da `never`. |
| `attribute_mappings[].profile` | string | hayır | Hazır profil adı; verilmezse `generic`. |

## Yanıt

`200 OK`; saklanan liste (bkz. [Öznitelik eşlemelerini getir](get.md)) ve yeni `ETag`.

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 404 | `not_found` | Bağlantı bu ortamda yok ya da kurumsal bağlantı değil. |
| 409 | `conflict` | Bağlantının protokolünde öznitelik eşlemesi yok (LDAP). |
| 412 | `precondition_failed` | `If-Match` güncel sürümle eşleşmiyor ya da liste eşzamanlı değişti. |
| 422 | `validation_failed` | Bir kural yukarıdaki kuralları bozuyor. Her kırık kural bir `errors[]` öğesidir; işaretçi `/attribute_mappings/<sıra>/<alan>`, liste kurallarında `/attribute_mappings`'tir (`email_required`, `too_many_metadata_keys`). |
| 428 | `precondition_required` | `If-Match` başlığı yok. |
| 400 | `unknown_field` | Gövdede bilinmeyen alan var. |
| 401 | `unauthenticated` | Kimlik bilgisi yok, geçersiz ya da iptal edilmiş. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde gerekli izin yok. |
| 429 | `rate_limited` | Hız sınırı aşıldı; `Retry-After` süresinden sonra yeniden deneyin. |
| 503 | `service_unavailable` | Bir bağımlılık geçici olarak kullanılamıyor; `Retry-After` süresinden sonra yeniden deneyin. |

## Örnek

```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…"'
```