快速入门：Linux

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

要求

一个 PlayFab 开发者账户。
Ubuntu 22.04 或更高版本，或者带有 Ubuntu 22.04 或更高版本发行版的 Windows Subsystem for Linux。请参阅如何在 Windows 上使用 WSL 安装 Linux。其他 Linux 发行版应该可以工作但尚未验证。

项目设置

从 PlayFab SDK 发布页面将 PlayFab Linux SDK 下载到你的项目中。

将 PlayFab C SDK 集成到你自己的项目中

将二进制文件添加到你的游戏

你需要将共享对象文件（.so）集成到你的项目中。你可以自己构建这些二进制文件，或从发布页面下载。以下步骤假定你已创建了一个新项目。

添加 .so 文件

这些文件通过 CMake 集成到你的项目中。

解压 PlayFab SDK for Linux 发布包并将其内容放到你想要的目录。
使用 target_include_directories 或其他等效函数，添加 PlayFab SDK 发布包中的以下头文件列表：

例如：

target_include_directories(
    [YOUR PROJECT NAME]
    "[LOCATION OF PLAYFAB LINUX SDK]/include"
)

使用 target_link_libraries 或其他等效函数，将 .so 文件的位置链接到你的项目。

例如：

set(PLAYFAB_SERVICES_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabServices.Linux.so")
set(PLAYFAB_CORE_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabCore.Linux.so")
set(LIBHTTPCLIENT_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/libHttpClient.Linux.so")

target_link_librariesc(
    [YOUR PROJECT NAME]
    ${PLAYFAB_SERVICES_PATH}
    ${PLAYFAB_CORE_PATH}
    ${LIBHTTPCLIENT_PATH}
)

你的项目现已完全设置为使用 PlayFab Services SDK for Linux。按照下面的步骤让一些示例调用运行起来。

初始化和登录

头文件

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

    PFAuthenticationLoginWithCustomIDRequest request{};
    request.createAccount = true;
    request.customId = "player1";

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

    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithCustomIDGetResult(&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 参考文档

​快速入门：Linux

​要求

​项目设置

​将 PlayFab C SDK 集成到你自己的项目中

​将二进制文件添加到你的游戏

​添加 .so 文件

​初始化和登录

​头文件

​初始化

​登录

​服务调用

​获取 EntityKey

​调用 GetFiles

​清理

​异步 API 模式

​错误处理

​调试

​参考