Share via

Verwenden von CloudScript-Aktionen mit PlayStream

  • Artikel

Wenn ein CloudScript-Handler über eine PlayStream-Aktion gestartet wird, hat dieser Handler Zugriff auf zusätzliche Daten darüber, warum er ausgeführt wird – den Kontext – die Sie zum Steuern Ihrer serverseitigen Logik verwenden können.

In diesem Tutorial erfahren Sie, was alles im Kontext verfügbar ist und wie Sie es in Ihren CloudScript-Handlern verwenden.

CloudScript-Grundlagen

Der Schlüssel, um CloudScript optimal zu nutzen, besteht darin, zu wissen, wie Sie mit den verfügbaren Eingaben arbeiten können– nämlich mit den Argumenten und dem Kontext für Ihren Handler.

Hier sehen Sie beispielsweise das helloWorld Beispiel aus dem Starter-CloudScript, das als Revision 1 in allen neu erstellten Titeln geladen wird (auch verfügbar in unserem GitHub, siehe unten).

// This is a CloudScript function.
// "args" is set to the value of the "FunctionParameter" parameter of the ExecuteCloudScript API.
// "context" contains additional information when the CloudScript function is called from a PlayStream action.
handlers.helloWorld = function (args, context) {

    // The pre-defined "currentPlayerId" variable is initialized to the PlayFab ID of the player logged-in on the game client.
    // CloudScript handles authenticating the player automatically.
    var message = "Hello " + currentPlayerId + "!";

    // You can use the "log" object to write out debugging statements. It has
    // three functions corresponding to logging level: debug, info, and error. These functions
    // take a message string and an optional object.
    log.info(message);
    var inputValue = null;
    if (args != null && args != undefined)
    {
        inputValue = args.inputValue;
    }
    log.debug("helloWorld:", { input: inputValue });

    // The value you return from a CloudScript function is passed back
    // to the game client in the ExecuteCloudScript API response, along with any log statements
    // and additional diagnostic information, such as any errors returned by API calls or external HTTP
    // requests. They are also included in the optional player_executed_cloudscript PlayStream event
    // generated by the function execution.
    return { messageValue: message };
}

In diesem Beispiel wird der gängige Anwendungsfall des Aufrufens von CloudScript von einem Client über ExecuteCloudScript veranschaulicht. Es sucht nach einem Argument, das mit dem Schlüssel inputValueübergeben wird, und verwendet den Wert für diesen Schlüssel als Teil des Texts, der in den Debugprotokollinformationen für die Ausführung zurückgegeben wird.

Der Kontexteingabeparameter

Es ist jedoch auch möglich, ein CloudScript als Ergebnis eines Ereignisses in PlayStream über eine Regel (Automation-Rules>), eine Segment enter/exit Action (Players-Segments>) oder den Aufgabendienst (Automation-Tasks>) aufzurufen.

Wenn Sie dies tun, enthält der an die Funktion übergebene Kontext alle Informationen, die Sie benötigen, um die entsprechende Aktion auszuführen.

Informationen zu den Grundlagen der Funktionsweise von PlayStream-Ereignissen finden Sie in unserem Blog Introducing PlayStream( Einführung in PlayStream). Eine Liste der PlayStream-Ereignistypen und deren Eigenschaften finden Sie in unserer PlayFab-API-Referenz.

Um diese Aktion anzuzeigen, sehen Sie sich den handlePlayStreamEventAndProfile Handler aus demselben CloudScript-Beispiel an.

// This is a simple example of a function that is called from a
handlers.handlePlayStreamEventAndProfile = function (args, context) {

    // The event that triggered the action.
    // For a list of event types, see our PlayFab API documentation.
    var psEvent = context.playStreamEvent;

    // The profile data of the player associated with the event
    var profile = context.playerProfile;

    // Post data about the event to an external API
    var content = JSON.stringify({user: profile.PlayerId, event: psEvent.EventName});
    var response = http.request('https://httpbin.org/status/200', 'post', content, 'application/json', null, true);

    return { externalAPIResponse: response };
}

Bei einem durch PlayStream ausgelösten CloudScript-Aufruf enthält der Kontext drei Elemente, die verwendet werden können, um die Logik Ihres serverautorisierenden Handlers zu steuern.

  1. Es gibt den playStreamEvent, den Sie im obigen Beispielcode sehen können. enthält playStreamEvent das vollständige Ereignis, das den Handler als JSON-Objekt ausgelöst hat, mit allen Parametern, die in der PlayStream-Ereignisdokumentation angezeigt werden. Wenn Sie also z. B. eine Regel in Ihrem Titel einrichten, die für ein beliebiges aufrufthandlePlayStreamEventAndProfile, playStreamEvent.EventName wäre player_logged_in, usw. (hier ist der vollständige Satz von Parametern für dieses Ereignis).player_logged_in event

  2. Als Nächstes gibt es die playerProfile, die auch im vorherigen Beispiel gezeigt wird. Diese enthält Informationen zum Player, der das Ereignis ausgelöst hat. Hier finden Sie alle Details der Profilparameter, aber es enthält unter anderem den vollständigen Satz von Statistiken für den Spieler in Ihrem Titel sowie alle benutzerdefinierten Tags, die Sie dem Spieler zugewiesen haben, sodass Sie diese Daten für sehr umfangreiche Entscheidungen verwenden können.

  3. Das letzte Element des Kontexts ist triggeredByTask. Im Gegensatz zu den ersten beiden, die bei verwendung von Regeln und Segment enter/exit-Triggern festgelegt werden, ist nur anwendbar, triggeredByTask wenn der Handler als Ergebnis einer Aufgabe ausgeführt wird, sei es manuell oder auf einem Timer. Sie enthält nur zwei Parameter:

  • Name : Der eindeutige Name, den Sie ihrer Aufgabe bei der Erstellung gegeben haben.

  • ID : Der eindeutige Bezeichner, der automatisch von PlayFab für Ihre Aufgabe generiert wird.

Für eine Aufgabe, die für ein Benutzersegment ausgeführt wird, verfügen Sie ebenfalls über , playerProfileaber nicht über eine playStreamEvent.

Und für eine Aufgabe, die einfach gegen Ihr Spiel ausgeführt wird, aber ohne Segment, gibt es keine playerProfile, da die Absicht darin besteht, etwas allgemeineres auszuführen, z. B. das Festlegen einiger Titeldaten für ein Ereignis.

Name ist also das Element, das Sie im Codefluss Ihres Handlers verwenden möchten, um die entsprechende Aktion zu bestimmen.

PlayStream plus CloudScript

In vielerlei Hinsicht verfügen CloudScript-Handler, die von PlayStream-Aktionen ausgelöst werden, über noch mehr potenzielle Funktionen als diejenigen, die direkt durch Aufrufe ExecuteCloudScriptvon ausgelöst werden, da es eine vielzahl von Daten gibt, die über den Kontext verfügbar gemacht werden.

Dadurch haben Sie die Möglichkeit, Ihre Handler nach dem Start mit zusätzlicher Logik zu aktualisieren, die Elemente des Ereignis- oder Playerprofils verwendet, die Sie ursprünglich nicht erwartet hatten, ohne Ihren Clientcode in irgendeiner Weise aktualisieren zu müssen.

Darüber hinaus werden wir das Spielerprofil in zukünftigen Updates des PlayFab-Diensts weiter ergänzen, was noch mehr Optionen für serverseitige Logik bietet.