Déployer des builds à l'aide de PowerShell/de l'API

Cet article explique comment déployer ou créer des builds de machines virtuelles utilisant le système d’exploitation Windows dans PowerShell, sur un appareil de développement Windows 10. Lorsque vous déployez une build à l’aide de PowerShell/de l’API, vous utiliserez probablement à la fois Game Manager et les API. C’est pourquoi les commandes PowerShell/API sont répertoriées ci-dessous par fonctionnalité. S’il s’agit de votre premier déploiement de build, nous vous recommandons de déployer une build à l’aide de l’exemple Wrapper, car il fournit toutes les ressources nécessaires pour déployer réellement des serveurs.

Pour utiliser et afficher PlayFab Multiplayer Servers, vous devez activer la fonctionnalité. Si vous êtes un nouvel utilisateur, nous vous recommandons d’utiliser la méthode Game Manager pour activer cette fonctionnalité. Pour obtenir des instructions, consultez Activer la fonctionnalité PlayFab Server.

Obtenir l’ID de votre titre et la clé secrète de développeur

Obtenez l’ID de votre titre PlayFab
- Connectez-vous à votre compte de développeur sur PlayFab.com
- Dans Game Manager, accédez à la page My Studios and Titles. Recherchez votre titre de jeu et récupérez l’ID de titre de jeu PlayFab
Obtenez la clé secrète de développeur du titre
- Dans Game Manager, sélectionnez votre titre > paramètres (icône d’engrenage)
- Sélectionnez Title settings, puis l’onglet Secret Keys pour obtenir la clé secrète de développeur

Pour plus d’informations sur les clés secrètes, consultez Gestion des clés secrètes.

Installer le module PowerShell PlayFab MultiplayerAPI

Ouvrez Windows PowerShell en tant qu’administrateur
Si vous avez déjà installé le module PlayFab Multiplayer PowerShell, désinstallez-le à l’aide de la commande suivante. Ce module est désormais déprécié.

Uninstall-Package PlayFabMultiplayer

Pour vous aider à passer au nouveau module, consultez Mappage des commandes afin de trouver les nouvelles commandes équivalentes. Sachez que les commandes et les arguments peuvent être différents.

Installez le nouveau module PlayFabMultiplayer API

Pour obtenir une documentation détaillée sur chaque commande, consultez la documentation des cmdlets.

Install-Module -Name PlayFabMultiplayerApi

Avant d’installer le module, vous devrez peut-être définir votre stratégie d’exécution en exécutant d’abord Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser dans PowerShell. Pour en savoir plus, consultez Stratégies d’exécution PowerShell.

Pour en savoir plus sur les cmdlets du module PlayFab Multiplayer PowerShell, exécutez la commande suivante. Vous pouvez également consulter la documentation de référence des cmdlets PlayFabMultiplayerApi.

Get-Command -Module PlayFabMultiplayerApi | Get-Help

Obtenir un EntityToken pour votre titre

Exécutez la commande suivante avec l’ID de votre titre et la clé de développeur associée. Vous devez exécuter cette commande au début de chaque session lorsque vous utilisez le module PowerShell PlayFabMultiplayerApi. Elle appelle l’API GetEntityToken pour obtenir un EntityToken et l’stocke dans une variable d’environnement en vue de son utilisation par les cmdlets ultérieures.

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

Activer la fonctionnalité Multiplayer Servers pour votre titre

Exécutez la cmdlet ci-dessous pour activer les fonctionnalités Multiplayer Servers. Elle appelle l’API enable multiplayer servers.

Enable-PfMultiplayerServer

Si vous recevez une erreur indiquant Title must have a valid payment instrument associated with it in order to enable Multiplayer Servers, consultez Activer PlayFab Multiplayer Servers à l’aide de Game Manager pour ajouter vos informations de paiement.

Téléverser un actif

Le téléversement d’un actif est obligatoire lorsque vous déployez une build pour des serveurs Windows, car vos actifs personnalisent l’image de conteneur Windows managée. Il est toutefois facultatif lors du déploiement d’une build pour des serveurs Linux, puisque vous pouvez personnaliser l’image de conteneur Linux. Pour en savoir plus, consultez Créer et déployer des builds Linux. Exécutez cette commande pour téléverser un actif.

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

où :

Filepath : chemin du fichier local à téléverser
AssetName : nom de l’actif à téléverser

Pour plus de détails, consultez la documentation de référence de New-PfAsset.

Créer une build

