快速入门：Win32

开始使用适用于 Win32 的 PlayFab Services SDK。按以下步骤将库包含到你的项目中，并试用基本 PlayFab 功能的示例代码。本快速入门帮助你使用 Win32 SDK 进行第一次 PlayFab API 调用。在继续之前，请确保已完成快速入门：Game Manager 中的步骤，以确保你拥有 PlayFab 账户并熟悉 PlayFab Game Manager。

要求

一个 PlayFab 开发者账户。
已安装 Visual Studio 2022。

项目设置

从 PlayFab SDK 发布页面将 PlayFab SDK 下载到你的项目中。将 PlayFabServicesSDK.Win32.props 导入到你的项目中。你可以在项目文件中手动执行此操作，或者在 Visual Studio 中打开 Property Manager 窗口，右键点击项目，然后选择 Add Existing Property Sheet。

故障排除

如果在项目中链接 SDK 时遇到问题，你可能需要通过 Visual Studio Installer 安装 17.5 build tools 和 libs。为 VS2022 点击 Modify，并安装这两个组件。

初始化和登录

头文件

包含 PFServices.h 以访问所有内置的 PlayFab 功能：

#include <playfab/services/PFServices.h>

初始化

PlayFab 初始化需要两个函数调用：PFServicesInitialize 和 PFServiceConfigCreateHandle。此初始化的结果是一个 PFServiceConfigHandle。你将此句柄提供给后续的登录调用，将调用指向 PlayFab 后端中正确的 title。

    HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true

    PFServiceConfigHandle serviceConfigHandle{ nullptr };

    hr = PFServiceConfigCreateHandle(
            "https://ABCDEF.playfabapi.com",    // PlayFab API endpoint - obtained in the Game Manager
            "ABCDEF",                           // PlayFab Title id - obtained in the Game Manager
            &serviceConfigHandle);

一旦你有了 PFServiceConfigHandle，就可以用它进行玩家登录调用。在 SDK 中，使用 PFAuthenticationReLoginWith*Async 方法，例如 PFAuthenticationLoginWithSteamAsync。此函数允许你使用 SteamTicket 将玩家登录到 PlayFab。进行登录调用后，可以使用 XAsyncGetStatus 检查调用状态。状态开始为 E_PENDING，调用成功完成后变为 S_OK。如果调用因某种原因失败，状态会反映该失败。所有 PlayFab Services 调用的错误处理方式都是这样。与 S_OK 结果一起，你会得到一个 PFEntityHandle。你使用此句柄以登录玩家的身份进行后续 PlayFab 调用。它包含以该玩家身份对 PlayFab 服务进行身份验证所需的任何材料。

    PFAuthenticationLoginWithSteamRequest request{};
    request.createAccount = true;
    request.steamTicket = steamTicket; // A ticket obtained from Steam

    XAsyncBlock async{};
    HRESULT hr = PFAuthenticationLoginWithSteamAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
    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

    std::vector<char> loginResultBuffer;
    PFAuthenticationLoginResult const* loginResult;
    size_t bufferSize;
    hr = PFAuthenticationLoginWithSteamGetResultSize(&async, &bufferSize);
    loginResultBuffer.resize(bufferSize);

    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithSteamGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);

服务调用

玩家登录后，你现在可以对 PlayFab 后端进行调用。以下是一个获取存储在 PlayFab 中当前玩家文件的调用示例。

获取 EntityKey

对于某些 PlayFab 调用来说，知道玩家的 PFEntityKey 会很有用。一旦你有了 PFEntityToken，就可以使用 PFEntityGetEntityKey 检索 PFEntityKey。

    PFEntityKey const* pEntityKey{};
    std::vector<char> entityKeyBuffer;
    size_t size{};
    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true

    entityKeyBuffer.resize(size);
    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);

调用 GetFiles

所有 PlayFab 调用都遵循类似的模式：准备请求对象、进行调用（使用登录得到的 PFEntityHandle）、创建接收响应的对象，然后调用 GetResult 函数以填充新创建的容器。

    XAsyncBlock async{};
    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = pEntityKey;

    HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
    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

    size_t resultSize;
    hr = PFDataGetFilesGetResultSize(&async, &resultSize);

    std::vector<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);

清理

当你的游戏准备关闭或你出于其他原因需要清理 PlayFab 时，请确保关闭所有已打开的句柄并调用 PFServicesUninitializeAsync。

    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    XAsyncBlock async{};
    HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
    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

异步 API 模式

PlayFab Services SDK 遵循 GDK 中实现的异步编程模型。此编程模型涉及使用由 XAsync 库提供的任务和任务队列。此模型与其他 GDK 函数和扩展（如 XBOX Services API）保持一致。虽然它引入了一些复杂性，但也带来了对异步操作的高度控制。以下示例展示了如何对 PFDataGetFilesAsync 进行异步调用。

    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getFilesResultBuffer(resultSize);
            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
        }
    };

    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = m_pEntityKey;
    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
    if (SUCCEEDED(hr))
    {
        async.release(); // at this point, the callback will be called so release the unique ptr
    }

错误处理

已完成的 XAsync 操作返回 HTTP 状态代码。错误状态代码在调用 XAsyncGetStatus() 或某个 PF*Get() API 时表现为失败的 HRESULT，例如 HTTP_E_STATUS_NOT_FOUND。要查看服务返回的详细错误消息，请参阅下一节关于调试的内容。这些详细的错误消息在开发期间可用于更好地理解 PlayFab 服务对客户端请求的反应。

调试

查看结果并调试 PlayFab Services SDK 中任何调用的最简单方法是启用调试跟踪。启用调试跟踪后，你既可以在调试器输出窗口中看到结果，也可以将结果挂接到自己游戏的日志中。

参考

API 参考文档

​快速入门：Win32

​要求

​项目设置

​故障排除

​初始化和登录

​头文件

​初始化

​登录

​服务调用

​获取 EntityKey

​调用 GetFiles

​清理

​异步 API 模式

​错误处理

​调试

​参考