事件管道教程

项目
10/04/2023

本文档是分步教程，介绍了如何在 PlayFab 服务 SDK 中使用事件管道功能。

步骤 1 - 初始化 PlayFab 服务 SDK

第一步：使用PFServicesInitialize和PFServiceConfigCreateHandle API 初始化 PF 服务 SDK。

PFServiceConfigCreateHandle API 接收可从 PlayFab Game Manager 的游戏中获取的连接字符串和游戏 ID。

第三个参数是PFServiceConfigHandle结构，表示正在创建的配置。下一步将使用此服务配置句柄。

PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

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

步骤 2 - 创建遥测事件管道

接下来，使用PFEventPipelineCreateTelemetryPipelineHandleWithKey API 创建具有遥测密钥的遥测事件管道。遥测密钥通过 PlayFab Game Manager 创建和管理。

创建 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 指针发送，因此它们使用相应管道类型的默认值。

我们还指定了“中等”压缩级别，设置此属性可压缩正文有效负载，并有助于优化网络资源利用率。

然后，我们继续调用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 仅发出 1 个名为“TelemetryKeyEvent”的事件。

此事件未链接到任何实体，因为到目前为止，我们尚未提供实体身份验证。

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 - 发出事件

此过程与上一个事件提交的过程相同。

唯一的两个区别是：

我们会使用其他名称（“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);

另请参阅

事件管道概述

通过