Freigeben über

Bereitstellen von Builds mithilfe von PowerShell/API

  • Artikel

Dieser Artikel bietet eine Übersicht über das Bereitstellen/Erstellen von Builds für VMs mit dem Windows-Betriebssystem in PowerShell auf einem Windows 10 Entwicklungsgerät.

Wenn Sie einen Build mithilfe von PowerShell/API bereitstellen, verwenden Sie wahrscheinlich eine Kombination aus Game Manager und den APIs. Daher sind die PowerShell-/API-Befehle nach Funktionen unten aufgeführt.

Wenn Sie zum ersten Mal einen Build bereitstellen, empfiehlt es sich, einen Build mithilfe des Wrapper-Beispiels bereitzustellen, da er mit allen Ressourcen zusammenkommt, die Sie zum tatsächlichen Bereitstellen von Servern benötigen.

Notiz

Um die PlayFab Multiplayer-Server verwenden und anzeigen zu können, müssen Sie das Feature aktivieren. Wenn Sie ein neuer Benutzer sind, empfehlen wir Ihnen, die Game Manager-Methode zu verwenden, um dieses Feature zu aktivieren. Anweisungen finden Sie unter Aktivieren des PlayFab Server-Features.

Abrufen Der Titel-ID und des geheimen Entwicklerschlüssels

  • Abrufen Ihrer PlayFab-Titel-ID

    • Melden Sie sich am PlayFab.com bei Ihrem Entwicklerkonto an .
    • Wechseln Sie im Game Manager zur Seite Meine Studios und Titel . Suchen Sie nach Ihrem Spieltitel, und rufen Sie die Titel-ID des PlayFab-Spiels ab.

  • Abrufen des geheimen Entwicklerschlüssels für den Titel

    • Wählen Sie in Game Manager Ihre Titeleinstellungen > (Zahnradsymbol) aus.
    • Wählen Sie Titeleinstellungen und dann die Registerkarte Geheime Schlüssel aus, um den geheimen Entwicklerschlüssel abzurufen.

Weitere Informationen zu geheimen Schlüsseln finden Sie unter Verwaltung geheimer Schlüssel.

Installieren des PowerShell-Moduls PlayFab MultiplayerAPI

  1. Öffnen von Windows PowerShell als Administrator

  2. Wenn Sie das PowerShell-Modul PlayFab Multiplayer bereits installiert haben, deinstallieren Sie es mit dem folgenden Befehl. Dieses Modul ist jetzt veraltet.

Uninstall-Package PlayFabMultiplayer

Informationen zum Umstieg auf das neue Modul finden Sie unter Zuordnungsbefehle , um die neuen entsprechenden Befehle zu finden. Beachten Sie, dass sowohl die Befehle als auch die Argumente unterschiedlich sein können.

  1. Installieren des neuen PlayFabMultiplayer-API-Moduls

Eine ausführliche Dokumentation zu den einzelnen Befehlen finden Sie in der Cmdlet-Dokumentation.

Install-Module -Name PlayFabMultiplayerApi

Tipp

Vor der Installation des Moduls müssen Sie möglicherweise Ihre Ausführungsrichtlinie festlegen, indem Sie zuerst in PowerShell ausführen Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser . Weitere Informationen finden Sie unter PowerShell-Ausführungsrichtlinien.

  1. Erfahren Sie mehr über die Cmdlets im PlayFab Multiplayer PowerShell-Modul, indem Sie den folgenden Befehl ausführen. Sie können auch die Referenzdokumentation zum Cmdlet PlayFabMultiplayerApi lesen.
Get-Command -Module PlayFabMultiplayerApi | Get-Help

Abrufen eines EntityTokens für Ihren Titel

Führen Sie den folgenden Befehl mit Ihrer Titel-ID und dem zugehörigen Entwicklerschlüssel aus. Sie müssen diesen Befehl zu Beginn einer beliebigen Sitzung ausführen, wenn Sie das PowerShell-Modul PlayFabMultiplayerApi verwenden.

Es ruft die GetEntityToken-API auf, um ein EntityToken abzurufen, und speichert es in einer Umgebungsvariable für die Verwendung in zukünftigen Cmdlets.

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

Aktivieren des Features "Multiplayerserver" für Ihren Titel

Führen Sie das folgende Cmdlet aus, um die Features von Multiplayerservern zu aktivieren. Sie ruft die API zum Aktivieren von Multiplayerservern auf.

Enable-PfMultiplayerServer

Wenn Sie eine Fehlermeldung mit dem Hinweis Title must have a valid payment instrument associated with it in order to enable Multiplayer Serverserhalten, lesen Sie Aktivieren von PlayFab Multiplayer-Servern mithilfe von Game Manager, um Ihre Zahlungsinformationen hinzuzufügen.

Hochladen eines Medienobjekts

Das Hochladen einer Ressource ist obligatorisch, wenn Sie einen Build für Windows-Server bereitstellen. Dies liegt daran, dass Ihre Ressourcen das verwaltete Windows-Containerimage anpassen.

