快速入门：GDK

  • 项目

Microsoft 游戏开发工具包（GDK）的 PlayFab Services SDK 入门。 按照以下步骤将库包含在项目中，并尝试基本 PlayFab 功能的示例代码。

本快速入门可帮助你使用 GDK 进行第一次 PlayFab API 调用。 在继续操作之前，请确保已完成 快速入门：Game Manager中的步骤，这可确保你拥有 PlayFab 帐户并熟悉 PlayFab Game Manager。

要求

项目设置

与其他 GDK 扩展库类似，通过项目属性添加 PlayFab Services SDK。 在项目的配置属性中，在游戏桌面>常规下，选择“游戏扩展库”。 在提示符下，检查 PlayFab.Services.C。

选择 PlayFab.Services.C 扩展库

Init 和 Logging in

标头

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

#include <playfab/services/PFServices.h>

初始化

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

    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后，可以使用它进行玩家登录呼叫。 在 GDK 中，使用 PFAuthenticationLoginWithXUserAsync。 此函数允许您使用 XUserHandle将玩家登录到 PlayFab。 若要详细了解如何获取和管理 XUserHandle 请参阅 用户标识和 XUser。

进行登录调用后，可以使用 XAsyncGetStatus 检查调用的状态。 状态以 E_PENDING 开始，并在调用成功完成后更改为 S_OK。 如果由于某种原因调用失败，状态将反映该失败。 对所有 PlayFab Services 调用的错误处理都以这种方式工作。

除了 S_OK 结果，还可返回 PFEntityHandle。 使用此句柄作为登录玩家进行后续 PlayFab 调用。 它包括以该玩家身份向 PlayFab 服务进行身份验证所需的任何材料。

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

    XAsyncBlock async{};
    HRESULT hr = PFAuthenticationLoginWithXUserAsync(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 = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize);
    loginResultBuffer.resize(bufferSize);

    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithXUserGetResult(&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 模式

GDK 的 PlayFab Services SDK 遵循 GDK 中实现的异步编程模型。 此编程模型涉及使用由 XAsync 库提供的任务和任务队列。 此模型与其他 GDK 函数和扩展（如 Xbox 服务 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 状态代码。 错误状态代码 HRESULT（例如调用 XAsyncGetStatus() 或 PF*Get() API 之一时的 HTTP_E_STATUS_NOT_FOUND）中显示为失败。

若要查看服务返回的详细错误消息，请参阅有关调试的下一部分。 这些详细的错误消息在开发过程中非常有用，以便更好地了解 PlayFab 服务如何响应来自客户端的请求。

调试

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

参考

API 参考文档