イベントパイプライン

イベントパイプラインは PlayFab Services SDK に含まれる機能で、その主な目的はゲーム開発者が PlayFab Insights に保存されるイベントを送信できるようにすることです。開発者はバッチサイズ、送信頻度、および適切なテレメトリソリューションの他の側面を指定できます。これはゲーム開発者の負担を軽減し、これらの側面をすべて代行するのに役立ちます。構成可能なイベントパイプラインがサポートされています。タイトルには 1 つまたは複数のこれらのパイプラインを含めることができ、それぞれに独自のプロパティを構成できます。パイプラインの基本的な概念について説明していきましょう。

パイプラインタイプ

パイプラインタイプは、パイプラインが発行するイベントの種類に直接関連しています。開発者がインスタンス化できるパイプラインには 2 つの異なるタイプがあります:

テレメトリイベントパイプライン: テレメトリイベントのみを発行でき、Write Telemetry Events REST API を使用します。
PlayStream イベントパイプライン: PlayStream イベントのみを発行でき、Write Events REST API を使用します。

異なるタイプと構成の複数のパイプラインを持つことができますが、パイプラインタイプは作成後に変更できないことに注意してください。パイプラインの再インスタンス化が必要になります。

認証タイプ

パイプライン作成のもう 1 つの重要な要素は認証タイプです。PlayFab イベントでは、エンティティ認証とテレメトリキー認証の 2 つの認証メカニズムがサポートされています。エンティティ認証は、ゲーム開発者がイベントを特定のエンティティに紐付けて、さらなる集計や分析を行いたい場合に使用されます。たとえば、ゲーム開発者はプレイヤーのアクションに関連するイベントをログに記録して、セグメンテーションを可能にするタイトルプレイヤーのさらなる行動分析を行うことができます。テレメトリキー認証は、ゲーム開発者がエンティティに必ずしも紐付ける必要のないイベントをログに記録したい場合に使用されます。たとえば、ログインしたプレイヤーが存在する前に、タイトルはパフォーマンスに関連するイベントや、さらなる分析のために収集したい特定のメトリックの送信を開始できます。これは、通常のエンティティ認証プロセスを経ることなく実行できます。 サポートされる認証タイプ / イベントタイプの組み合わせ

	エンティティ認証	テレメトリキー認証
テレメトリイベント	有効	有効
PlayStream イベント	有効	無効

エンティティ認証

この認証タイプは、通常かつ最も一般的な PlayFab 認証方法です。特定のエンティティに密接に関連しており、後続の呼び出しで使用されるエンティティトークンを取得するために、対応する PlayFab ログイン API を呼び出す必要があります。次のリストは、エンティティ認証で使用できる異なるタイプのエンティティを表しています。

namespace: namespace エンティティは、スタジオ内のすべてのタイトルのすべてのグローバル情報を指します。
title: title エンティティは、そのタイトルのすべてのグローバル情報を指します。
master_player_account: master_player_account は、スタジオ内のすべてのタイトルで共有されるプレイヤーエンティティです。
title_player_account: 多くの開発者にとって、title_player_account は最も伝統的な方法でプレイヤーを表します。
character: character エンティティは title_player_account のサブエンティティです。
group: group エンティティは、他のエンティティのコンテナーです。現在、プレイヤーとキャラクターに限定されています。

異なるエンティティタイプの詳細については、組み込みエンティティタイプを参照してください。また、パイプラインエンティティは、有効な PFEntityHandle を提供することにより、パイプライン作成後に更新できます。したがって、ゲーム開発者はエンティティを追加してイベントの紐付けを開始したり (エンティティ認証への切り替えまたはエンティティの更新セクションを参照)、エンティティに関連しないものをログに記録したい場合は削除することもできます (テレメトリキー認証への切り替えセクションを参照)。パイプラインにエンティティが存在する場合、それは常にテレメトリキー認証よりも優先されます。

テレメトリキー認証

テレメトリキー認証はエンティティトークンを必要としないため、特定のエンティティに紐付けられません。テレメトリキー認証が使用される場合、パイプライン作成時に PFEventPipelineTelemetryKeyConfig 構造体が必要です。この構造体には 2 つの主な部分があります:

PlayFab Game Manager 経由で作成および管理される文字列で構成されるテレメトリキー。
SDK にイベントのアップロードに使用すべき適切なサービス構成を知らせる PFServiceConfigHandle。サービス構成ハンドルは、SDK 初期化中に PFServiceConfigCreateHandle を呼び出すことで作成されます。

