チュートリアル: CloudScript コンテキスト モデルの使用

PlayFab は、API、スケジュールされたタスク、PlayStream イベント、プレーヤーがセグメントに出入りするときなど、いくつかのメカニズムを通じてスクリプトを実行します。 多くの場合、スクリプトが実行されるコンテキストは、スクリプトの実行方法にとって重要です。 この例は、スクリプトが実行されているプレーヤーのプレーヤー ID を知っています。 スクリプトが実行されるコンテキストによって、使用可能なデータ モデルが決まり、スクリプトで使用されるコンテキスト固有のデータが提供されます。

このチュートリアルで学習する内容は次のとおりです。

  • 共有コンテキスト モデルを使用する
  • ExecuteFunction API を介して実行する場合は、コンテキスト モデルを使用します。
  • スケジュールされたタスクを介して実行する場合は、コンテキスト モデルを使用します。
  • プレーヤーのコンテキストで実行する場合は、コンテキスト モデルを使用します。
  • エンティティのコンテキストで実行する場合は、コンテキスト モデルを使用します。

共有タイトル認証コンテキスト モデルを使用する

スクリプトの実行方法に関係なく、タイトル認証コンテキストが常に提供されます。 これには、スクリプトの実行に使用されるタイトル ID とエンティティ トークン (詳細については GetEntityToken を参照) が含まれます。 このコンテキストを知っていると、サーバー API を使用してスクリプト内で PlayFab への追加の API 呼び出しを行うことができます。

// Shared models
public class TitleAuthenticationContext
{
    public string Id { get; set; }
    public string EntityToken { get; set; }
}

ExecuteFunction API を介して実行する場合は、コンテキスト モデルを使用する

ExecuteFunction API を使用してスクリプトを実行すると、提供されるコンテキストには次の情報が含まれます:

  • 呼び出し元のエンティティ プロフィール
  • タイトル認証コンテキスト
  • 実行中の関数の一部として PlayStream イベントが送信されるかどうかを示すブール値
  • スクリプトを呼び出すときに使用される関数の引数
// Models via ExecuteFunction API
public class FunctionExecutionContext<T>
{
    public PlayFab.ProfilesModels.EntityProfileBody CallerEntityProfile { get; set; }
    public TitleAuthenticationContext TitleAuthenticationContext { get; set; }
    public bool? GeneratePlayStreamEvent { get; set; }
    public T FunctionArgument { get; set; }
}

public class FunctionExecutionContext : FunctionExecutionContext<object>
{
}

スケジュールされたタスクを介して実行する場合は、コンテキスト モデルを使用する

スクリプトを実行するようにタスクをスケジュールすると、提供されるコンテキストには次の情報が含まれます。

  • スケジュールされたタスク名 ID
  • PlayStream イベントのスタックを含むイベント履歴
  • タイトル認証コンテキスト
  • 実行中の関数の一部として PlayStream イベントが送信されるかどうかを示すブール値
  • スクリプトを呼び出すときに使用される関数の引数
// Models via Scheduled task
public class PlayStreamEventHistory
{
    public string ParentTriggerId { get; set; }
    public string ParentEventId { get; set; }
    public bool TriggeredEvents { get; set; }
}

public class ScheduledTaskFunctionExecutionContext<T>
{
    public PlayFab.CloudScriptModels.NameIdentifier ScheduledTaskNameId { get; set; }
    public Stack<PlayStreamEventHistory> EventHistory { get; set; }
    public TitleAuthenticationContext TitleAuthenticationContext { get; set; }
    public bool? GeneratePlayStreamEvent { get; set; }
    public T FunctionArgument { get; set; }
}

public class ScheduledTaskFunctionExecutionContext : ScheduledTaskFunctionExecutionContext<object>
{
}

プレーヤーのコンテキストで実行する場合は、コンテキスト モデルを使用する

プレーヤー PlayStream イベントを介してスクリプトを実行する場合、セグメントに出入りする場合、またはセグメント ベースのスケジュールされたタスクの一部として提供されるコンテキストには、次の情報が含まれます。

  • プレイヤー プロフィール
  • プレーヤー プロフィールが切り捨てられているかどうかを示すブール値。
    • プレーヤー プロフィールは、2048 バイトを超えると切り捨てられます。 これが発生した場合は、プロフィール API (サーバー、クライアント、またはエンティティ API のいずれか) を使用して完全なプロフィールを取得する必要があります。
  • スクリプトをトリガーした PlayStream イベント。
  • 実行中の関数の一部として PlayStream イベントが送信されるかどうかを示すブール値
  • スクリプトを呼び出すときに使用される関数の引数
// Models via Player PlayStream event, entering or leaving a 
// player segment or as part of a player segment based scheduled task.
public class PlayerPlayStreamFunctionExecutionContext<T>
{
    public PlayFab.CloudScriptModels.PlayerProfileModel PlayerProfile { get; set; }
    public bool PlayerProfileTruncated { get; set; }
    public PlayFab.CloudScriptModels.PlayStreamEventEnvelopeModel PlayStreamEventEnvelope { get; set; }
    public TitleAuthenticationContext TitleAuthenticationContext { get; set; }
    public bool? GeneratePlayStreamEvent { get; set; }
    public T FunctionArgument { get; set; }
}

public class PlayerPlayStreamFunctionExecutionContext : PlayerPlayStreamFunctionExecutionContext<object>
{
}

エンティティ PlayStream イベントを介して実行する場合、エンティティ セグメントに出入りする場合、またはエンティティ セグメント ベースのスケジュールされたタスクの一部として、コンテキスト モデルを使用します。

エンティティ PlayStream イベントを介してスクリプトを実行する場合、エンティティ セグメントに出入りする場合、またはエンティティ セグメント ベースのスケジュールされたタスクの一部として提供されるコンテキストには、次の情報が含まれます。

  • エンティティ プロフィール
  • スクリプトをトリガーした PlayStream イベント。
  • 実行中の関数の一部として PlayStream イベントが送信されるかどうかを示すブール値
// Models via Entity PlayStream event, entering or leaving an 
// entity segment or as part of an entity segment based scheduled task.
public class EventFullName
{
    public string Name { get; set; }
    public string Namespace { get; set; }
}

public class OriginInfo
{
    public string Id { get; set; }
    public DateTime? Timestamp { get; set; }
}

public class EntityPlayStreamEvent<T>
{
    public string SchemaVersion { get; set; }
    public EventFullName FullName { get; set; }
    public string Id { get; set; }
    public DateTime Timestamp { get; set; }
    public PlayFab.CloudScriptModels.EntityKey Entity { get; set; }
    public PlayFab.CloudScriptModels.EntityKey Originator { get; set; }
    public OriginInfo OriginInfo { get; set; }
    public T Payload { get; set; }
    public PlayFab.ProfilesModels.EntityLineage EntityLineage { get; set; }
}

public class EntityPlayStreamEvent : EntityPlayStreamEvent<object>
{
}

public class EntityPlayStreamFunctionExecutionContext<TPayload, TArg>
{
    public PlayFab.ProfilesModels.EntityProfileBody CallerEntityProfile { get; set; }
    public EntityPlayStreamEvent<TPayload> PlayStreamEvent { get; set; }
    public TitleAuthenticationContext TitleAuthenticationContext { get; set; }
    public bool? GeneratePlayStreamEvent { get; set; }
    public TArg FunctionArgument { get; set; }
}

public class EntityPlayStreamFunctionExecutionContext : EntityPlayStreamFunctionExecutionContext<object, object>
{
}