> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 多人游戏服务器

> 管理 PlayFab Multiplayer Servers,包括生成、服务器、资产、容器映像和配额。

`playfab mps` 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。

`playfab mps` 管理 PlayFab Multiplayer Servers (MPS):生成及其别名和区域、服务器、资产、证书、机密、容器映像、配额和虚拟机 (VM)。它涵盖与 PlayFab 的 [MpsPowershell](https://github.com/PlayFab/MpsPowershell) 模块相同的操作;与其 `Set-PfTitle` 等效的是 `xbox context set playfab-title-id <id>`。请参阅[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。

```bash theme={null}
xbox --playfab-title-id ABC123 --output json-compact --data-only playfab mps build list
```

## 命令树

每个命令都在 `xbox playfab mps` 下运行。

| 命令 | PlayFab API 路径 | 说明 |
| - | - | - |
| `title enable` | `/MultiplayerServer/EnableMultiplayerServersForTitle` | 为游戏启用 MPS。 |
| `title status` | `/MultiplayerServer/GetTitleEnabledForMultiplayerServersStatus` | 检查是否已为游戏启用 MPS。 |
| `build get` | `/MultiplayerServer/GetBuild` | 获取生成。 |
| `build list` | `/MultiplayerServer/ListBuildSummariesV2` | 列出一页生成。 |
| `build create` | 取决于 `--type` | 创建生成。请参阅 [`mps build create`](#mps-build-create)。 |
| `build update-name` | `/MultiplayerServer/UpdateBuildName` | 重命名生成。 |
| `build delete` | `/MultiplayerServer/DeleteBuild` | 删除生成。 |
| `build alias get` | `/MultiplayerServer/GetBuildAlias` | 获取生成别名。 |
| `build alias list` | `/MultiplayerServer/ListBuildAliases` | 列出一页生成别名。 |
| `build alias create` | `/MultiplayerServer/CreateBuildAlias` | 创建生成别名。 |
| `build alias update` | `/MultiplayerServer/UpdateBuildAlias` | 更新生成别名。 |
| `build alias delete` | `/MultiplayerServer/DeleteBuildAlias` | 删除生成别名。 |
| `build region update` | `/MultiplayerServer/UpdateBuildRegion` | 更新生成的某个区域。 |
| `build region update-all` | `/MultiplayerServer/UpdateBuildRegions` | 更新生成的所有区域。 |
| `build region delete` | `/MultiplayerServer/DeleteBuildRegion` | 从生成中删除区域。 |
| `server get` | `/MultiplayerServer/GetMultiplayerServerDetails` | 获取服务器会话的详细信息。 |
| `server list` | `/MultiplayerServer/ListMultiplayerServers` | 列出某个区域中生成的一页服务器会话。 |
| `server list-archived` | `/MultiplayerServer/ListArchivedMultiplayerServers` | 列出生成的一页已存档服务器会话。 |
| `server request` | `/MultiplayerServer/RequestMultiplayerServer` | 请求服务器会话。 |
| `server shutdown` | `/MultiplayerServer/ShutdownMultiplayerServer` | 关闭服务器会话。 |
| `server get-logs` | `/MultiplayerServer/GetMultiplayerServerLogs` | 获取已终止服务器的日志。 |
| `server get-session-logs` | `/MultiplayerServer/GetMultiplayerSessionLogsBySessionId` | 按会话 ID 获取已终止服务器的日志。 |
| `asset list` | `/MultiplayerServer/ListAssetSummaries` | 列出一页资产。 |
| `asset upload` | `/MultiplayerServer/GetAssetUploadUrl` | 将本地文件作为资产上传。请参阅 [`mps asset upload`](#mps-asset-upload)。 |
| `asset delete` | `/MultiplayerServer/DeleteAsset` | 删除资产。 |
| `asset get-upload-url` | `/MultiplayerServer/GetAssetUploadUrl` | 获取用于上传资产的 URL。 |
| `asset get-download-url` | `/MultiplayerServer/GetAssetDownloadUrl` | 获取用于下载资产的 URL。 |
| `certificate list` | `/MultiplayerServer/ListCertificateSummaries` | 列出一页证书。 |
| `certificate upload` | `/MultiplayerServer/UploadCertificate` | 上传证书。请参阅 [`mps certificate upload`](#mps-certificate-upload-and-mps-secret-upload)。 |
| `certificate delete` | `/MultiplayerServer/DeleteCertificate` | 删除证书。 |
| `secret list` | `/MultiplayerServer/ListSecretSummaries` | 列出一页机密。 |
| `secret upload` | `/MultiplayerServer/UploadSecret` | 上传机密。请参阅 [`mps secret upload`](#mps-certificate-upload-and-mps-secret-upload)。 |
| `secret delete` | `/MultiplayerServer/DeleteSecret` | 删除机密。 |
| `container-image list` | `/MultiplayerServer/ListContainerImages` | 列出一页自定义容器映像。 |
| `container-image list-tags` | `/MultiplayerServer/ListContainerImageTags` | 列出容器映像的一页标记。 |
| `container-image untag` | `/MultiplayerServer/UntagContainerImage` | 从容器映像中删除标记。 |
| `container-image repository delete` | `/MultiplayerServer/DeleteContainerImageRepository` | 删除容器映像存储库。 |
| `container-registry credentials get` | `/MultiplayerServer/GetContainerRegistryCredentials` | 获取容器注册表的凭据。 |
| `container-registry credentials rollover` | `/MultiplayerServer/RolloverContainerRegistryCredentials` | 替换容器注册表的凭据。 |
| `quota get` | `/MultiplayerServer/GetTitleMultiplayerServersQuotas` | 获取游戏的 MPS 配额。 |
| `quota change get` | `/MultiplayerServer/GetTitleMultiplayerServersQuotaChange` | 获取配额更改请求。 |
| `quota change list` | `/MultiplayerServer/ListTitleMultiplayerServersQuotaChanges` | 列出所有配额更改请求。 |
| `quota change create` | `/MultiplayerServer/CreateTitleMultiplayerServersQuotaChange` | 请求配额更改。 |
| `qos-server list` | `/MultiplayerServer/ListQosServersForTitle` | 列出游戏的 QoS 服务器。 |
| `party-qos-server list` | `/MultiplayerServer/ListPartyQosServers` | 列出 PlayFab Party QoS 服务器。 |
| `virtual-machine list` | `/MultiplayerServer/ListVirtualMachineSummaries` | 列出一页 VM。 |
| `remote-user create` | `/MultiplayerServer/CreateRemoteUser` | 创建用于登录生成的 VM 的远程用户。 |
| `remote-user delete` | `/MultiplayerServer/DeleteRemoteUser` | 删除远程用户。 |
| `remote-login get-endpoint` | `/MultiplayerServer/GetRemoteLoginEndpoint` | 获取托管生成的 VM 的远程登录终结点。 |
| `party request` | `/Party/RequestPartyService` | 请求 PlayFab Party 会话。 |

## 请求正文

大多数 MPS 命令会发送操作的 JSON 请求对象,与 [`playfab api`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api) 类似:

| 选项 | 说明 |
| - | - |
| `--body` | 内联的 JSON 请求正文。如果两个正文选项都未传递,则默认为 `{}`。 |
| `--body-file` | 包含 JSON 请求正文的文件的路径,或使用 `-` 从 stdin 读取。 |

`--body` 和 `--body-file` 不能结合使用。`certificate upload` 和 `secret upload` 仅接受 `--body-file`,`asset upload` 两者都不接受;请参阅它们各自的部分。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps build get --body '{ "BuildId": "11111111-2222-3333-4444-555555555555" }'
xbox --playfab-title-id ABC123 --data-only playfab mps server list --body '{ "BuildId": "11111111-2222-3333-4444-555555555555", "Region": "EastUs" }'
```

## 破坏性命令

以下命令在终端中会先进行询问,在其他环境中则需要 `--confirm` (`--yes`, `-y`):`build delete`、`build alias delete`、`build region delete`、`server shutdown`、`asset delete`、`certificate delete`、`secret delete`、`container-image repository delete` 和 `remote-user delete`。使用 `--body-file -` 时,即使在终端中也需要 `--confirm`。其他进行更改的 MPS 命令会直接运行而不询问。请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps build delete --body '{ "BuildId": "11111111-2222-3333-4444-555555555555" }' --confirm
```

## 分页

以下列表命令每次调用返回一页结果:

* `build list`、`build alias list`
* `server list`、`server list-archived`
* `asset list`、`certificate list`、`secret list`
* `container-image list`、`container-image list-tags`
* `virtual-machine list`

当存在更多结果时,会设置响应的 `SkipToken`。若要获取下一页,请将带有该值的 `"SkipToken"` 添加到请求正文中,保留其他字段,并重复此操作,直到返回的 `SkipToken` 为 `null`。在请求正文中设置 `"PageSize"` 可更改每页包含的结果数。

获取第一页生成:

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only playfab mps build list --body '{ "PageSize": 50 }'
```

如果其 `SkipToken` 不为 `null`,请传递该令牌以获取下一页:

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only playfab mps build list --body '{ "PageSize": 50, "SkipToken": "<SkipToken from the previous page>" }'
```

表格输出没有 `SkipToken` 列,因此当存在更多结果时,表格之后会在 stderr 上显示一条通知,其中包含要发送的令牌。

## 表格输出

以下表格中的命令接受 `--output table`;其他 MPS 命令不接受。请参阅[表格输出](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md#table-output)。

| 命令 | 列 |
| - | - |
| `build list` | `BUILD ID`、`NAME`、`CREATED` |
| `build alias list` | `ALIAS ID`、`NAME` |
| `server list` | `SERVER ID`、`REGION`、`STATE`、`SESSION ID` |
| `server list-archived` | `SERVER ID`、`REGION`、`STATE`、`LAST TRANSITION` |
| `asset list` | `FILE NAME` |
| `certificate list` | `NAME`、`THUMBPRINT` |
| `secret list` | `NAME`、`VERSION`、`EXPIRES` |
| `container-image list` | `IMAGE` |
| `container-image list-tags` | `TAG` |
| `quota change list` | `REQUEST ID`、`DESCRIPTION`、`PENDING`、`APPROVED` |
| `qos-server list` | `REGION`、`SERVER URL` |
| `party-qos-server list` | `REGION`、`SERVER URL` |
| `virtual-machine list` | `VM ID`、`STATE`、`HEALTH` |

返回单条记录的命令将其显示为一行:

| 命令 | 列 |
| - | - |
| `title status` | `STATUS` |
| `build get` | `BUILD ID`、`NAME`、`STATUS`、`OS`、`VM SIZE` |
| `build alias get` | `ALIAS ID`、`NAME` |
| `server get` | `SERVER ID`、`STATE`、`REGION`、`SESSION ID`、`IPV4 ADDRESS` |
| `asset get-upload-url` | `FILE NAME`、`UPLOAD URL`(已编辑) |
| `asset get-download-url` | `FILE NAME`、`DOWNLOAD URL`(已编辑) |
| `container-registry credentials get` | `DNS NAME`、`USERNAME`、`PASSWORD`(已编辑) |
| `quota change get` | `REQUEST ID`、`DESCRIPTION`、`PENDING`、`APPROVED` |
| `remote-login get-endpoint` | `IPV4 ADDRESS`、`PORT` |

已编辑的列会打印 `********`,因为该值是凭据。JSON 输出会返回实际值。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps build list --output table
```

```text theme={null}
BUILD ID                              NAME            CREATED
------------------------------------  --------------  ------------------------
11111111-2222-3333-4444-555555555555  combat-sandbox  2026-04-26T22:15:16.7Z
22222222-3333-4444-5555-666666666666  lobby-service   2026-06-23T22:00:37.702Z
```

## `mps build create`

`build create` 需要 `--type`(它选择要调用的 PlayFab API),并像其他 MPS 命令一样接受请求正文:

| `--type` 值 | PlayFab API 路径 |
| - | - |
| `managed` | `/MultiplayerServer/CreateBuildWithManagedContainer` |
| `custom` | `/MultiplayerServer/CreateBuildWithCustomContainer` |
| `process` | `/MultiplayerServer/CreateBuildWithProcessBasedServer` |

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps build create --type managed --body-file managed-build.json
```

## `mps certificate upload` 和 `mps secret upload`

`certificate upload` 和 `secret upload` 仅通过 `--body-file <path>`(或用于 stdin 的 `--body-file -`)接受请求正文,因为正文包含 PFX 密码或机密值。它们拒绝 `--body`,因为该选项会将值留在 shell 历史记录和进程列表中。两者都不接受 `--output table`。

| 命令 | 请求字段 |
| - | - |
| `certificate upload` | `GameCertificate`(`Name`、`Base64EncodedValue`,以及 PFX 有密码时的 `Password`)、`ForceUpdate`、`CustomTags` |
| `secret upload` | `GameSecret`(`Name`、`Value`、`ExpirationDate`)、`ForceUpdate`、`CustomTags` |

`ForceUpdate` 会替换已使用该名称的证书或机密。请勿将正文文件纳入源代码管理,并在上传后将其删除。

`certificate.json` 包含 Base64 编码的 PFX 及其密码:

```json theme={null}
{
  "GameCertificate": {
    "Name": "nod-arena-tls",
    "Base64EncodedValue": "<Base64-encoded PFX>",
    "Password": "<PFX password>"
  }
}
```

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps certificate upload --body-file certificate.json
```

若要在不将机密写入其他文件的情况下构建正文,请将其通过管道传递给 `--body-file -`。此处,`jq` 从 `api-key.txt` 而不是从其自身的参数中读取该值,因此该值不会出现在进程列表中:

```bash theme={null}
jq -n --rawfile value api-key.txt \
  '{GameSecret: {Name: "nod-arena-api-key", Value: ($value | rtrimstr("\n"))}}' \
  | xbox --playfab-title-id ABC123 playfab mps secret upload --body-file -
```

## `mps asset upload`

`asset upload` 将本地文件作为多人游戏服务器资产上传。它接受选项而不是请求正文,并以 JSON 形式写入资产名称和上传状态。

| 选项 | 必需 | 说明 |
| - | - | - |
| `--file` | 是 | 要上传的本地文件的路径。 |
| `--asset-name` | 是 | 要在 PlayFab 中创建的资产的名称。 |
| `--buffer-size` | 否 | 上传块大小(以字节为单位)。默认为 `4194304` (4 MiB)。 |

```bash theme={null}
xbox --playfab-title-id ABC123 playfab mps asset upload --file gameserver.zip --asset-name gameserver.zip
```


## Related topics

- [定价计量](https://docs.xbox.com/zh-CN/services/playfab/pricing/meters/meters.md)
- [关闭多人游戏服务器](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/multiplayer/multiplayer-server/shutdown-multiplayer-server.md)
- [列出多人游戏服务器](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/multiplayer/multiplayer-server/list-multiplayer-servers.md)
- [多人游戏服务器的生命周期](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/servers/multiplayer-game-server-lifecycle.md)
- [请求多人游戏服务器](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/multiplayer/multiplayer-server/request-multiplayer-server.md)