開発者がテレメトリキーを使用したい場合は、パイプラインがインスタンス化された後にテレメトリキーを追加する方法がないため、パイプライン作成時に提供することが重要です。 テレメトリキー認証はテレメトリイベントでのみ利用可能で、PlayStream イベントをサポートしていないことに注意してください。

イベントパイプラインの構成

前述したように、イベントパイプラインには、PFEventPipelineConfig 構造体パラメーターを介してパイプライン作成後に提供できる構成可能なプロパティがいくつかあります。構成可能なプロパティは次のとおりです:

maxEventsPerBatch: PlayFab に書き込む前にバッチ処理されるイベントの最大数。
maxWaitTimeInSeconds: パイプラインが不完全なバッチを送信するまで待機する最大時間。
pollDelayInMs: パイプラインがイベントバッファーを空にした後、再度読み込むまでに待機する時間。
compressionLevel: 圧縮アルゴリズムで使用される圧縮レベルを定義します。圧縮の詳細については、GZIP 圧縮 を参照してください。
retryOnDisconnect: イベントパイプラインは、接続の切断により失敗したイベントの送信を再試行します。テレメトリイベントパイプラインでのみ利用可能です。
bufferSize: パイプラインのバッファー内のイベント量の上限。

デフォルト値

プロパティ	テレメトリパイプライン	PlayStream パイプライン
maxEventsPerBatch	5	5
maxWaitTimeInSeconds	3	3
pollDelayInMs	3000	10
compressionLevel	None (無効)	None (無効)
retryOnDisconnect	true	該当なし
bufferSize	1024	1024

PFEventPipelineConfig に一部のプロパティのみが指定されている場合、空のものは上書きされ、デフォルト値が使用されます。これらのプロパティのいずれかをイベントパイプライン用に更新する方法の例については、パイプライン構成の更新 を参照してください。

GZIP 圧縮

イベントパイプラインは、GZIP 圧縮標準を使用して本文ペイロードを圧縮するオプションを提供します。必要な圧縮レベルは、PFEventPipelineUpdateConfiguration API パラメーターの一部である PFEventPipelineConfig 構造体内で指定できます。低い圧縮レベルは、圧縮率は低いですが最高速度を実現し、高い圧縮レベルはより良い圧縮率を実現しますが、圧縮速度は最も遅くなります。圧縮率の違いは、送信されるデータのタイプにすべて依存します。データのサイズとランダム性によっては、異なるレベルでも圧縮率が同じになる場合があります。 トレードオフ: 圧縮を使用すると、圧縮アルゴリズムの実行という複雑さが追加されるため CPU 時間が増加しますが、一方でネットワークの本文ペイロードは大幅に減少します。したがって、ゲームのニーズとリソースに応じて、圧縮を使用するかどうかはゲーム開発者次第です。内部検証に基づくと、CPU 時間は平均 20% 増加し、ペイロード本文サイズは平均 91% 減少します。これらのパーセンテージは、圧縮されるデータのペイロードサイズと複雑さによって大きく変わる可能性があります。

イベントハンドラー

パイプライン作成の一環として、ゲーム開発者は、イベントがアップロードされたときに呼び出される 2 つのオプションのイベントハンドラーを提供できます。ただし、ゲーム開発者が “fire and forget” (投げっぱなし) のエクスペリエンスを希望する場合は、イベントハンドラーの提供を省略できます。提供できるイベントハンドラーは次のとおりです:

PFEventPipelineBatchUploadSucceededEventHandler: 名前の通り、PlayFab に正常にアップロードされたすべてのイベントを受け取ります。
PFEventPipelineBatchUploadFailedEventHandler: パイプラインの再試行ロジックを経て失敗したすべてのイベントを受け取ります。

パイプライン作成の例

以下では、前述のトピックに基づいてイベントパイプラインをインスタンス化する方法の異なる例を見ることができます。

エンティティ認証を使用したテレメトリイベントパイプラインの作成 開発者がテレメトリイベントを送信したいが、テレメトリキー認証を使用する必要がない場合、次の例に示すように PFEventPipelineCreateTelemetryPipelineHandleWithEntity API がこの目的に役立ちます:

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

この例は、エンティティ認証を使用し、ハンドラーがないテレメトリイベントパイプラインを作成する方法を示しています。これは、パイプラインがイベントを発行し、結果を気にしないことを意味します。

