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

# PowerShell/API를 사용하여 빌드 배포

> 자산 업로드 및 Windows OS 빌드 생성을 포함하여 PowerShell과 Multiplayer Servers API에서 PlayFab Multiplayer Servers VM 빌드를 배포합니다.

이 문서에서는 Windows 10 개발 장치에서 PowerShell을 사용하여 Windows OS의 VM용 빌드를 배포/생성하는 방법을 개괄적으로 설명합니다.

PowerShell/API를 사용하여 빌드를 배포할 때는 Game Manager와 API를 함께 사용하게 될 가능성이 큽니다. 따라서 PowerShell/API 명령은 아래에 기능별로 나열되어 있습니다.

빌드를 처음 배포하는 경우 실제로 서버를 배포하는 데 필요한 모든 자산을 제공하는 [Wrapper 샘플](/services/playfab/multiplayer/servers/wrapper-sample)을 사용하여 빌드를 배포하는 것을 권장합니다.

<Note>
  PlayFab Multiplayer Servers를 사용하고 보려면 이 기능을 활성화해야 합니다. 새 사용자인 경우, Game Manager 방법을 사용하여 이 기능을 활성화하는 것이 좋습니다. 지침은 [PlayFab 서버 기능 활성화](/services/playfab/multiplayer/servers/enable-playfab-multiplayer-servers)를 참조하세요.
</Note>

## 타이틀 ID 및 개발자 비밀 키 가져오기

