다음을 통해 공유

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

  • 아티클

이 문서에서는 Windows 10 개발 장치의 PowerShell에서 Windows OS를 사용하여 VM용 빌드를 배포/만드는 방법을 간략하게 설명합니다.

PowerShell/API를 사용하여 빌드를 배포할 때 게임 관리자와 API를 함께 사용하는 경우가 많습니다. 따라서 PowerShell/API 명령은 아래 기능별로 나열됩니다.

빌드를 처음 배포하는 경우 실제로 서버를 배포하는 데 필요한 모든 자산과 함께 제공되므로 래퍼 샘플을 사용하여 빌드를 배포하는 것이 좋습니다.

참고 항목

PlayFab 멀티 플레이어 서버를 사용 및 확인하려면 이 기능을 사용으로 설정해야 합니다. 신규 사용자인 경우 게임 관리자 방법을 사용하여 이 기능을 사용하는 것이 좋습니다. 자세한 내용은 PlayFab 서버 기능 사용을 참조하세요.

타이틀 ID 및 개발자 비밀 키 받기

  • PlayFab 타이틀 ID 받기

    • PlayFab.com에서 개발자 계정으로 로그인합니다.
    • 게임 관리자에서 내 스튜디오 및 타이틀 페이지로 이동합니다. 게임 타이틀을 찾고 PlayFab 게임 타이틀 ID를 받습니다.

  • 타이틀의 개발자 비밀 키 받기

    • 게임 관리자에서 타이틀 > 설정(톱니바퀴 아이콘)을 선택합니다.
    • 타이틀 설정을 선택한 다음 비밀 키 탭을 선택하여 개발자 비밀 키를 받습니다

비밀 키에 대한 자세한 내용은 비밀 키 관리를 참조하세요.

PlayFab MultiplayerAPI PowerShell 모듈 설치

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

  2. 이전에 PlayFab 멀티 플레이어 PowerShell 모듈을 설치한 경우, 다음 명령을 사용하여 제거합니다. 이 모듈은 이제 사용되지 않습니다.

Uninstall-Package PlayFabMultiplayer

새 모듈로 전환하는 데 도움이 되도록 매핑 명령을 참조하여 새 해당 명령을 찾으세요. 명령과 인수가 모두 다를 수 있다는 점에 유의하세요.

  1. 새 PlayFabMultiplayer API 모듈 설치

각 명령에 대한 자세한 설명서는Cmdlet 설명서를 참조하세요.

Install-Module -Name PlayFabMultiplayerApi

팁

모듈을 설치하기 전에 먼저 PowerShell에서 Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser을(를) 실행하여 실행 정책을 설정해야 할 수 있습니다. 자세한 내용은 PowerShell 실행 정책을 참조하세요.

  1. 다음 명령을 실행하여 PlayFab 멀티 플레이어 PowerShell 모듈에서 cmdlet에 대해 자세히 알아봅니다. 또는 PlayFabMultiplayerApi cmdlet 참조 설명서를 참조할 수 있습니다.
Get-Command -Module PlayFabMultiplayerApi | Get-Help

타이틀용 EntityToken 얻기

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

GetEntityToken API를 호출하여 EntityToken을 얻고 향후 cmdlet에서 사용할 환경 변수에 저장합니다.

Set-PfTitle -TitleID "mytitleID" -SecretKey "mysecretkey"

타이틀에 멀티 플레이어 서버 기능 사용

아래에서 이 cmdlet을 실행하여 멀티 플레이어 기능을 사용하도록 합니다. 이 작업은 멀티 플레이어 서버를 사용하는 API를 호출합니다.

Enable-PfMultiplayerServer

Title must have a valid payment instrument associated with it in order to enable Multiplayer Servers라는 오류가 표시되면 게임 관리자를 통해 PlayFab 멀티 플레이어 서버 사용을 참고하여 결제 정보를 추가합니다.

자산 업로드

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

