使用 PowerShell/API 部署构建

本文概述了如何在 Windows 10 开发设备上使用 PowerShell 为使用 Windows OS 的虚拟机部署/创建构建。使用 PowerShell/API 部署构建时，您很可能会结合使用 Game Manager 和 API。因此，下面按功能列出了 PowerShell/API 命令。如果这是您首次部署构建，我们建议您使用 Wrapper 示例部署构建，因为它随附了实际部署服务器所需的所有资产。

要使用和查看 PlayFab Multiplayer Servers，您需要启用该功能。如果您是新用户，我们建议您使用 Game Manager 方法启用此功能。有关说明，请参阅启用 PlayFab 服务器功能。

获取标题 ID 和开发人员密钥

获取 PlayFab 标题 ID
- 登录 PlayFab.com 上的开发者账户
- 在 Game Manager 中，转到 My Studios and Titles 页面。找到您的游戏标题并获取 PlayFab 游戏标题 ID
获取标题的开发人员密钥
- 在 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

使用您的标题 ID 和关联的开发人员密钥运行以下命令。使用 PlayFabMultiplayerApi PowerShell 模块时，必须在任何会话开始时运行此命令。它会调用 GetEntityToken API 以获取 EntityToken 并将其存储在环境变量中，以供将来的 cmdlet 使用。

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

为您的标题启用多人游戏服务器功能

运行下面的 cmdlet 以启用 Multiplayer Servers 功能。它会调用启用多人游戏服务器 API。

Enable-PfMultiplayerServer

如果您收到错误消息 Title must have a valid payment instrument associated with it in order to enable Multiplayer Servers，请参阅使用 Game Manager 启用 PlayFab Multiplayer Servers 添加您的付款信息。

上传资产

在部署 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

在开发期间，请关闭任何未使用或运行状况不佳的区域，以避免虚拟机核心小时使用。核心小时使用从虚拟机启动开始，直到虚拟机关闭为止。除非区域的目标备用服务器达到 0 或删除区域，否则区域中的虚拟机不会自动关闭。

关闭虚拟机

有三种方法可以关闭虚拟机

将某个区域的目标备用设为 0，这只会关闭此区域的虚拟机。
从构建中删除特定区域。
删除整个构建，这将关闭该构建所有区域的虚拟机。

列出已部署的构建

要查看您的标题的构建列表，请运行以下命令。

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

获取标题 ID 和开发人员密钥

安装 PlayFab MultiplayerAPI PowerShell 模块

为您的标题获取 EntityToken

为您的标题启用多人游戏服务器功能

上传资产

创建构建

关闭虚拟机

列出已部署的构建

请求多人游戏服务器

命令映射

另请参阅

​获取标题 ID 和开发人员密钥

​安装 PlayFab MultiplayerAPI PowerShell 模块

​为您的标题获取 EntityToken

​为您的标题启用多人游戏服务器功能

​上传资产

​创建构建

​关闭虚拟机

​列出已部署的构建

​请求多人游戏服务器

​命令映射

​另请参阅

获取标题 ID 和开发人员密钥

安装 PlayFab MultiplayerAPI PowerShell 模块

为您的标题获取 EntityToken

为您的标题启用多人游戏服务器功能

上传资产

创建构建

关闭虚拟机

列出已部署的构建

请求多人游戏服务器

命令映射

另请参阅