Dies ist jedoch optional, wenn Sie einen Build für Linux-Server bereitstellen, da Sie das Linux-Containerimage anpassen können. Weitere Informationen finden Sie unter Erstellen von Linux-Containerimages.

Führen Sie diesen Befehl aus, um ein Medienobjekt hochzuladen.

New-PfAsset -FilePath C:\MyAsset.zip -AssetName MyAsset.zip

Dabei gilt:

  • Filepath: Pfad zur lokalen Datei, die Sie hochladen möchten
  • AssetName: Name des hochzuladenden Medienobjekts

Weitere Informationen finden Sie in der Referenzdokumentation zu New-PfAsset.

Erstellen eines Builds

  • Beim Erstellen eines Builds für Windows-Server müssen Sie ein Medienobjekt hochgeladen haben. Wenn nicht, lesen Sie Hochladen eines Medienobjekts.
  • Beim Erstellen eines Builds für Linux-Server müssen Sie Ihr benutzerdefiniertes Linux-Containerimage in Ihre PlayFab-Containerregistrierung hochgeladen haben. Weitere Informationen finden Sie unter Bereitstellen von Linux-Servern.

Wichtig

Stellen Sie sicher, dass Sie die richtigen Werte für $vmSize und $regions verwenden, wenn Sie beabsichtigen, die Zur kostenlosen Auswertung angebotenen Ressourcen zu nutzen.

Beispielcode unten zum Bereitstellen von Builds für Windows-Spieleserver.

$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

Nachfolgend finden Sie Beispielcode zum Bereitstellen von Builds für Linux-Spieleserver.

$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

Tipp

Schließen Sie während der Entwicklung alle nicht verwendeten oder fehlerhaften Regionen, um die Nutzung von VM-Kernstunden zu vermeiden. Die Nutzung der Kernstunde beginnt beim Starten des virtuellen Computers und wird fortgesetzt, bis die VM heruntergefahren wird. VMs in einer Region werden nicht automatisch heruntergefahren, es sei denn, die Ziel-Standbyserver der Region erreichen 0 oder eine Region wird gelöscht.

Herunterfahren von VMs

Es gibt drei Möglichkeiten zum Herunterfahren von VMs

  1. Legen Sie den Ziel-Standbymodus einer Region auf 0 fest. Dadurch werden VMs nur für diese Region heruntergefahren.
  2. Löschen einer bestimmten Region aus einem Build.
  3. Löschen Sie den gesamten Build. Dadurch werden VMs in allen Regionen für diesen Build heruntergefahren.

Auflisten bereitgestellter Builds

Führen Sie die folgenden Befehle aus, um eine Liste der Builds für Ihren Titel anzuzeigen.

Get-PfBuild | ConvertTo-Json -depth 5

Anfordern eines Multiplayerservers

Nachdem Sie einen Build erstellt haben, wird nach dem Ausführen Ihrer .exe-Datei mindestens ein Server erstellt. Diese Server sind jetzt "bereit".

Sie können sie sehen, wenn Sie mit diesem Befehl alle Server auflisten, auf denen unser Build ausgeführt wird.

Get-PFMultiplayerServer -BuildId $buildResponse.data.BuildId -Region "EastUS"

Sobald wir einige Standbyserver sehen, fordern wir einen für das Gameplay an...

$sessionId = New-Guid
$serverResponse = Request-PfMultiplayerServer -BuildId $buildResponse.data.BuildId -PreferredRegions @('EastUS') -SessionId $sessionId

Die Antwort auf diesen Anruf enthält eine IPv4-Adresse und eine Portnummer, mit der Clients eine Verbindung herstellen können. Für WindowsRunnerCSharp.exe hostet es einen einfachen Webserver, sodass Sie zur IPv4-Adresse und Portnummer navigieren können, um eine Antwort zu erhalten:

curl "http://$($serverResponse.data.Ipv4Address):$($serverResponse.data.Ports[0].Num)"

Dies ist der Kern von PlayFab-Multiplayerservern: Innerhalb von 3 Sekunden nach aufruft Ihr Matchmaking-Dienst RequestMultiplayerServer, ordnet PlayFab einen neuen Server zu.

Diese Server stammen aus kontinuierlich aufgefüllten, ständigen Serverpools, die Sie pro Region und pro Build konfigurieren.

Zuordnungsbefehle

Die folgende Tabelle zeigt das neue Äquivalent der alten Befehle. Dies ist eine schnelle Zuordnung, die denjenigen hilft, die die vorherige Version des PowerShell-Moduls verwendet haben und ihre vorhandenen Befehle konvertieren müssen.

Lesen Sie unbedingt die Definition der einzelnen Befehle, um vollständige Details zur Änderung zu erhalten, da sich auch einige der Argumente geändert haben.

MultiplayerPowershell-Befehl (alt) MpsPowershell-API-Modul (neu)
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 veraltet
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

Weitere Informationen