> ## 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.
# Écriture de CloudScript personnalisé
> Écrivez des fonctions JavaScript PlayFab CloudScript personnalisées pouvant être appelées depuis des clients Unity, des règles PlayStream et des tâches planifiées, avec des exemples helloWorld.
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](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart) 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](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) 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 :
* [Environnement **Unity** configuré avec le **SDK Unity** PlayFab](/fr/services/playfab/sdks/unity3d/quickstart)
* L'ID de titre est défini dans l'objet `PlayFabSharedSettings`.
* Le projet peut connecter un utilisateur avec succès.
## 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).
```javascript theme={null}
// CloudScript (JavaScript)
handlers.helloWorld = function (args, context) {
var message = "Hello " + currentPlayerId + "!";
log.info(message);
var inputValue = null;
if (args && args.hasOwnProperty("inputValue"))
inputValue = args.inputValue;
log.debug("helloWorld:", { input: inputValue });
return { messageValue: message };
}
```
### 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.
```csharp theme={null}
// Build the request object and access the API
private static void StartCloudHelloWorld()
{
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest()
{
FunctionName = "helloWorld", // Arbitrary function name (must exist in your uploaded cloud.js file)
FunctionParameter = new { inputValue = "YOUR NAME" }, // The parameter provided to your function
GeneratePlayStreamEvent = true, // Optional - Shows this event in PlayStream
}, OnCloudHelloWorld, OnErrorShared);
}
// OnCloudHelloWorld defined in the next code block
```
### Analyse du code
[ExecuteCloudScriptRequest](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptrequest) est le type de requête de tout appel à [PlayFabClientAPI.ExecuteCloudScript](xref:titleid.playfabapi.com.client.server-sidecloudscript.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.
```csharp theme={null}
private static void OnCloudHelloWorld(ExecuteCloudScriptResult result) {
// CloudScript returns arbitrary results, so you have to evaluate them one step and one parameter at a time
Debug.Log(JsonWrapper.SerializeObject(result.FunctionResult));
JsonObject jsonResult = (JsonObject)result.FunctionResult;
object messageValue;
jsonResult.TryGetValue("messageValue", out messageValue); // note how "messageValue" directly corresponds to the JSON values set in CloudScript
Debug.Log((string)messageValue);
}
private static void OnErrorShared(PlayFabError error)
{
Debug.Log(error.GenerateErrorReport());
}
```
## 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](/fr/services/playfab/api-references), 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.
| Nom | Utilisation |
| :- | :- |
| **server** | A accès à tous les appels d'API côté serveur répertoriés dans la [documentation de référence des API PlayFab](/fr/services/playfab/api-references). Ils peuvent être appelés (de manière synchrone) comme suit : `var result = server.AuthenticateUserTicket(request);` |
| **http** | Effectue des requêtes HTTP synchrones, comme suit : `http.request(url, method, content, contentType, headers, logRequestAndResponse)`. L'objet `headers` contient des propriétés correspondant aux différents en-têtes et à leurs valeurs. `logRequestAndResponse` est une valeur booléenne qui détermine si le titre doit journaliser les erreurs de la requête dans la réponse. |
| **log** | Crée des instructions de journalisation et les ajoute à la réponse. Les journaux ont trois niveaux : `log.info()`, `log.debug()` et `log.error()`. Les trois niveaux acceptent une chaîne de message, ainsi qu'un objet facultatif contenant des données supplémentaires à inclure dans le journal. Par exemple, `log.info('hello!', { time: new Date() });` |
| **currentPlayerId** | ID PlayFab du joueur qui a déclenché l'appel CloudScript. |
| **handlers** | Objet global qui contient toutes les fonctions CloudScript de votre titre. Des fonctions peuvent être ajoutées ou appelées via cet objet. Par exemple, `handlers.pop = function() {};`, `handlers.pop();`. |
| **script** | Objet global qui contient `Revision` et `titleId`. `Revision` représente le **numéro de révision** du CloudScript en cours d'exécution, et `titleId` représente l'ID du titre actuel. |
En outre, deux paramètres sont transmis à toutes les fonctions de gestionnaire ; ils sont détaillés ci-dessous.
| Nom | Utilisation |
| :- | :- |
| **args** | Premier paramètre d'une fonction de gestionnaire. Représentation objet du champ `FunctionParameter` d'une requête `ExecuteCloudscript`. |
| **context** | Deuxième paramètre d'une fonction de gestionnaire. Informations supplémentaires sur la requête lorsqu'elle est déclenchée par une action d'événement PlayStream, y compris les [données de l'événement](/fr/services/playfab/api-references/events) qui a déclenché l'action (context.playStreamEvent) et les [données de profil](xref:titleid.playfabapi.com.client.accountmanagement.getplayerprofile#playerprofilemodel) du joueur associé (context.playerProfile) |
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](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#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](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart) 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.
```javascript theme={null}
handlers.helloWorld = function (args) {
// ALWAYS validate args parameter passed in from clients (Better than we do here)
var message = "Hello " + args.name + "!"; // Utilize the name parameter sent from client
log.info(message);
return { messageValue: message };
}
```
```csharp theme={null}
// Build the request object and access the API
private static void StartCloudHelloWorld()
{
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest()
{
FunctionName = "helloWorld", // Arbitrary function name (must exist in your uploaded cloud.js file)
FunctionParameter = new { name = "YOUR NAME" }, // The parameter provided to your function
GeneratePlayStreamEvent = true, // Optional - Shows this event in PlayStream
}, OnCloudHelloWorld, OnErrorShared);
}
private static void OnCloudHelloWorld(ExecuteCloudScriptResult result) {
// CloudScript returns arbitrary results, so you have to evaluate them one step and one parameter at a time
Debug.Log(JsonWrapper.SerializeObject(result.FunctionResult));
JsonObject jsonResult = (JsonObject)result.FunctionResult;
object messageValue;
jsonResult.TryGetValue("messageValue", out messageValue); // note how "messageValue" directly corresponds to the JSON values set in CloudScript
Debug.Log((string)messageValue);
}
private static void OnErrorShared(PlayFabError error)
{
Debug.Log(error.GenerateErrorReport());
}
```
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](/fr/services/playfab/api-references) pour connaître les paramètres requis et les structures d'objets.
L'exemple suivant est extrait d'un gestionnaire CloudScript potentiel.
```javascript theme={null}
// CloudScript (JavaScript)
//See: JSON.parse, JSON.stringify, parseInt and other built-in javascript helper functions for manipulating data
var currentState; // here we are calculating the current player's game state
// here we are fetching the "SaveState" key from PlayFab,
var playerData = server.GetUserReadOnlyData({"PlayFabId" : currentPlayerId, "Keys" : ["SaveState"]});
var previousState = {}; //if we return a matching key-value pair, then we can proceed otherwise we will need to create a new record.
if(playerData.Data.hasOwnProperty("SaveState"))
{
previousState = playerData.Data["SaveState"];
}
var writeToServer = {};
writeToServer["SaveState"] = previousState + currentState; // pseudo Code showing that the previous state is updated to the current state
var result = server.UpdateUserReadOnlyData({"PlayFabId" : currentPlayerId, "Data" : writeToServer, "Permission":"Public" });
if(result)
{
log.info(result);
}
else
{
log.error(result);
}
```
## 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.
2. 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**.
3. 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](#advanced-debugging-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](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript-af). Découvrez comment utiliser le [débogage local de CloudScript avec Azure Functions.](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/local-debugging-for-cloudscript-using-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.
```javascript theme={null}
handlers.logTest = function(args, context) {
log.info("This is a log statement!");
log.debug("This is a debug statement.");
log.error("This is... an error statement?");
// the last parameter indicates we want logging on errors
http.request('https://httpbin.org/status/404', 'post', '', 'text/plain', null, true);
};
```
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.
```csharp theme={null}
// Invoke this on start of your application
void Login() {
PlayFabClientAPI.LoginWithCustomID(new LoginWithCustomIDRequest {
CreateAccount = true,
CustomId = "Starter"
}, result => RunLogTest(), null);
}
void RunLogTest() {
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest {
FunctionName = "logTest",
// duplicates the response of the request to PlayStream
GeneratePlayStreamEvent = true
}, null, null);
}
// Logs evaluated in next code block
```
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.
Cette sélection affiche le JSON brut de l'événement, détaillé pour chaque événement [ici](/fr/services/playfab/api-references/events). 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.
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.
```javascript theme={null}
handlers.logTest = function(args, context) {
log.info("This is a log statement!", { what: "Here on business." });
log.debug("This is a debug statement.", { who: "I am a doctor, sir" });
log.error("This is... an error statement?", { why: "I'm here to fix the plumbing. Probably.", errCode: 123 });
};
```
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.
```csharp theme={null}
void RunLogTest()
{
PlayFabClientAPI.ExecuteCloudScript(
new ExecuteCloudScriptRequest
{
FunctionName = "logTest",
// handy for logs because the response will be duplicated on PlayStream
GeneratePlayStreamEvent = true
},
result =>
{
var error123Present = false;
foreach (var log in result.Logs)
{
if (log.Level != "Error") continue;
var errData = (JsonObject) log.Data;
object errCode;
var errCodePresent = errData.TryGetValue("errCode", out errCode);
if (errCodePresent && (ulong) errCode == 123) error123Present = true;
}
if (error123Present)
Debug.Log("There was a bad, bad error!");
else
Debug.Log("Nice weather we're having.");
}, null);
}
```
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](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript) contient un [ExecuteCloudScriptResult](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#executecloudscriptresult) qui comprend un champ [ScriptExecutionError](xref:titleid.playfabapi.com.client.server-sidecloudscript.executecloudscript#scriptexecutionerror). En adaptant le dernier exemple de la section sur la journalisation, nous pourrions l'utiliser comme indiqué ci-dessous.
```csharp theme={null}
void RunLogTest() {
PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest {
FunctionName = "logTest",
// handy for logs because the response will be duplicated on PlayStream
GeneratePlayStreamEvent = true
}, result => {
if(result.Error != null) {
Debug.Log(string.Format("There was error in the CloudScript function {0}:\n Error Code: {1}\n Message: {2}"
, result.FunctionName, result.Error.Error, result.Error.Message));
}
},
null);
}
```
Si une erreur se produisait, ce code l'afficherait dans le journal.
## Related topics
- [Démarrage rapide de CloudScript](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript/quickstart.md)
- [Documentation de la gestion des services en direct PlayFab](/fr/services/playfab/live-service-management/index.md)
- [Démarrage rapide des tâches planifiées](/fr/services/playfab/data-analytics/acting-data/scheduled-tasks/quickstart.md)
- [Guide de démarrage rapide de PlayFab CloudScript avec Azure Functions](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart.md)
- [Appels de webhooks depuis CloudScript](/fr/services/playfab/live-service-management/service-gateway/automation/cloudscript/making-webhook-calls-from-cloudscript.md)