イベントパイプライン

[アーティクル]
10/04/2023

イベントパイプラインは PlayFab Services SDK の一部である機能であり、主な目的は、ゲーム開発者が PlayFab Insights に格納されるイベントを送信できるようにすることです。これにより、開発者はバッチサイズ、送信頻度、適切なテレメトリソリューションのその他の側面を指定できます。

これは、ゲーム開発者の負担を軽減し、それらのすべての側面を彼らの代わりに処理するのに役立ちます。構成可能なイベントパイプラインのサポートがあります。タイトルには、これらのパイプラインを 1 つ以上含めることができます。また、それぞれに独自のプロパティを使用して構成できます。

パイプラインの基本的な概念をいくつか見てみましょう。

パイプラインの種類

パイプラインの種類は、パイプラインによって出力されるイベントの種類に直接関連します。開発者がインスタンス化できるパイプラインには、次の 2 種類があります。

テレメトリイベントパイプライン: テレメトリイベントのみを出力でき、テレメトリイベントの書き込み REST API を使用できます。
PlayStream イベントパイプライン: PlayStream イベントのみを出力でき、書き込みイベント REST API を使用します。

異なる種類と構成を持つ複数のパイプラインを使用できますが、作成後にパイプラインの種類を変更することはできません。パイプラインの再インスタンス化が必要です。

認証の種類

パイプライン作成のもう 1 つの重要な部分は、認証の種類です。 PlayFab イベントには、エンティティ認証とテレメトリキー認証という 2 つの認証メカニズムがサポートされています。

エンティティ認証は、ゲーム開発者が特定のエンティティに対してイベントをリンクして、さらに集計または分析する場合に使用されます。たとえば、ゲーム開発者は、プレイヤーのアクションに関連するイベントをログに記録して、セグメント化を可能にするタイトルプレイヤーの動作分析をさらに行うことができます。

テレメトリキー認証は、ゲーム開発者が必ずしもエンティティにリンクする必要のないイベントをログに記録する場合に使用されます。たとえば、プレイヤーがログインする前に、タイトルはパフォーマンスに関連するイベントの送信を開始したり、さらに分析するために収集する特定のメトリックを開始したりできます。これは、通常のエンティティ認証プロセスを経ることなく実行できます。

サポートされている認証の種類/イベントの種類の組み合わせ

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

エンティティ認証

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

名前空間: 名前空間エンティティは、スタジオ内のすべてのタイトルのすべてのグローバル情報を参照します。
タイトル: タイトルエンティティは、タイトルのすべてのグローバル情報を参照します。
master_player_account: master_player_account は、スタジオ内の全タイトル間で共有されるプレイヤーエンティティです。
title_player_account: ほとんどの開発者にとって、title_player_account は最も従来的な意味でプレイヤーを表します。
文字: 文字エンティティは、title_player_account のサブエンティティです。
グループ: グループエンティティは、他のエンティティのコンテナーです。現在、プレイヤーとキャラクターに制限されています。

さまざまなエンティティ型の詳細については、「組み込みのエンティティ型」を参照してください。

また、パイプラインエンティティは、有効な PFEntityHandle を指定することで、パイプラインの作成後に更新できます。そのため、ゲーム開発者はエンティティを追加してイベントへのリンクを開始したり (「エンティティ認証への切り替え」または「エンティティの更新」セクションを参照)、エンティティに関連していないものをログに記録する必要があるエンティティを削除することもできます (「テレメトリキー認証への切り替え」セクションを参照)。

パイプラインにエンティティが存在する場合は、テレメトリキー認証よりも常に優先されます。

テレメトリキー認証

テレメトリキー認証ではエンティティトークンは必要ないため、特定のエンティティに関連付けられません。

テレメトリキー認証を使用する場合は、パイプラインの作成時に PFEventPipelineTelemetryKeyConfig 構造体が必要です。この構造体には、次の 2 つのメイン部分があります。

PlayFab ゲームマネージャーを使用して作成および管理される文字列で構成されるテレメトリキー。
イベントのアップロードに使用する適切なサービス構成が SDK に認識されるようにする PFServiceConfigHandle。サービス構成ハンドルは、PFServiceConfigCreateHandle を呼び出すことによって、SDK の初期化中に作成されます。

開発者がテレメトリキーを使用する場合は、パイプラインのインスタンス化後にテレメトリキーを追加する方法がないため、パイプラインの作成時に提供することが重要です。

テレメトリキー認証はテレメトリイベントでのみ使用できること、PlayStream イベントはサポートされていないことに注意してください。

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

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

構成可能なプロパティは次のとおりです。

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

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 の唯一の有効な値は "外部" であることに注意してください。その他のエンティティ型は拒否され、イベントはアップロードされません。

テレメトリキー認証を使用する場合の有効な 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 のプロパティは、既存の構成値を既定値で上書きします。

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

テレメトリキーが非アクティブ化された場合、またはパイプラインの作成時に無効なキーが指定されている場合、そのテレメトリキーを使用して実行されているイベントパイプラインは、キーが無効または非アクティブであることが判明するとすぐに失敗し始めます。

最終的に顧客がキーを再アクティブ化する場合、パイプラインはそのことを認識せず、失敗したイベントハンドラーを介してエラーを送信し続けます。この動作はセッションベースであるため、タイトルが再起動されると、新しいパイプラインが作成され、イベントを再度アップロードできることを意味します。

次の方法で共有

イベントパイプライン

パイプラインの種類

認証の種類

エンティティ認証

テレメトリキー認証

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

GZIP 圧縮

イベントハンドラー

パイプラインの作成例

イベントの出力

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

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

パイプライン構成の更新

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

関連項目

フィードバック

その他のリソース

次の方法で共有

イベント パイプライン

パイプラインの種類

認証の種類

エンティティ認証

テレメトリ キー認証

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

GZIP 圧縮

イベント ハンドラー

パイプラインの作成例

イベントの出力

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

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

パイプライン構成の更新

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

関連項目

フィードバック

その他のリソース

イベントパイプライン

テレメトリキー認証

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

イベントハンドラー

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

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