使用 PowerShell/API 部署組建

本文概述如何在 Windows 10 開發裝置上，於 PowerShell 中使用 Windows 作業系統部署/建立 VM 組建。使用 PowerShell/API 部署組建時，您可能會結合使用 Game Manager 和 API。因此，下方依功能列出 PowerShell/API 命令。如果這是您第一次部署組建，建議使用 Wrapper 範例部署組建，因為它附有實際部署伺服器所需的所有資產。

若要使用和檢視 PlayFab 多人遊戲伺服器，您需要啟用此功能。如果您是新使用者，建議您使用 Game Manager 方法啟用此功能。如需指示，請參閱啟用 PlayFab 伺服器功能。

取得您的遊戲識別碼和開發人員秘密金鑰

取得您的 PlayFab 遊戲識別碼
- 在 PlayFab.com 上登入您的開發人員帳戶
- 在 Game Manager 中，前往 My Studios and Titles 頁面。尋找您的遊戲並取得 PlayFab 遊戲識別碼
取得遊戲的開發人員秘密金鑰
- 在 Game Manager 中，選取您的遊戲 > 設定 (齒輪圖示)
- 選取 Title settings，然後選取 Secret Keys 索引標籤以取得開發人員秘密金鑰

如需秘密金鑰的詳細資訊，請參閱秘密金鑰管理。

安裝 PlayFab MultiplayerAPI PowerShell 模組

以系統管理員身分開啟 Windows PowerShell
如果您先前已安裝 PlayFab Multiplayer PowerShell 模組，請使用下列命令將其解除安裝。此模組現已淘汰。

Uninstall-Package PlayFabMultiplayer

為了協助您轉換到新模組，請參閱對應命令以找出新的對等命令。請注意，命令和引數都可能不同。

安裝新的 PlayFabMultiplayer API 模組

如需每個命令的詳細文件，請參閱 Cmdlet 文件。

Install-Module -Name PlayFabMultiplayerApi

安裝模組之前，您可能需要先在 PowerShell 中執行 Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser 來設定執行原則。若要深入了解，請參閱 PowerShell 執行原則。

執行下列命令，深入了解 PlayFab Multiplayer PowerShell 模組中的 Cmdlet。或者，您可以參閱 PlayFabMultiplayerApi Cmdlet 參考文件。

Get-Command -Module PlayFabMultiplayerApi | Get-Help

取得遊戲的 EntityToken

使用您的遊戲識別碼和相關聯的開發人員金鑰執行下列命令。使用 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 錯誤，請參閱使用 Game Manager 啟用 PlayFab 多人遊戲伺服器，以新增您的付款資訊。

上傳資產

為 Windows 伺服器部署組建時，必須上傳資產。這是因為您的資產會自訂受控 Windows 容器映像。不過，為 Linux 伺服器部署組建時，上傳資產是選擇性的，因為您可以自訂 Linux 容器映像。若要深入了解，請參閱建立和部署 Linux 組建。執行此命令以上傳資產。

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

其中：

Filepath：您要上傳之本機檔案的路徑
AssetName：要上傳之資產的名稱

如需詳細資料，請參閱 New-PfAsset 參考文件。

建立組建

為 Windows 伺服器建立組建時，您需要已上傳資產。如果尚未上傳，請參閱上傳資產。
為 Linux 伺服器建立組建時，您需要已將自訂 Linux 容器映像上傳至您的 PlayFab 容器登錄。若要深入了解，請參閱建立和部署 Linux 組建。

如果您打算利用免費評估所提供的資源，請確定您為 $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

將區域的目標待命設定為 0，這只會關閉此區域的 VM。
從組建中刪除特定區域。
刪除整個組建，這會關閉此組建所有區域的 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 會裝載一個簡單的 Web 伺服器，因此您可以瀏覽至該 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

XBOX Services

PlayFab

取得您的遊戲識別碼和開發人員秘密金鑰

安裝 PlayFab MultiplayerAPI PowerShell 模組

取得遊戲的 EntityToken

為您的遊戲啟用多人遊戲伺服器功能

上傳資產

建立組建

關閉 VM

列出已部署的組建

要求多人遊戲伺服器

對應命令

另請參閱

​取得您的遊戲識別碼和開發人員秘密金鑰

​安裝 PlayFab MultiplayerAPI PowerShell 模組

​取得遊戲的 EntityToken

​為您的遊戲啟用多人遊戲伺服器功能

​上傳資產

​建立組建

​關閉 VM

​列出已部署的組建

​要求多人遊戲伺服器

​對應命令

​另請參閱

取得您的遊戲識別碼和開發人員秘密金鑰

安裝 PlayFab MultiplayerAPI PowerShell 模組

取得遊戲的 EntityToken

為您的遊戲啟用多人遊戲伺服器功能

上傳資產

建立組建

關閉 VM

列出已部署的組建

要求多人遊戲伺服器

對應命令

另請參閱