> ## 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 和多人遊戲伺服器 API 部署 PlayFab 多人遊戲伺服器 VM 組建，包括上傳資產和建立 Windows 作業系統組建。

本文概述如何在 Windows 10 開發裝置上，於 PowerShell 中使用 Windows 作業系統部署/建立 VM 組建。

使用 PowerShell/API 部署組建時，您可能會結合使用 Game Manager 和 API。因此，下方依功能列出 PowerShell/API 命令。

如果這是您第一次部署組建，建議使用 [Wrapper 範例](/zh-TW/services/playfab/multiplayer/servers/wrapper-sample)部署組建，因為它附有實際部署伺服器所需的所有資產。

<Note>
  若要使用和檢視 PlayFab 多人遊戲伺服器，您需要啟用此功能。如果您是新使用者，建議您使用 Game Manager 方法啟用此功能。如需指示，請參閱[啟用 PlayFab 伺服器功能](/zh-TW/services/playfab/multiplayer/servers/enable-playfab-multiplayer-servers)。
</Note>

## 取得您的遊戲識別碼和開發人員秘密金鑰

* 取得您的 PlayFab 遊戲識別碼
  * 在 [PlayFab.com](https://developer.playfab.com) 上登入您的開發人員帳戶
  * 在 Game Manager 中，前往 **My Studios and Titles** 頁面。尋找您的遊戲並取得 PlayFab 遊戲識別碼

* 取得遊戲的開發人員秘密金鑰
  * 在 Game Manager 中，選取您的遊戲 > 設定 (齒輪圖示)
  * 選取 **Title settings**，然後選取 **Secret Keys** 索引標籤以取得開發人員秘密金鑰

如需秘密金鑰的詳細資訊，請參閱[秘密金鑰管理](/zh-TW/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

使用您的遊戲識別碼和相關聯的開發人員金鑰執行下列命令。使用 PlayFabMultiplayerApi PowerShell 模組時，您必須在任何工作階段開始時執行此命令。

它會呼叫 [GetEntityToken](xref:titleid.playfabapi.com.authentication.authentication.getentitytoken) API 以取得 EntityToken，並將其儲存在環境變數中，供後續的 Cmdlet 使用。

```powershell theme={null}
Set-PfTitle -TitleID "mytitleID" -SecretKey "mysecretkey"
```

## 為您的遊戲啟用多人遊戲伺服器功能

執行下方的 Cmdlet 以啟用多人遊戲伺服器功能。它會呼叫[啟用多人遊戲伺服器](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 多人遊戲伺服器](/zh-TW/services/playfab/multiplayer/servers/enable-playfab-multiplayer-servers)，以新增您的付款資訊。

<a id="upload-an-asset" />

## 上傳資產

為 Windows 伺服器部署組建時，必須上傳資產。這是因為您的資產會自訂受控 Windows 容器映像。

不過，為 Linux 伺服器部署組建時，上傳資產是選擇性的，因為您可以自訂 Linux 容器映像。若要深入了解，請參閱[建立和部署 Linux 組建](/zh-TW/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 組建](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds)。

<Info>
  如果您打算利用[免費評估](/zh-TW/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>
  在開發期間，請關閉任何未使用或狀況不良的區域，以避免使用 VM 核心時數。核心時數的使用從 VM 啟動時開始，並持續到 VM 關閉為止。除非區域的目標待命伺服器數達到 0 或區域遭到刪除，否則區域中的 VM 不會自動關閉。
</Tip>

### 關閉 VM

有三種方式可以關閉 VM

1. 將區域的**目標待命**設定為 0，這只會關閉此區域的 VM。
2. 從組建中刪除特定區域。
3. 刪除整個組建，這會關閉此組建**所有區域**的 VM。

## 列出已部署的組建

若要查看遊戲的組建清單，請執行下列命令。

```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 就會配置新的伺服器。

這些伺服器來自您依區域和依組建設定、並會持續補充的待命伺服器集區。

<a id="mapping-commands" />

## 對應命令

下表顯示舊命令的新對等命令。這是一個快速對應，可協助使用過先前版本 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 部署組建](/zh-TW/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell)
* [使用 Game Manager 部署組建](/zh-TW/services/playfab/multiplayer/servers/deploy-using-game-manager)
* [建立您的第一部伺服器](/zh-TW/services/playfab/multiplayer/servers/create-your-first-server)
* [Wrapper 範例](/zh-TW/services/playfab/multiplayer/servers/wrapper-sample)
* [範例和資源](/zh-TW/services/playfab/multiplayer/servers/server-samples-resources)


## Related topics

- [逐步解說：使用 PowerShell/API 部署組建](/zh-TW/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell.md)
- [使用 Game Manager 部署組建](/zh-TW/services/playfab/multiplayer/servers/deploy-using-game-manager.md)
- [逐步解說：使用 Game Manager 部署組建](/zh-TW/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-game-manager.md)
- [部署 PlayFab 多人遊戲伺服器組建](/zh-TW/services/playfab/multiplayer/servers/deploying-playfab-multiplayer-server-builds.md)
- [管理秘密 (預覽)](/zh-TW/services/playfab/multiplayer/servers/manage-secrets.md)