> ## 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 多人遊戲伺服器，包括組建、伺服器、資產、容器映像和配額。

`playfab mps` 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。

`playfab mps` 管理 PlayFab 多人遊戲伺服器 (MPS)：組建及其別名和區域、伺服器、資產、憑證、秘密、容器映像、配額，以及虛擬機器 (VM)。它涵蓋的作業與 PlayFab 的 [MpsPowershell](https://github.com/PlayFab/MpsPowershell) 模組相同；與其 `Set-PfTitle` 對等的命令是 `xbox context set playfab-title-id <id>`。請參閱[內容](https://docs.xbox.com/zh-TW/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-TW/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-TW/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-TW/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-TW/services/playfab/multiplayer/servers/index.md)
- [使用 PlayFab 多人遊戲伺服器裝載多人遊戲](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/using-playfab-servers-to-host-games.md)
- [多人遊戲伺服器比較](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/server-comparison.md)
- [PlayFab 多人遊戲伺服器術語](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/server-terms.md)
- [多人遊戲伺服器的生命週期](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/multiplayer-game-server-lifecycle.md)
