# 接続の属性マッピングを置き換える

`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 キー）。ターゲットごとに 1 ルール。マッピングで `app_metadata` は書き込めません。 |
| `attribute_mappings[].source_name` | 文字列 | はい | 1〜512 バイト。制御文字や双方向文字を含まず、先頭または末尾に空白を含まないこと。 |
| `attribute_mappings[].source_name_format` | 文字列 \| null | いいえ | SAML の `NameFormat`（絶対 URI）。1 つのソース名は 1 つの形式でのみ読み取れます。 |
| `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` | ルールが上記の規則に違反しています。違反した各ルールは `errors[]` の 1 項目となり、`/attribute_mappings/<index>/<field>` を指します。リスト全体のルール（`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…"'
```