Passer au contenu principal
CloudScript est l’une des fonctionnalités les plus polyvalentes de PlayFab. Il permet au code client de demander l’exécution de tout type de fonctionnalité personnalisée côté serveur que vous pouvez implémenter, et il peut être utilisé avec pratiquement n’importe quoi. En plus des demandes d’exécution explicites provenant du code client ou serveur, CloudScript peut être exécuté en réponse à des événements PlayStream (en créant une règle) ou dans le cadre d’une tâche planifiée.
CloudScript avec Azure Functions améliore ce qui faisait la force de CloudScript, avec davantage de langages pris en charge et de meilleurs flux de débogage.
Ce tutoriel traite de l’écriture de votre code CloudScript. Consultez le démarrage rapide de CloudScript pour obtenir de l’aide sur le chargement de vos fichiers CloudScript dans votre titre.
Ce tutoriel présente des exemples de code Unity, mais CloudScript fonctionne de manière similaire pour tous les SDK.
Prérequis de ce tutoriel :

Prise en main : helloWorld

Notre exemple helloWorld fonctionne sur un tout nouveau titre, sans aucune modification dans Game Manager. Le fichier CloudScript par défaut d’un nouveau titre comprend un gestionnaire appelé helloWorld. Il utilise quelques fonctionnalités de base : paramètres d’entrée, journalisation, currentPlayerId et paramètres de retour. L’exemple suivant présente le code par défaut de la fonction helloWorld (sans les commentaires).

Analyse du code

L’objet handlers est prédéfini dans l’environnement PlayFab CloudScript. Vous devez ajouter toutes vos fonctions CloudScript à cet objet.
  • helloWorld est une fonction mise à la disposition de votre titre et des SDK, car elle est définie dans l’objet handlers.
  • args est un objet arbitraire qui provient de l’appelant. Il est analysé à partir de JSON et peut contenir n’importe quelles données, dans n’importe quel format.
Consultez FunctionParameter dans la section suivante.
Vous ne devez accorder aucune confiance à cet objet. Un client piraté ou un utilisateur malveillant peut fournir n’importe quelle information ici, dans n’importe quel format.
  • Context est un paramètre avancé. Dans cet exemple, il est null. Ce paramètre est contrôlé par le serveur et sûr.
  • currentPlayerId est une variable globale définie sur le PlayFabId du joueur qui effectue cet appel. Ce paramètre est contrôlé par le serveur et sûr. Remarque : lors de l’utilisation de l’API ExecuteEntityCloudScript, ce paramètre est null, sauf si l’entité possède un MasterPlayerID dans sa chaîne d’entités.
  • log.info : log est un objet global. Il sert principalement à déboguer votre CloudScript. L’objet log expose les méthodes suivantes : info, debug et error. D’autres détails sont fournis plus loin dans ce tutoriel.
  • return : tout objet que vous renvoyez est sérialisé en JSON et renvoyé à l’appelant. Vous pouvez renvoyer n’importe quel objet sérialisable en JSON, avec les données de votre choix.
Il est de votre responsabilité de ne pas renvoyer de données secrètes à vos clients via votre CloudScript. Un client piraté ou un utilisateur malveillant peut examiner les données renvoyées, même si vous ne les affichez pas à l’utilisateur pendant le jeu normal.

Exécution de fonctions CloudScript depuis un client de jeu Unity

L’appel d’une fonction CloudScript depuis un client est simple. Vous devez d’abord créer un ExecuteCloudScriptRequest et définir la propriété ActionId sur le nom de la fonction CloudScript à exécuter (dans ce cas, helloWorld), puis envoyer l’objet à PlayFab via notre API.
Vous ne pouvez appeler que les méthodes CloudScript attachées à l’objet JavaScript handlers.
Pour exécuter des méthodes CloudScript, vous aurez besoin des lignes de code suivantes dans votre client.

Analyse du code

ExecuteCloudScriptRequest est le type de requête de tout appel à PlayFabClientAPI.ExecuteCloudScript.
  • ExecuteCloudScriptRequest.FunctionName est une chaîne. Sa valeur doit correspondre au nom de la fonction définie dans CloudScript. Dans ce cas, helloWorld.
  • ExecuteCloudScriptRequest.FunctionParameter peut être n’importe quel objet sérialisable en JSON. Il devient le premier paramètre args de la fonction helloWorld (reportez-vous à args dans la section précédente).
  • ExecuteCloudScriptRequest.GeneratePlayStreamEvent est facultatif. S’il est défini sur true, un événement est publié dans PlayStream ; vous pouvez le consulter dans Game Manager ou l’utiliser pour d’autres déclencheurs PlayStream.