テレメトリキー認証を使用したテレメトリイベントパイプラインの作成 開発者がテレメトリイベントを送信したいが、テレメトリキー認証を使用する必要がある場合、次の例に示すように PFEventPipelineCreateTelemetryPipelineHandleWithKey API がこの目的に役立ちます:

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

この例は、エンティティ認証を使用しないテレメトリイベントパイプラインを作成する方法を示しています。イベントパイプラインは、後でエンティティを追加する可能性を持って、テレメトリキーを使用してイベントのアップロードを開始します。エンティティ認証への切り替えまたはエンティティの更新を参照してください。

PlayStream イベントパイプラインの作成 開発者が PlayStream イベントを送信したい場合、次の例に示すように PFEventPipelineCreatePlayStreamPipelineHandle API がこの目的に役立ちます:

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreatePlayStreamPipelineHandle(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

この例は、エンティティ認証を使用し、ハンドラーがない PlayStream イベントパイプラインの作成方法を示しています。これは、パイプラインがイベントを発行し、結果を気にしないことを意味します。

イベントハンドラーを使用するイベントパイプライン この例は、パイプライン作成 API にイベントハンドラーを提供する方法を示しています。

void CALLBACK OnBatchUploadedHandler(void* context, PFUploadedEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void CALLBACK OnBatchUploadFailedHandler(void* context, HRESULT hr, const char* errorMessage, PFEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        OnBatchUploadedHandler,             // eventPipelineBatchUploadedEventHandler
        OnBatchUploadFailedHandler,         // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

例に示すように、OnBatchUploadedHandler と OnBatchUploadFailedHandler は、イベントパイプラインの作成時に渡される 2 つの異なるコールバック関数として宣言されます。イベントに関連するすべての結果は、結果が成功か失敗かに応じて、これら 2 つの関数のいずれかで返されます。結果をどのように処理するかはゲーム開発者次第です。

イベントの発行

イベントパイプラインが既に作成されていれば、イベントの発行は簡単な操作です。ゲーム開発者は、既存のイベントパイプラインハンドルと送信したいイベントを受け取る PFEventPipelineEmitEvent API を呼び出す必要があります。

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEvent myEvent
    {
        nullptr,
        "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

テレメトリキー認証を使用する場合、PFEntityKey の一部としての entityType の有効な値は “external” のみであることに注意することが重要です。他のエンティティタイプは拒否され、イベントはアップロードされません。テレメトリキー認証を使用する場合の有効な PFEntityKey の例:

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEntityKey pfEntityKey{ "my-unique-ID", "external" };  // Note the "external" value

    PFEvent myEvent
    {
        &pfEntityKey,
        "custom.playfab.events.PlayFab.Test.EventsWithTelemetryKey",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

イベントが発行されたときにバッファーサイズの制限を超えた場合、次のように SDK からエラーが発生します:

E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

ニーズに応じた適切なバッファーサイズを設定してください。

エンティティ認証への切り替えまたはエンティティの更新

パイプラインがテレメトリキー構成のみを使用して作成されている場合、エンティティ認証に切り替える方法や、パイプラインを別のエンティティを使用するように更新する方法があります。 PFEventPipelineAddUploadingEntity を使用することで、実行中のパイプラインを再初期化することなくエンティティを追加できます。既存のエンティティがある場合、それを置き換えます。例: タイトル実行の開始時にテレメトリキー構成でテレメトリイベントパイプラインが作成されます。この理由として考えられるのは、まだプレイヤーの ID がないか、単にまだプレイヤーに関連するものをログに記録したくない場合です。

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

その後、プレイヤーがログインしたか、特定のエンティティに紐付いたイベントの送信を開始したいだけなので、次のように既存のイベントパイプラインハンドルと目的のエンティティハンドルで PFEventPipelineAddUploadingEntity を呼び出すことができます:

void EventPipelineUpdateEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineAddUploadingEntity(
        handle,                 // eventPipelineHandle
        entityHandle            // entityHandle
    );

    if (FAILED(hr))
    {
        printf("Failed adding uploading entity: 0x%x\r\n", hr);
        return;
    }
}

この呼び出しの後、パイプラインは、そのエンティティに紐付けられた後続のイベントのログ記録を開始します。

テレメトリキー認証への切り替え

前のシナリオを拡張して、開発者がテレメトリ認証に戻り、エンティティからのイベントログを切り離したい場合、PFEventPipelineRemoveUploadingEntity を呼び出して、次のようにイベントパイプラインハンドルを渡すことができます:

void EventPipelineRemoveEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineRemoveUploadingEntity(
        handle                  // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed removing uploading entity: 0x%x\r\n", hr);
        return;
    }
}

この呼び出しはエンティティを削除し、後続のすべてのイベントに対してテレメトリキー認証に効果的に戻ります。

パイプライン構成の更新

パイプラインは、既存のイベントパイプラインハンドルと新しい構成構造体を受け取る PFEventPipelineUpdateConfiguration API を使用して次のように簡単に更新できます:

void EventPipelineUpdateConfiguration(PFEventPipelineHandle handle)
{
    uint32_t maxEvents = 10;
    uint32_t maxWaitTime = 5;
    uint32_t pollDelay = 50;
    PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
    bool retryOnDisconnect = true;
    size_t bufferSize = 2048;

    PFEventPipelineConfig eventPipelineConfig
    {
        &maxEvents,             // maxEventsPerBatch
        &maxWaitTime,           // maxWaitTimeInSeconds
        &pollDelay,             // pollDelayInMs
        &compressionLevel,      // compressionLevel
        &retryOnDisconnect,     // retryOnDisconnect
        &bufferSize,            // bufferSize
    };

    HRESULT hr = PFEventPipelineUpdateConfiguration(
        handle,                 // eventPipelineHandle
        eventPipelineConfig     // eventPipelineConfig
    );

    if (FAILED(hr))
    {
        printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
        return;
    };
}

注意事項: 空または null のプロパティは、既存の構成値をデフォルト値で上書きします。

無効化された/非アクティブなテレメトリキー

テレメトリキーが非アクティブ化された場合、またはパイプライン作成時に無効なキーが提供された場合、そのテレメトリキーを使用して実行中のイベントパイプラインは、キーが無効または非アクティブであることを検出するとすぐに失敗し始めます。顧客がキーを再アクティブ化する場合、パイプラインはそれを認識せず、失敗したイベントハンドラーを介して失敗を返送し続けます。この動作はセッションベースであることに注意してください。つまり、タイトルが再起動されると、新しいパイプラインが作成され、再びイベントをアップロードできるようになります。

パイプラインハンドルのライフサイクル

他の PlayFab ハンドルと同様に、イベントパイプラインハンドルは複製/クローズパターンを使用します:

PFEventPipelineCloseHandle: パイプラインハンドルを閉じます。パイプラインへの最後のハンドルが閉じられると、パイプラインは破棄され、残りのバッファされたイベントはフラッシュされます。
PFEventPipelineDuplicateHandle: パイプラインハンドルを複製します。元のハンドルと複製されたハンドルの両方は、PFEventPipelineCloseHandle で独立して閉じる必要があります。

// Duplicate a handle for use in another component
PFEventPipelineHandle duplicatedHandle;
HRESULT hr = PFEventPipelineDuplicateHandle(originalHandle, &duplicatedHandle);

// When done, close both handles independently
PFEventPipelineCloseHandle(duplicatedHandle);
PFEventPipelineCloseHandle(originalHandle);

XBOX Services

PlayFab

PlayFab Services SDK - イベントパイプライン

イベントパイプライン

パイプラインタイプ

認証タイプ

エンティティ認証

テレメトリキー認証

イベントパイプラインの構成

デフォルト値

GZIP 圧縮

イベントハンドラー

パイプライン作成の例

イベントの発行

エンティティ認証への切り替えまたはエンティティの更新

テレメトリキー認証への切り替え

パイプライン構成の更新

無効化された/非アクティブなテレメトリキー

パイプラインハンドルのライフサイクル

関連項目

​イベントパイプライン

​パイプラインタイプ

​認証タイプ

​エンティティ認証

​テレメトリキー認証

​イベントパイプラインの構成

​デフォルト値

​GZIP 圧縮

​イベントハンドラー

​パイプライン作成の例

​イベントの発行

​エンティティ認証への切り替えまたはエンティティの更新

​テレメトリキー認証への切り替え

​パイプライン構成の更新

​無効化された/非アクティブなテレメトリキー

​パイプラインハンドルのライフサイクル

​関連項目

イベントパイプライン

パイプラインタイプ

認証タイプ

エンティティ認証

テレメトリキー認証

イベントパイプラインの構成

デフォルト値

GZIP 圧縮

イベントハンドラー

パイプライン作成の例

イベントの発行

エンティティ認証への切り替えまたはエンティティの更新

テレメトリキー認証への切り替え

パイプライン構成の更新

無効化された/非アクティブなテレメトリキー

パイプラインハンドルのライフサイクル

関連項目