* PlayFab 타이틀 ID 가져오기
  * [PlayFab.com](https://developer.playfab.com)에서 개발자 계정에 로그인합니다.
  * Game Manager에서 **My Studios and Titles** 페이지로 이동합니다. 게임 타이틀을 찾아 PlayFab 게임 타이틀 ID를 가져옵니다.

* 타이틀의 개발자 비밀 키 가져오기
  * Game Manager에서 타이틀 > 설정(톱니바퀴 아이콘)을 선택합니다.
  * **Title settings**를 선택한 다음 **Secret Keys** 탭을 선택하여 개발자 비밀 키를 가져옵니다.

비밀 키에 대한 자세한 내용은 [비밀 키 관리](/services/playfab/live-service-management/gamemanager/secret-key-management)를 참조하세요.

## PlayFab MultiplayerAPI PowerShell 모듈 설치

1. 관리자 권한으로 Windows PowerShell을 엽니다.

2. [PlayFab Multiplayer PowerShell](https://github.com/PlayFab/MultiplayerPowershell) 모듈을 이전에 설치한 경우, 다음 명령을 사용하여 제거합니다. 이 모듈은 이제 더 이상 사용되지 않습니다.

```powershell theme={null}
Uninstall-Package PlayFabMultiplayer
```

새 모듈로 전환하는 데 도움이 되도록 [명령 매핑](#mapping-commands)을 참조하여 새로운 동등 명령을 찾으세요. 명령과 인수 모두 다를 수 있음에 유의하세요.

3. 새 [PlayFabMultiplayer API 모듈](https://github.com/PlayFab/MpsPowershell)을 설치합니다.

각 명령에 대한 자세한 문서는 [Cmdlet 문서](https://github.com/PlayFab/MpsPowershell/tree/main/MpsPowershell/docs)를 참조하세요.

```powershell theme={null}
Install-Module -Name PlayFabMultiplayerApi
```

<Tip>
  모듈을 설치하기 전에 먼저 PowerShell에서 `Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser`를 실행하여 실행 정책을 설정해야 할 수도 있습니다. 자세한 내용은 [PowerShell 실행 정책](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)을 참조하세요.
</Tip>

4. 다음 명령을 실행하여 PlayFab Multiplayer PowerShell 모듈의 cmdlet에 대해 자세히 알아보세요. 또는 [PlayFabMultiplayerApi cmdlet 참조 문서](https://github.com/PlayFab/MpsPowershell/tree/main/MpsPowershell/docs)를 참조할 수도 있습니다.

```powershell theme={null}
Get-Command -Module PlayFabMultiplayerApi | Get-Help
```

## 타이틀용 EntityToken 획득

타이틀 ID와 연결된 개발자 키를 사용하여 다음 명령을 실행합니다. PlayFabMultiplayerApi PowerShell 모듈을 사용할 때 세션 시작 시 이 명령을 실행해야 합니다.

이는 [GetEntityToken](xref:titleid.playfabapi.com.authentication.authentication.getentitytoken) API를 호출하여 EntityToken을 획득하고 향후 cmdlet에서 사용할 수 있도록 환경 변수에 저장합니다.

```powershell theme={null}
Set-PfTitle -TitleID "mytitleID" -SecretKey "mysecretkey"
```

## 타이틀에 대해 멀티플레이어 서버 기능 활성화

아래 cmdlet을 실행하여 Multiplayer Servers 기능을 활성화합니다. 이는 [enable multiplayer servers](xref:titleid.playfabapi.com.multiplayer.multiplayerserver.enablemultiplayerserversfortitle) API를 호출합니다.

```powershell theme={null}
Enable-PfMultiplayerServer
```

`Title must have a valid payment instrument associated with it in order to enable Multiplayer Servers`라는 오류가 표시되는 경우, Game Manager를 사용하여 결제 정보를 추가하려면 [PlayFab Multiplayer Servers 활성화](/services/playfab/multiplayer/servers/enable-playfab-multiplayer-servers)를 참조하세요.

## 자산 업로드

Windows 서버용 빌드를 배포할 때는 자산 업로드가 필수입니다. 이는 자산이 관리형 Windows 컨테이너 이미지를 사용자 지정하기 때문입니다.

그러나 Linux 서버용 빌드를 배포할 때는 Linux 컨테이너 이미지를 사용자 지정할 수 있으므로 선택 사항입니다. 자세한 내용은 [Linux 빌드 생성 및 배포](/services/playfab/multiplayer/servers/deploying-linux-based-builds)를 참조하세요.

자산을 업로드하려면 이 명령을 실행합니다.

```powershell theme={null}
New-PfAsset -FilePath C:\MyAsset.zip -AssetName MyAsset.zip
```

여기서:

* **Filepath**: 업로드할 로컬 파일의 경로
* **AssetName**: 업로드할 자산의 이름

자세한 내용은 [New-PfAsset 참조 문서](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/New-PfAsset.md)를 참조하세요.

## 빌드 생성

* Windows 서버용 빌드를 생성할 때 자산을 업로드해야 합니다. 그렇지 않은 경우 [자산 업로드](#upload-an-asset)를 참조하세요.
* Linux 서버용 빌드를 생성할 때는 PlayFab 컨테이너 레지스트리에 사용자 지정 Linux 컨테이너 이미지를 업로드해야 합니다. 자세한 내용은 [Linux 빌드 생성 및 배포](/services/playfab/multiplayer/servers/deploying-linux-based-builds)를 참조하세요.

<Info>
  [무료 평가판](/services/playfab/multiplayer/servers/billing-for-thunderhead)에서 제공되는 리소스를 활용하려는 경우 \_\_$vmSize__와 __$regions\_\_에 올바른 값을 사용하세요.
</Info>

Windows 게임 서버용 빌드를 배포하는 데 도움이 되는 샘플 코드는 다음과 같습니다.

```powershell theme={null}
$vmSize = "Standard_D2as_v4"
$regions = @( @{ StandbyServers = 1; MaxServers = 1; Region = 'EastUS'; ScheduledStandbySettings = $NULL } )
$ports = @( @{ Name = 'tcp_port'; Num = 8080; Protocol = 'TCP' }, @{ Name = 'udp_port'; Num = 8081; Protocol = 'UDP' } )
$gameAssets = @( @{ FileName = 'MyAsset.zip'; MountPath = 'C:\Assets' } )

$buildResponse = New-PfBuild -BuildName ExampleBuild -ContainerFlavor ManagedWindowsServerCore -StartMultiplayerServerCommand 'C:\Assets\MyCustomServer.exe' -GameAssetReferences $gameAssets -VMSize $vmSize -MultiplayerServerCountPerVM 1 -Ports $ports -RegionConfigurations $regions

# All PlayFabMultiplayerApi cmdlets return objects, so we can pass the returned object to ConvertTo-Json for human readability.
$buildResponse | ConvertTo-Json -depth 5
```

Linux 게임 서버용 빌드를 배포하는 데 도움이 되는 샘플 코드는 다음과 같습니다.

```powershell theme={null}
$vmSize = "Standard_D2as_v4"
$ports = @( @{ Name = 'tcp_port'; Num = 8080; Protocol = 'TCP' }, @{ Name = 'udp_port'; Num = 8081; Protocol = 'UDP' } )
$regions = @( @{ 'MaxServers' = 1; 'Region' = 'AustraliaEast'; StandbyServers = 1; 'ScheduledStandbySettings' = $NULL } )
$containerImageReference = @{ ImageName = "MyLinuxContainerImage"; Tag = "0.2" }

$buildResponse = New-PfBuild -BuildName ExampleBuild -ContainerFlavor CustomLinux -ContainerImageReference $containerImageReference -VMSize $vmSize -MultiplayerServerCountPerVM 1 -Ports $ports -RegionConfigurations $regions

# All PlayFabMultiplayerApi cmdlets return objects, so we can pass the returned object to ConvertTo-Json for human readability.
$buildResponse | ConvertTo-Json -depth 5
```

<Tip>
  개발 중에는 VM 코어 사용 시간을 피하기 위해 사용하지 않거나 상태가 좋지 않은 지역을 종료하세요. 코어 사용 시간은 VM 시작 중에 시작되어 VM이 종료될 때까지 계속됩니다. 지역의 대상 대기 서버가 0에 도달하거나 지역이 삭제되지 않는 한 지역의 VM은 자동으로 종료되지 않습니다.
</Tip>

### VM 종료

VM을 종료하는 세 가지 방법이 있습니다.

1. 지역의 **target standby**를 0으로 설정하면 해당 지역의 VM만 종료됩니다.
2. 빌드에서 특정 지역을 삭제합니다.
3. 전체 빌드를 삭제하면 이 빌드의 **모든 지역**에서 VM이 종료됩니다.

## 배포된 빌드 나열

타이틀의 빌드 목록을 보려면 아래 명령을 실행합니다.

```powershell theme={null}
Get-PfBuild | ConvertTo-Json -depth 5
```

### 멀티플레이어 서버 요청

빌드를 생성하면 .exe 파일을 실행한 후 하나 이상의 서버가 생성됩니다. 이러한 서버는 이제 "대기 중" 상태가 됩니다.

이 명령을 사용하여 빌드가 실행 중인 모든 서버를 나열할 때 확인할 수 있습니다.

```powershell theme={null}
Get-PFMultiplayerServer -BuildId $buildResponse.data.BuildId -Region "EastUS"
```

일부 대기 서버가 확인되면 게임 플레이용으로 하나를 요청해 보겠습니다...

```powershell theme={null}
$sessionId = New-Guid
$serverResponse = Request-PfMultiplayerServer -BuildId $buildResponse.data.BuildId -PreferredRegions @('EastUS') -SessionId $sessionId
```

해당 호출에 대한 응답에는 클라이언트가 연결할 수 있는 IPv4 주소와 포트 번호가 포함됩니다. WindowsRunnerCSharp.exe의 경우 간단한 웹 서버를 호스팅하므로 IPv4 주소와 포트 번호로 이동하여 응답을 받을 수 있습니다.

```powershell theme={null}
curl "http://$($serverResponse.data.Ipv4Address):$($serverResponse.data.Ports[0].Num)"
```

이는 PlayFab 멀티플레이어 서버의 핵심입니다. 매치메이킹 서비스가 [RequestMultiplayerServer](xref:titleid.playfabapi.com.multiplayer.multiplayerserver.requestmultiplayerserver)를 호출한 후 3초 이내에 PlayFab이 새 서버를 할당합니다.

이러한 서버는 지역별, 빌드별로 구성된 지속적으로 다시 채워지는 대기 서버 풀에서 제공됩니다.

## 명령 매핑

아래 표는 이전 명령의 새로운 동등 명령을 보여줍니다. 이는 이전 버전의 PowerShell 모듈을 사용했으며 기존 명령을 변환해야 하는 사용자를 돕기 위한 빠른 매핑입니다.

일부 인수도 변경되었으므로 변경 사항의 전체 세부 정보를 얻으려면 각 명령의 정의를 반드시 읽으세요.

| MultiplayerPowershell 명령(이전)          | MpsPowershell API 모듈(신규)                                                                                                              |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Add-PFMultiplayerAsset                | New-PfAsset                                                                                                                           |
| Add-PFMultiplayerCertificate          | Invoke-PfUploadCertificate                                                                                                            |
| Enable-PFMultiplayerServer            | [Enable-PfMultiplayerServer](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Enable-PfMultiplayerServer.md)     |
| Get-PFMultiplayerAsset                | [Get-PfAssetSummary](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfAssetSummary.md)                     |
| Get-PFMultiplayerBuild                | [Get-PfBuild](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfBuild.md)                                   |
| Get-PFMultiplayerCertificate          | [Get-PfCertificateSummary](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfCertificateSummary.md)         |
| Get-PFMultiplayerContainerImages      | [Get-PfContainerImage](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfContainerImage.md)                 |
| Get-PFMultiplayerImageTags            | [Get-PfContainerImageTag](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfContainerImageTag.md)           |
| Get-PFMultiplayerQosServer            | [Get-PfQosServer](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfPartyQosServer.md)                      |
| Get-PFMultiplayerServer               | [Get-PfMultiplayerServer](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Get-PfMultiplayerServer.md)           |
| Get-PFTitleEntityToken                | 사용 중단됨                                                                                                                                |
| New-PFMultiplayerBuild                | [New-PfBuild](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/New-PfBuild.md)                                   |
| New-PFMultiplayerServer               | [Request-PfMultiplayerServer](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Request-PfMultiplayerServer.md)   |
| Remove-PFMultiplayerAsset             | [Remove-PfAsset](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Remove-PfAsset.md)                             |
| Remove-PFMultiplayerBuild             | [Remove-PfBuild](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Remove-PfBuild.md)                             |
| Remove-PFMultiplayerCertificate       | [Remove-PfCertificate](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Remove-PfCertificate.md)                 |
| Remove-PFMultiplayerContainerImageTag | [Invoke-PfImageUntagContainer](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Invoke-PfImageUntagContainer.md) |
| Set-PFTitle                           | [Set-PfTitle](https://github.com/PlayFab/MpsPowershell/blob/main/MpsPowershell/docs/Set-PfTitle.md)                                   |

## 관련 항목

* [연습: PowerShell/API를 사용하여 빌드 배포](/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell)
* [Game Manager를 사용하여 빌드 배포](/services/playfab/multiplayer/servers/deploy-using-game-manager)
* [첫 번째 서버 만들기](/services/playfab/multiplayer/servers/create-your-first-server)
* [Wrapper 샘플](/services/playfab/multiplayer/servers/wrapper-sample)
* [샘플 및 리소스](/services/playfab/multiplayer/servers/server-samples-resources)


## Related topics

- [연습: PowerShell/API를 사용하여 빌드 배포](/ko/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell.md)
- [PlayFab 멀티플레이어 서버 빌드 배포](/ko/services/playfab/multiplayer/servers/deploying-playfab-multiplayer-server-builds.md)
- [Linux 빌드 생성 및 배포](/ko/services/playfab/multiplayer/servers/deploying-linux-based-builds.md)
- [Wrapper 샘플](/ko/services/playfab/multiplayer/servers/wrapper-sample.md)
- [Windows Runner 샘플](/ko/services/playfab/multiplayer/servers/windows-runner-sample.md)