그러나 Linux 컨테이너 이미지를 사용자 지정할 수 있으므로 Linux 서버용 빌드를 배포할 때는 선택 사항입니다. 자세한 내용은 Linux 컨테이너 이미지 만들기를 참조하세요.

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

New-PfAsset -FilePath C:\MyAsset.zip -AssetName MyAsset.zip

설명:

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

자세한 내용은 New-PfAsset 참조 설명서를 참조하세요.

빌드 만들기

  • Windows 서버용 빌드를 만들 때 자산을 업로드해야 합니다. 그렇지 않은 경우 자산 업로드를 참조하세요.
  • Linux 서버용 빌드를 만들 때 사용자 지정 Linux 컨테이너 이미지를 PlayFab 컨테이너 레지스트리에 업로드해야 합니다. 자세한 내용은 Linux 서버 배포를 참조하세요.

Important

무료 평가용으로 제공되는 리소스를 활용하려면 $vmSize 및 $regions에 올바른 값을 사용해야 합니다.

아래 샘플 코드는 Windows 게임 서버용 빌드를 배포하는 데 도움이 됩니다.

$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 게임 서버용 빌드를 배포하는 데 도움이 됩니다.

$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

팁

개발 중에는 VM 코어 시간 사용을 방지하기 위해 사용되지 않거나 비정상적인 지역을 차단합니다. 코어 시간 사용은 VM 시작 중에 시작되어 VM이 종료될 때까지 계속됩니다. 지역의 대상 대기 서버가 0에 도달하거나 지역이 삭제되지 않는 한 지역의 VM은 자동으로 종료되지 않습니다.

VM 종료

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

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

배포된 빌드 나열

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

Get-PfBuild | ConvertTo-Json -depth 5

멀티 플레이어 서버 요청

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

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

Get-PFMultiplayerServer -BuildId $buildResponse.data.BuildId -Region "EastUS"

일부 대기 서버를 확인하고 나면, 게임 플레이를 하기 위해 한 서버에 요청을 합니다...

$sessionId = New-Guid
$serverResponse = Request-PfMultiplayerServer -BuildId $buildResponse.data.BuildId -PreferredRegions @('EastUS') -SessionId $sessionId

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

curl "http://$($serverResponse.data.Ipv4Address):$($serverResponse.data.Ports[0].Num)"

이것이 PlayFab 멀티 플레이어 서버의 핵심입니다. RequestMultiplayerServer를 호출하는 매치 메이킹 서비스를 요청하면 3초 이내에 PlayFab에서 새 서버를 할당합니다.

이러한 서버는 지역별 및 빌드별로 구성한 대기 서버 풀에서 지속적으로 다시 채워집니다.

매핑 명령

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

일부 인수도 변경되었으므로 각 명령의 정의를 확인하여 변경 내용에 대한 전체 세부 정보를 얻습니다.

MultiplayerPowershell 명령(이전) MpsPowershell API 모듈(신규)
Add-PFMultiplayerAsset New-PfAsset
Add-PFMultiplayerCertificate Invoke-PfUploadCertificate
Enable-PFMultiplayerServer Enable-PfMultiplayerServer
Get-PFMultiplayerAsset Get-PfAssetSummary
Get-PFMultiplayerBuild Get-PfBuild
Get-PFMultiplayerCertificate Get-PfCertificateSummary
Get-PFMultiplayerContainerImages Get-PfContainerImage
Get-PFMultiplayerImageTags Get-PfContainerImageTag
Get-PFMultiplayerQosServer Get-PfQosServer
Get-PFMultiplayerServer Get-PfMultiplayerServer
Get-PFTitleEntityToken 사용되지 않음
New-PFMultiplayerBuild New-PfBuild
New-PFMultiplayerServer Request-PfMultiplayerServer
Remove-PFMultiplayerAsset Remove-PfAsset
Remove-PFMultiplayerBuild Remove-PfBuild
Remove-PFMultiplayerCertificate Remove-PfCertificate
Remove-PFMultiplayerContainerImageTag Invoke-PfImageUntagContainer
Set-PFTitle Set-PfTitle

참고 항목