Selon le langage, la dernière partie de la ligne ExecuteCloudScript consiste à envoyer la requête au serveur PlayFab CloudScript, et à gérer le résultat et les erreurs de manière propre au langage. Par exemple, dans Unity, JavaScript ou AS3, la gestion des erreurs et des résultats s’effectue à l’aide de fonctions de rappel. Voici un exemple de méthodes de gestion des erreurs.

Vue d’ensemble intermédiaire : variables globales et arguments avancés

CloudScript est un ensemble de fonctions JavaScript compilées avec V8 et hébergées sur les serveurs de PlayFab. Il a accès à toutes les API serveur répertoriées dans la documentation de référence des API PlayFab, ainsi qu’à un journaliseur, à l’ID PlayFab du joueur qui effectue la requête CloudScript et à toutes les informations incluses dans la requête, le tout sous forme d’objets prédéfinis. Les fonctions CloudScript sont elles-mêmes des propriétés d’un objet global handlers. Le tableau suivant présente la liste complète de ces variables prédéfinies. En outre, deux paramètres sont transmis à toutes les fonctions de gestionnaire ; ils sont détaillés ci-dessous. Les fonctions CloudScript peuvent être appelées via l’API ExecuteCloudScript ou par une action d’événement PlayStream prédéfinie. Les détails complets de la réponse à ExecuteCloudScript sont disponibles dans ExecuteCloudScriptResult.

Niveau intermédiaire : FunctionParameter et args

Dans la section précédente, nous avons décrit comment renseigner request.FunctionParameter et consulter ces informations dans le paramètre args. Le démarrage rapide de CloudScript montre comment charger un nouveau CloudScript. En combinant les deux, nous pouvons fournir un autre exemple de transmission d’arguments du client vers CloudScript. Reprenez l’exemple précédent et modifiez le code CloudScript et votre code client comme indiqué ci-dessous.
Après ces modifications, vous pouvez facilement envoyer et recevoir des données entre CloudScript et vos clients.
Il est important de souligner que toutes les données provenant de vos clients sont susceptibles d’être piratées et exploitées.
Vous devez toujours valider les paramètres d’entrée avant de mettre à jour votre back-end. Le processus de validation des paramètres d’entrée varie d’un titre à l’autre, mais la validation la plus élémentaire consiste à vérifier que les entrées se situent dans des plages et des périodes acceptables.

Niveau intermédiaire : appel des API serveur

Comme indiqué précédemment, dans les méthodes CloudScript, vous avez accès à l’ensemble complet des appels de l’API Server. Votre code cloud peut ainsi faire office de serveur dédié. Tâches serveur courantes :
  • Mettre à jour les statistiques et les données des joueurs.
  • Octroyer des articles et des monnaies.
  • Générer aléatoirement des données de jeu.
  • Calculer de manière sécurisée les résultats des combats, et plus encore…
Consultez les API Server répertoriées dans notre documentation de référence des API PlayFab pour connaître les paramètres requis et les structures d’objets. L’exemple suivant est extrait d’un gestionnaire CloudScript potentiel.

Niveau avancé : action d’événement PlayStream

Une fonction CloudScript peut être configurée pour s’exécuter en réponse à un événement PlayStream.
  1. Dans n’importe quel navigateur :
    • Accédez à PlayFab Game Manager.
    • Trouvez votre Title.
    • Sous Build dans la barre latérale, accédez à l’onglet Automation.
    • Accédez à l’onglet Rules.
