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

# 빌드 별칭 관리 및 할당

> PlayFab 빌드 별칭을 사용하여 안전한 롤아웃, 하위 호환성, 게임 모드를 위해 가중치가 부여된 빌드 전반에 걸쳐 멀티플레이어 서버 할당을 분산합니다.

빌드 별칭(build alias)은 빌드 위에 있는 관리 계층으로, `RequestMultiplayerServer` 호출을 제어된 방식으로 여러 빌드에 걸쳐 분산시킬 수 있게 해줍니다. 이는 빌드 간 업그레이드 및 아래에 나열된 여러 시나리오의 단순성과 신뢰성을 개선할 수 있습니다. 별칭은 각 빌드 ID의 가중치와 함께 빌드 ID 목록을 지정하여 이를 달성합니다. 빌드의 가중치는 각 할당 요청에 대해 해당 빌드가 먼저 시도될 가능성을 설정합니다. 예를 들어 Build 1의 가중치가 8이고 Build 2의 가중치가 2이면, Build 1은 요청의 약 80%에 대해 먼저 시도되므로 StandingBy 서버가 있는 동안 요청의 약 80%를 처리합니다. Build 1의 StandingBy 서버가 특정 지역에서 소진되면 해당 요청은 대신 Build 2로 전달되므로, Build 2가 해당 지역에서 요청의 20% 이상을 처리할 수 있습니다. 하지만 각 요청의 지역이 우선하며, 가중치는 지역 내에서 어떤 빌드가 요청을 처리할지만 결정합니다. 자세한 내용은 [다른 빌드 및 지역으로의 대체](#fallback-to-other-builds-and-regions)를 참조하세요.

### 하위 호환성이 있는 안전한 배포

이는 게임 서버를 업데이트하고 있고 소매 클라이언트가 두 서버 모두와 호환되는 빌드 간 업그레이드에 대한 가장 일반적인 시나리오입니다.

클라이언트는 별칭 1을 참조하며, 다음과 같은 구성을 갖습니다:

* Build 1: Weight = 1

Build 2가 생성되면 별칭 1은 다음과 같이 변경됩니다:

* Build 1: Weight = 8
* Build 2: Weight = 2

모든 새 서버 요청이 Build 2에 의해 처리될 때까지 가중치를 점진적으로 변경할 수 있습니다. 이 시점에서 Build 1의 가중치는 0이고 별칭에서 제거될 수 있습니다.

별칭의 일반적인 사용 사례는 클라이언트 호환성 버전 및 게임 모드에 별칭을 연동하는 것입니다. 예를 들면 "DeathMatch client 2.2 RETAIL"입니다. 별칭을 사용하면 이 경험을 지원하는 빌드를 지속적으로 업데이트하면서 이 상위 수준 추상화를 관리할 수 있습니다. 별칭은 또한 필요한 경우 빌드를 롤백하기 쉽게 만듭니다.

### 하위 호환되지 않는 배포

이 경우 현재 게임 클라이언트가 이전 서버 빌드와 호환되지 않기 때문에 게임 클라이언트를 업데이트하는 동시에 게임 서버를 업데이트하려고 합니다. 하나의 빌드에서 다른 빌드로의 전환은 다음과 같이 수행됩니다:

이전 클라이언트는 별칭 1을 참조하며, 다음과 같습니다:

* Build 1: Weight = 1

Build 2가 생성되면 새 클라이언트는 별칭 2를 참조하며, 다음과 같습니다:

* Build 2: Weight = 1

이 시나리오에서 별칭은 빌드와 유사하게 사용되며, 다중화 기능은 사용되지 않습니다.

### 하위 호환성이 있는 블라스트 배포

이는 하위 호환성이 있는 빌드 간 업그레이드 시나리오와 유사하지만 수요 동작에서 더 갑작스러운 전환이 있습니다. 하나의 빌드에서 다른 빌드로의 전환은 다음과 같이 수행됩니다:

클라이언트는 별칭 1을 참조하며, 다음과 같습니다:

* Build 1: Weight = 1

Build 2가 생성되면 별칭 1은 다음과 같이 변경됩니다:

* Build 1: Weight = 0
* Build 2: Weight = 1

### 하위 호환성이 있는 배포 테스트

게임 서버를 업데이트하고 싶고 클라이언트 버전이 두 서버 모두와 호환되지만, 모든 플레이어에게 대규모로 배포하기 전에 두 번째 버전을 테스트하고 싶은 경우입니다. 하나의 빌드에서 다른 빌드로 테스트하고 전환하는 방법은 다음과 같습니다:

클라이언트는 별칭 1을 참조하며, 다음과 같습니다:

* Build 1: Weight = 1

Build 2가 생성되면. 테스트 클라이언트는 별칭 2를 참조하며, 다음과 같습니다:

* Build 2: Weight = 1

Build 2가 검증되면. 별칭 1은 다음과 같이 변경됩니다:

* Build 1: Weight = 8
* Build 2: Weight = 2

점진적으로 Build 2에 더 많은 가중치가 부여되고 모든 트래픽을 흡수합니다.

## 다른 빌드 및 지역으로의 대체

별칭은 여러 빌드에 걸친 대체를 허용함으로써 멀티플레이어 서버 배포를 더 탄력적으로 만들 수 있습니다. 별칭에서 서버를 요청할 때, 플레이어에게 허용 가능한 환경을 제공하는 모든 지역을 선호하는 순서대로 `PreferredRegions`에 나열하세요. PlayFab Multiplayer Servers(MPS)는 각 요청을 다음과 같이 처리합니다.

1. MPS는 빌드 가중치를 사용하여 요청에 대한 별칭 빌드의 순서를 정합니다. 가중치가 높은 빌드일수록 먼저 올 가능성이 높습니다.
2. MPS는 나열된 순서대로 지역을 살펴봅니다. 각 지역에서 해당 순서대로 모든 빌드를 시도합니다. 해당 지역에 배포되지 않은 빌드는 건너뜁니다.
3. MPS는 StandingBy 서버가 있는 첫 번째 빌드에서 서버를 할당합니다. 해당 지역에 StandingBy 서버가 있는 빌드가 없으면 MPS는 다음 지역으로 이동합니다. 어떤 지역에도 없으면 요청은 `MultiplayerServerTooManyRequests` 오류로 실패합니다.

지역 순서는 항상 빌드 가중치보다 우선합니다. 플레이어는 용량이 있는 가장 선호하는 지역에서 서버를 얻으며, 가중치는 해당 지역에서 어떤 빌드가 플레이어에게 서비스를 제공할지만 결정합니다. 가중치를 사용하여 빌드 간(예: 가상 머신(VM) 크기 간)의 비용 및 성능 선호도를 표현하세요. 더 많은 지역을 포함하는 빌드를 별칭에 추가하면 용량이 늘어나기만 합니다.

가중치가 0인 빌드는 대체용으로도 할당에 사용되지 않습니다. 빌드를 대체용으로 유지하려면 대신 0이 아닌 작은 가중치를 지정하세요. 예를 들어 주 빌드의 999에 대해 1을 지정합니다.

별칭의 빌드 중 어느 것도 요청된 지역에 배포되어 있지 않으면 요청은 `MultiplayerServerNotFound` 오류로 실패합니다. 두 오류를 모두 방지하는 방법은 [모범 사례 및 출시 검사 목록](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/best-practices.md)을 참조하세요.

예를 들어, 빌드 별칭을 대상으로 하는 할당 요청이 EastUS를 지역 #1로, West US를 지역 #2로 순위를 매긴다고 가정해 보겠습니다. 이 빌드 별칭은 Build 1과 Build 2 두 빌드에 유사한 가중치를 제공합니다.

특정 할당에 대해 Build 1이 순서상 먼저 온다고 가정합니다.

1. East US의 Build 1에 대한 할당이 시도됩니다.
2. \#1이 실패하면 East US의 Build 2에 대한 할당이 시도됩니다.
3. \#2가 실패하면 WestUS의 Build 1에 대한 할당이 시도됩니다.
4. \#3이 실패하면 WestUs의 Build 2에 대한 할당이 시도됩니다.

특히 한 빌드에서 다른 빌드로 점진적으로 업그레이드할 때, 이 대체 동작은 빌드 중 하나에 문제가 있어도 플레이어가 가장 낮은 지연 시간의 서버를 얻을 수 있도록 최적화되어 있습니다.

## PlayFab REST API로 빌드 별칭 관리

> [!NOTE]
>
> 이제 Game Manager에서 빌드 별칭을 관리할 수 있습니다. 시작하려면 [빌드 개요 페이지](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/build-overview.md)를 참조하세요.

1. API를 사용하여 빌드 별칭을 만듭니다.

   API:

   ```http theme={null}
   POST https://titleId.playfabapi.com/MultiplayerServer/CreateBuildAlias
   ```

   샘플 본문:

   ```json theme={null}
   {
       "AliasName":"TestingAlias",
       "BuildSelectionCriteria":
       [{
           "BuildWeightDistribution":{"9a8a4584-c81a-479c-9ef9-16d3743f7ca7":"1"}
       }]
   }
   ```

   샘플 응답:

   ```json theme={null}
   {
       "AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6",
       "AliasName":"TestingAlias",
       "BuildSelectionCriteria":
       [{
           "BuildWeightDistribution":{"9a8a4584-c81a-479c-9ef9-16d3743f7ca7":"1"}
       }]
   }
   ```

   **빌드 별칭 ID는 응답의 일부로 제공됩니다.**

2. 빌드 별칭의 매개 변수를 업데이트합니다.

   API:

   ```http theme={null}
   POST https://titleId.playfabapi.com/MultiplayerServer/UpdateBuildAlias
   ```

   샘플 본문:

   ```json theme={null}
   {
       "AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6",
       "AliasName":"TestingAliasRenamed",
       "BuildSelectionCriteria":
       [{
           "BuildWeightDistribution":{"9a8a4584-c81a-479c-9ef9-16d3743f7ca7":"1",
           "7ac7f347-3d61-9fe9-c974-a18c4854a8a9":"1"}
       }]
   }
   ```

   샘플 응답:

   ```json theme={null}
   {
       "AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6",
       "AliasName":"TestingAliasRenamed",
       "BuildSelectionCriteria":
       [{
           "BuildWeightDistribution":{"9a8a4584-c81a-479c-9ef9-16d3743f7ca7":"1",
           "7ac7f347-3d61-9fe9-c974-a18c4854a8a9":"1"}
       }]
   }
   ```

3. 빌드 별칭을 삭제합니다.

   API:

   ```http theme={null}
   POST https://titleId.playfabapi.com/MultiplayerServer/DeleteBuildAlias
   ```

   샘플 본문:

   ```json theme={null}
   {
       "AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6"
   }
   ```

4. 빌드 별칭을 나열합니다.

   API:

   ```http theme={null}
   GET https://titleId.playfabapi.com/MultiplayerServer/ListBuildAliases
   ```

   샘플 응답:

   ```json theme={null}
   [{
       "AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6",
       "AliasName":"TestingAliasRenamed",
       "BuildSelectionCriteria":
       [{
           "BuildWeightDistribution":{"9a8a4584-c81a-479c-9ef9-16d3743f7ca7":"1",
           "7ac7f347-3d61-9fe9-c974-a18c4854a8a9":"1"}
       }]
   }]
   ```

## 빌드 별칭을 사용하여 할당

빌드 별칭을 사용하여 할당하려면 `RequestMultiplayerServer` 호출에서 빌드 별칭 ID를 지정합니다.

API:

```http theme={null}
POST https://titleId.playfabapi.com/MultiplayerServer/RequestMultiplayerServer
```

샘플 본문:

```json theme={null}
{
    "SessionId":"6a07440c-7bcc-4e23-8b81-4934543ff966",
    "PreferredRegions":["SouthCentralUs"],
    "BuildAliasParams":
        {"AliasId":"97d2b0a5-7c04-4593-8451-66bbb97f94b6"}
}
```


## Related topics

- [빌드 개요 페이지](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/build-overview.md)
- [할당량 변경 관리](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/quota-changes.md)
- [모범 사례 및 출시 검사 목록](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/best-practices.md)
- [요약 관리](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/quota-summary.md)
- [PlayFab Multiplayer Servers와 통합](https://docs.xbox.com/ko/services/playfab/multiplayer/matchmaking/multiplayer-servers.md)