使用 PowerShell/API 部署内部版本

本文概述了如何在 Windows 10 开发设备上的 PowerShell 中使用 Windows OS 为虚拟机部署/创建内部版本。

使用 PowerShell/API 部署内部版本时,可能会结合使用 Game Manager 和 API。 因此,以下功能将列出 PowerShell/API 命令。

如果是首次部署内部版本,建议使用包装器示例进行部署,因为它们随附了实际部署服务器所需的全部资产。

注意

若要使用和查看 PlayFab 多人游戏服务器,你需要启用该功能。 如果你是新用户,我们建议使用 Game Manager 方法启用此功能。 有关说明,请参阅启用 PlayFab 服务器功能

获取游戏 ID 和开发者密钥

  • 获取 PlayFab 游戏 ID

    • PlayFab.com 上登录到你的开发者帐户
    • 在 Game Manager 中,转至“我的工作室和游戏”页面。 查找游戏并获取 PlayFab 游戏 ID
  • 获取游戏的开发者密钥

    • 在 Game Manager 中,选择“游戏”>“设置”(齿轮图标)
    • 选择“游戏设置”,然后选择“密钥”选项卡以获取开发者密钥

有关开发者密钥的详细信息,请参阅密钥管理

安装 PlayFab 多人游戏 API PowerShell 模块

  1. 以管理员身份打开 Windows PowerShell

  2. 如果以前已安装了 PlayFab 多人游戏 PowerShell 模块,请通过以下命令将其卸载。 此模块现已弃用。

Uninstall-Package PlayFabMultiplayer

为帮助转换到新模块,请参阅映射命令以查找新的等效命令。 请注意,命令和参数可能有所不同。

  1. 安装新的 PlayFab 多人游戏 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 的错误消息,请参阅如何使用 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

  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,它托管一个简单的 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

另请参阅