将 CloudScript 操作与 PlayStream 配合使用

项目
10/13/2023

从 PlayStream 操作启动 CloudScript 处理程序时，此处理程序可以访问有关运行原因的其他数据（上下文）- 您可以使用它来驱动服务器端逻辑。

本教程介绍上下文中的所有可用内容，以及如何在 CloudScript 处理程序中使用它。

CloudScript 基础知识

充分利用 CloudScript 的关键在于知道如何使用可用的输入 - 即处理程序的 args 和 context。

例如，以下是初学者 CloudScript 中的 helloWorld 示例，在所有新创建的游戏中加载为 Revision 1（也可在我们的 GitHub 中找到，如下所示）。

// 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 };
}

此示例说明通过 ExecuteCloudScript 从客户端调用 CloudScript 的常见用例。它检查使用键 inputValue 传入的参数，并使用此键的值作为执行调试日志信息中返回的文本的一部分。

context 输入参数

但是，也可以通过规则 (Automation->Rules)、细分进入/退出操作 (Players->Segments) 或任务服务 (Automation->Tasks) 作为 PlayStream 中事件的结果来调用 CloudScript。

执行此操作时，传递给函数的 context 提供了采取适当操作所需的所有信息。

要了解 PlayStream 事件的基本工作原理，请参阅我们的博客 Introducing PlayStream；有关 PlayStream 事件类型及其属性的列表，请参阅我们的 PlayFab API 参考。

要查看此操作，请查看同一示例 CloudScript 中的 handlePlayStreamEventAndProfile 处理程序。

// 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 };
}

对于 PlayStream 触发的 CloudScript 调用，context 包含 3 个元素，可用于驱动服务器权威处理程序逻辑。

还有 playStreamEvent - 您可以在上面的示例代码中看到它。 playStreamEvent 包含作为 JSON 对象触发处理程序的完整事件，有关其所有参数的信息，请参阅 PlayStream 事件文档。因此，例如，如果在游戏中设置了对任何 player_logged_in event 调用 handlePlayStreamEventAndProfile 的规则，则 playStreamEvent.EventName 将是 player_logged_in 等（点击此处查看此事件的完整参数集）。
接下来，还有 playerProfile - 也可以在前面的示例中看到。它包含有关触发事件的玩家的信息。您可以在此找到 profile 参数的所有详细信息，但除此以外，它还包含游戏中玩家的完整统计数据集，以及分配给此玩家的任何自定义标签，以便您利用此充分数据做出明智决策。
context 的最后一个元素是 triggeredByTask。与使用规则和细分进入/退出触发器时设置的前两个元素不同，triggeredByTask 仅适用于处理程序作为任务的结果运行的情况（不管是手动还是通过计时器）。它仅包含两个参数：

Name - 在创建任务时为其提供的唯一名称。
ID - PlayFab 为任务自动生成的唯一标识符。

对于针对用户细分运行的任务，还将有 playerProfile，但不会有 playStreamEvent。

对于简单地针对游戏运行但没有任何细分的任务，不会有 playerProfile，因为意图是运行一些更通用的任务，例如为事件设置一些游戏数据。

因此，name 是用在处理程序代码流中的元素，以确定要采取的相应操作。

PlayStream 和 CloudScript

在许多方面，PlayStream 操作触发的 CloudScript 处理程序比通过调用 ExecuteCloudScript 直接触发的功能具有更多潜在功能，因为通过 context 可以获得丰富的数据集。

这让您能够在发布后使用附加逻辑（使用您起初没有想到的事件或玩家档案的元素）更新处理程序，而不必以任何方式更新客户端代码。

此外，我们将在 PlayFab 服务的未来更新中继续扩展玩家档案，这将为服务器端逻辑提供更多的选择。

通过

将 CloudScript 操作与 PlayStream 配合使用

CloudScript 基础知识

context 输入参数

PlayStream 和 CloudScript

其他资源