La page ressemblera à l’exemple ci-dessous. Game Manager : PlayStream, actions d'événement
  1. Utilisez le bouton New Rule pour créer une règle.
    • Donnez un nom à la nouvelle Rule.
    • Sélectionnez un Event type qui servira de déclencheur pour une condition ou une action.
    • Pour que la Rule déclenche une fonction CloudScript, ajoutez une Action à l’aide du bouton de cette section.
    • Sélectionnez ensuite l’option dans le menu déroulant Type.
    • Sélectionnez la fonction helloWorld dans le menu déroulant Cloud Script Function.
    • Sélectionnez le bouton Save action.
    Game Manager : PlayStream, enregistrer l'action
  2. Cette Rule est maintenant configurée pour se déclencher sur tout événement du type sélectionné. Pour la tester :
    • Cochez la case Publish results as PlayStream Event.
    • Enregistrez l’Action.
    • Déclenchez ensuite un événement.
    • Dans le PlayStream Monitor, un nouvel événement correspondant à l’exécution du CloudScript doit apparaître, contenant les informations appropriées.
    • Pour plus d’informations sur la vérification d’un événement PlayStream dans le débogueur, consultez la section suivante Niveau avancé : débogage de CloudScript.
Les actions d’événement ne peuvent utiliser que la révision en production lors de l’appel de fonctions CloudScript. Si vous ne trouvez pas la fonction helloWorld dans la liste déroulante, c’en est très probablement la raison.

Niveau avancé : débogage de CloudScript

Le débogage est beaucoup plus simple avec CloudScript avec Azure Functions. Découvrez comment utiliser le débogage local de CloudScript avec Azure Functions.

Journalisation

L’un des outils les plus importants pour déboguer du code est la journalisation. Notre CloudScript fournit un utilitaire à cet effet. Il prend la forme de l’objet log, qui peut journaliser n’importe quel message à l’aide des méthodes Info, Debug et Error. En outre, l’objet HTTP journalise toutes les erreurs rencontrées lors des requêtes si le paramètre logRequestAndResponse est défini. Si la configuration de ces journaux est simple, y accéder demande un peu de finesse. Voici un exemple de fonction CloudScript qui utilise les 4 types de journaux.
Pour exécuter cet exemple, ajoutez cette fonction à votre révision en production avant de continuer. La fonction logTest peut être appelée à l’aide d’ExecuteCloudScript, comme indiqué ci-dessous.
La définition de GeneratePlayStreamEvent fait en sorte que l’appel de la fonction CloudScript génère un événement PlayStream, qui inclut le contenu de la réponse. Pour trouver le contenu d’un événement PlayStream :
  • Accédez à la page d’accueil de Game Manager de votre Title ou à son onglet PlayStream.
  • Le PlayStream Debugger affiche les événements au fur et à mesure de leur arrivée.
  • Lorsqu’ils arrivent, sélectionnez la petite icône bleue Info dans le coin supérieur droit de l’événement, comme illustré ci-dessous. Game Manager : PlayStream, débogueur
Cette sélection affiche le JSON brut de l’événement, détaillé pour chaque événement ici. Un exemple de ce JSON est présenté ci-dessous.
  • Si nous ajoutons le MonoBehavior LogScript à la scène, l’exécution du jeu produit ceci dans PlayStream. Game Manager : PlayStream, journal d'événements JSON
Le résultat d’un appel ExecuteCloudScript comprend un champ appelé Logs, qui est une liste d’objets de journal générés par la fonction CloudScript. Vous pouvez voir les trois appels de journalisation, ainsi que le journal de la requête HTTP non valide. Contrairement aux appels de journalisation, le journal de la requête HTTP utilise également le champ Data. Ce champ est un objet JavaScript qui peut contenir toute information pertinente pour l’instruction de journalisation. Les appels à log peuvent également utiliser ce champ, via le deuxième paramètre, comme indiqué ci-dessous.
Ces appels renseignent tous le champ Data du résultat avec leur deuxième paramètre. Comme les journaux sont inclus dans le résultat, le code côté client peut réagir aux instructions de journalisation. L’erreur de la fonction logTest est forcée, mais le code client peut être adapté pour y réagir.
Si ce code est exécuté, la sortie doit indiquer la présence de l’erreur. Des réponses réalistes à une erreur pourraient consister à l’afficher dans l’interface utilisateur ou à enregistrer une valeur dans un fichier journal.

Niveau avancé : erreurs

En développement, les erreurs CloudScript ne sont souvent pas déclenchées manuellement, contrairement au cas de log.error. Heureusement, la réponse à ExecuteCloudScript contient un ExecuteCloudScriptResult qui comprend un champ ScriptExecutionError. En adaptant le dernier exemple de la section sur la journalisation, nous pourrions l’utiliser comme indiqué ci-dessous.
Si une erreur se produisait, ce code l’afficherait dans le journal.
Dernière modification le 8 octobre 2026