イベント パイプラインのチュートリアル

  • [アーティクル]

このドキュメントは、PlayFab Services SDK でイベント パイプライン機能を使用する方法に関する簡単な手順ごとのチュートリアルです。

手順 1 - PlayFab Services SDK の初期化

最初の手順では、PFServicesInitialize API と PFServiceConfigCreateHandle API を使用して PF Service SDK を初期化します。

PFServiceConfigCreateHandle API は、PlayFab ゲーム マネージャーでタイトルから取得できる接続文字列とタイトル ID を受け取ります。

3 番目のパラメーターは、作成中の構成を表す PFServiceConfigHandle 構造体です。 このサービス構成ハンドルは、次の手順で使用します。

PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

PFServiceConfigCreateHandle(
    "titleConnectionString",
    "titleId",
    &serviceConfigHandle
);

手順 2 - テレメトリ イベント パイプラインの作成

次に、PFEventPipelineCreateTelemetryPipelineHandleWithKey API を使用して、テレメトリ キーを持つテレメトリ イベント パイプラインを作成しましょう。 テレメトリ キーは、PlayFab ゲーム マネージャーを通じて作成および管理されます。

PFEventPipelineTelemetryKeyConfig 構造体を作成するときに、SDK の初期化中に取得した実際のテレメトリ キーとサービス構成ハンドルを渡します。

PFEventPipelineHandle handle;
XTaskQueueHandle taskQueueHandle;

XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Manual, &taskQueueHandle);

PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
{
    "myTelemetryKey",
    serviceConfigHandle,
};

HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
    &telemetryKeyConfig,
    taskQueueHandle,
    nullptr,
    nullptr,
    nullptr,
    &handle
);

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

手順 3 - パイプライン構成の更新

パイプライン構成を更新してみましょう。この例では、最大 10 個のイベントのバッチを送信します (既定値は 5)。

また、maxWaitTimeInSeconds と pollDelayInMs を null ポインターとして送信するため、それぞれのパイプライン型の既定値が使用されます。

また、"Medium" 圧縮レベルも指定しています。このプロパティを設定すると、本文のペイロードが圧縮され、ネットワーク リソースの使用率を最適化するのに役立ちます。

次に、PFEventPipelineUpdateConfiguration を呼び出して、前の手順で取得した PFEventPipelineHandle と PFEventPipelineConfig 構造体を渡します。

uint32_t maxEvents = 10;
PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;

PFEventPipelineConfig eventPipelineConfig
{
    &maxEvents,         // maxEventsPerBatch
    nullptr,            // maxWaitTimeInSeconds
    nullptr,            // pollDelayInMs
    &compressionLevel   // compressionLevel
};

HRESULT hr = PFEventPipelineUpdateConfiguration(
    handle,
    eventPipelineConfig
);

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

手順 4 - イベントの出力

この手順では、PFEventPipelineEmitEvent API を介して "TelemetryKeyEvent" という名前のイベントを 1 つだけ出力します。

これまでエンティティ認証を提供していないため、このイベントはどのエンティティにもリンクされません。

PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "TelemetryKeyEvent",
    nullptr,
    "{}"
};

HRESULT hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

手順 5 - エンティティの取得

ここでは、イベントとのリンクを開始するために使用できるエンティティを取得します。

このチュートリアルでは、PFAuthenticationReLoginWithXUserAsync API を呼び出して、有効な PFEntityHandle を取得します。

注意

PFAuthenticationLoginWithXUserRequest の一部として渡される userHandle オブジェクトは XUserHandle 型です。 有効な XUserHandle を取得する手順は、このチュートリアルでは範囲外です。 このトピックの詳細については、XUserAddAsync のドキュメントを参照してください。

PFEntityHandle entityHandle;

PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;
request.user = userHandle; // An XUserHandle obtained from XUserAddAsync

XAsyncBlock async{};

HRESULT hr = PFAuthenticationReLoginWithXUserAsync(entityHandle, &request, &async);

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

hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

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

手順 6 - パイプラインへのエンティティの追加

既に有効なエンティティがあるため、PFEventPipelineAddUploadingEntity を呼び出し、前の手順のイベント パイプライン ハンドルとエンティティ ハンドルを渡すことができます。 このアクションにより、パイプラインはエンティティ認証を使用するように切り替えることができます。

HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

手順 7 - イベントの出力

この手順は、前のイベントの送信と同じです。

違いは次の 2 点だけです:

  • わかりやすくするために、このイベントに別の名前 ("EntityEvent") をタグ付けしています。
  • このイベントはログに記録され、以前に取得したエンティティとリンクされます。
PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "EntityEvent",
    nullptr,
    "{}"
};

hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

手順 8 - イベント パイプライン ハンドルを閉じる

最後に、イベントのアップロードが完了したら、パイプライン ハンドルを渡して PFEventPipelineCloseHandle を呼び出すだけです。

PFEventPipelineCloseHandle(handle);

関連項目