> ## 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 部署构建

> 通过 PowerShell 和 Multiplayer Servers API 部署 PlayFab Multiplayer Servers 虚拟机构建，包括上传资产和创建 Windows OS 构建。

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

使用 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 功能。它会调用[启用多人游戏服务器](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 服务器创建构建时，您需要将自定义 Linux 容器映像上传到您的 PlayFab 容器注册表。要了解更多信息，请参阅[创建和部署 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>
  在开发期间，请关闭任何未使用或运行状况不佳的区域，以避免虚拟机核心小时使用。核心小时使用从虚拟机启动开始，直到虚拟机关闭为止。除非区域的目标备用服务器达到 0 或删除区域，否则区域中的虚拟机不会自动关闭。
</Tip>

### 关闭虚拟机

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

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

## 列出已部署的构建

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

```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，它承载一个简单的 Web 服务器，因此您可以浏览到 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 部署构建](/zh-CN/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell.md)
- [部署 PlayFab 多人游戏服务器构建](/zh-CN/services/playfab/multiplayer/servers/deploying-playfab-multiplayer-server-builds.md)
- [管理机密(预览版)](/zh-CN/services/playfab/multiplayer/servers/manage-secrets.md)
- [Wrapper 示例](/zh-CN/services/playfab/multiplayer/servers/wrapper-sample.md)
- [Windows Runner 示例](/zh-CN/services/playfab/multiplayer/servers/windows-runner-sample.md)