CloudScript アクションと PlayStream を使用する

  • [アーティクル]

PlayStream アクションから CloudScript ハンドラーを開始すると、そのハンドラーは実行理由 (コンテキスト) に関する追加データにアクセスでき、それを使用してサーバー側のロジックを実行できます。

このチュートリアルでは、このコンテキストで可能なすべての機能と、CloudScript ハンドラーでそれを使用する方法を説明します。

CloudScript の基本

CloudScript を最大限に活用する鍵は、利用可能な入力 (ハンドラーの引数とコンテキスト) を使用する方法を知ることです。

たとえば、新しく作成されたすべてのタイトルのリビジョン 1 としてロードされた、スターターの CloudScript の helloWorld の例を用意しました (Microsoft の 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 のキーで渡された引数をチェックし、実行に対するデバッグ ログ情報に返されるテキストの一部としてそのキーの値を使用します。

コンテキストの入力パラメーター

ただし、ルール ([Automation (自動化)]->[Rules (ルール)])、セグメントの進入または退出アクション ([プレイヤー]->[セグメント])、またはタスク サービス ([Automation (自動化)]->[タスク]) によって、PlayStream のイベントの結果として CloudScript を呼び出すこともできます。

これを実行すると、関数に渡されたコンテキストによって、適切なアクションを実行するために必要なすべての情報が提供されます。

PlayStream イベントの仕組みの基本は、ブログ「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 呼び出しの場合は、コンテキストにサーバーが権威を持つハンドラーのロジックを促進するために使用できる 3 つの要素が含まれます。

  1. 上記のコードの例に playStreamEvent があります。 playStreamEvent には、JSON オブジェクトとしてハンドラーをトリガーした完全なイベントと、PlayStream イベントの説明書に記載されるすべてのパラメーターが含まれます。 そのため、たとえばいずれかの player_logged_in event に対する handlePlayStreamEventAndProfile というルールをタイトルに設定した場合、playStreamEvent.EventName は player_logged_in などになります (イベントの完全なパラメーターのセットはこちらをご覧ください)。

  2. 次に、前の例には playerProfile もあります。 これには、イベントをトリガーしたプレイヤーに関する情報が含まれています。 ここでプロファイル パラメーターの詳細を確認できますが、特に、タイトルのプレイヤーに対する完全な統計情報と、そのプレイヤーに割り当てたカスタム タグが含まれています。そのため、そのデータを使用して豊富な情報に基づく意思決定が可能です。

  3. コンテキストの最後の情報は triggeredByTask です。 ルールの使用とセグメントの侵入/退出がトリガーされると設定される最初の 2 つとは異なり、triggeredByTask は手動かタイマーどおりかにかかわらず、タスクの結果としてハンドラーが実行された時のみ適用されます。 含まれるのは 2 つのパラメーターのみです。

  • Name – 作成時にタスクに付けた一意の名前です。

  • ID – PlayFab によってタスクに自動的に生成された一意の識別子です。

ユーザー セグメントに対して実行されるタスクに対しては playerProfile もありますが、playStreamEvent はありません。

また、単にゲームに対して実行されるもののセグメントに実行されないタスクには playerProfile はありません。これは、イベントに向けたタイトル データの設定など、より全般的なタスクを実行することが目的であるためです。

そのため、ハンドラーのコード フローで使用し、適切なアクションを決定するためには Name の要素を使用します。

PlayStream と CloudScript

多くの点で、PlayStream アクションによってトリガーされる CloudScript ハンドラーは、ExecuteCloudScript への呼び出しによって直接トリガーされるハンドラーよりも機能が豊富である可能性があります。コンテキストによって利用可能となる豊富なデータがあるためです。

これにより、最初は予測していなかったイベントの要素やプレイヤーのプロファイルを使用した追加ロジックで開始後のハンドラーを更新できます。この場合、クライアント コードを更新する必要はありません。

さらに、PlayFab サービスの今後の更新でプレイヤー プロファイルをさらに追加していく予定です。これにより、サーバー側のロジックのオプションはさらに増えることになります。