Pour créer une build pour des serveurs Windows, vous devez avoir téléversé un actif. Si ce n’est pas le cas, consultez Téléverser un actif.
Pour créer une build pour des serveurs Linux, vous devez avoir téléversé votre image de conteneur Linux personnalisée dans votre registre de conteneurs PlayFab. Pour en savoir plus, consultez Créer et déployer des builds Linux.

Assurez-vous d’utiliser les bonnes valeurs pour $vmSize__ et __$ regions si vous prévoyez de tirer parti des ressources offertes pour l’évaluation gratuite.

Exemple de code ci-dessous pour vous aider à déployer des builds pour des serveurs de jeu Windows.

$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

Exemple de code ci-dessous pour vous aider à déployer des builds pour des serveurs de jeu Linux.

$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

Pendant le développement, désactivez les régions inutilisées ou défectueuses afin d’éviter de consommer des heures de cœur de machine virtuelle. La consommation d’heures de cœur commence au démarrage de la machine virtuelle et se poursuit jusqu’à son arrêt. Les machines virtuelles d’une région ne s’arrêtent pas automatiquement, sauf si le nombre cible de serveurs en attente de la région atteint 0 ou si la région est supprimée.

Arrêt des machines virtuelles

Il existe trois façons d’arrêter des machines virtuelles

Définissez le nombre cible de serveurs en attente d’une région sur 0 : cela arrête les machines virtuelles de cette région uniquement.
Supprimez une région spécifique d’une build.
Supprimez la build entière : cela arrête les machines virtuelles de toutes les régions de cette build.

Répertorier les builds déployées

Pour afficher la liste des builds de votre titre, exécutez les commandes ci-dessous.

Get-PfBuild | ConvertTo-Json -depth 5

Demander un serveur multijoueur

Une fois que vous avez créé une build, un ou plusieurs serveurs sont créés après l’exécution de votre fichier .exe. Ces serveurs sont désormais « en attente » (standing by). Vous pouvez les voir en répertoriant tous les serveurs qui exécutent notre build à l’aide de cette commande.

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

Une fois que des serveurs en attente apparaissent, demandons-en un pour jouer…

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

La réponse à cet appel comprend une adresse IPv4 et un numéro de port auxquels les clients peuvent se connecter. WindowsRunnerCSharp.exe héberge un serveur web simple; vous pouvez donc accéder à l’adresse IPv4 et au numéro de port pour obtenir une réponse :

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

C’est le cœur de PlayFab Multiplayer Servers : dans les 3 secondes qui suivent l’appel de RequestMultiplayerServer par votre service de matchmaking, PlayFab alloue un nouveau serveur. Ces serveurs proviennent de pools de serveurs en attente, réalimentés en continu, que vous configurez par région et par build.

Mappage des commandes

Le tableau ci-dessous présente les nouveaux équivalents des anciennes commandes. Il s’agit d’un mappage rapide destiné à aider ceux qui ont utilisé la version précédente du module PowerShell et doivent convertir leurs commandes existantes. Assurez-vous de lire la définition de chaque commande pour connaître tous les détails de la modification, car certains arguments ont également changé.

Commande MultiplayerPowershell (ancienne)	Module d’API MpsPowershell (nouveau)
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	déprécié
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

XBOX Services

PlayFab

Obtenir l’ID de votre titre et la clé secrète de développeur

Installer le module PowerShell PlayFab MultiplayerAPI

Obtenir un EntityToken pour votre titre

Activer la fonctionnalité Multiplayer Servers pour votre titre

Téléverser un actif

Créer une build

Arrêt des machines virtuelles

Répertorier les builds déployées

Demander un serveur multijoueur

Mappage des commandes

Voir aussi

​Obtenir l’ID de votre titre et la clé secrète de développeur

​Installer le module PowerShell PlayFab MultiplayerAPI

​Obtenir un EntityToken pour votre titre

​Activer la fonctionnalité Multiplayer Servers pour votre titre

​Téléverser un actif

​Créer une build

​Arrêt des machines virtuelles

​Répertorier les builds déployées

​Demander un serveur multijoueur

​Mappage des commandes

​Voir aussi

Obtenir l’ID de votre titre et la clé secrète de développeur

Installer le module PowerShell PlayFab MultiplayerAPI

Obtenir un EntityToken pour votre titre

Activer la fonctionnalité Multiplayer Servers pour votre titre

Téléverser un actif

Créer une build

Arrêt des machines virtuelles

Répertorier les builds déployées

Demander un serveur multijoueur

Mappage des commandes

Voir aussi