快速入門：Linux

開始使用適用於 Linux 的 PlayFab Services SDK。請依照下列步驟將程式庫納入您的專案，並試用基本 PlayFab 功能的範例程式碼。本快速入門可協助您使用 Linux 進行第一次 PlayFab API 呼叫。在繼續之前，請確定您已完成快速入門：Game Manager 中的步驟，以確保您擁有 PlayFab 帳戶並熟悉 PlayFab Game Manager。

需求

PlayFab 開發人員帳戶。
Ubuntu 22.04 或更高版本，或搭配 Ubuntu 22.04 或更高版本發行版的 Windows 子系統 Linux 版。請參閱如何使用 WSL 在 Windows 上安裝 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}
)

您的專案現在已完全設定為可使用適用於 Linux 的 PlayFab Services SDK。請依照接下來的步驟，讓一些範例呼叫正常運作。

初始化和登入

標頭

納入 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);

TBD 取得 PFServiceConfigHandle 之後，您就可以使用它進行玩家登入呼叫。在 SDK 中，使用 PFAuthenticationLoginWith*Async 方法，例如 PFAuthenticationLoginWithCustomIDAsync。此函式可讓您使用自訂識別碼將玩家登入 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 服務 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 參考文件

XBOX Services

PlayFab

Linux 快速入門

快速入門：Linux

需求

專案設定

將 PlayFab C SDK 整合至您自己的專案

將二進位檔新增至您的遊戲

新增 .so 檔案

初始化和登入

標頭

初始化

登入

服務呼叫

取得 EntityKey

呼叫 GetFiles

清除

非同步 API 模式

錯誤處理

偵錯

參考

​快速入門：Linux

​需求

​專案設定

​將 PlayFab C SDK 整合至您自己的專案

​將二進位檔新增至您的遊戲

​新增 .so 檔案

​初始化和登入

​標頭

​初始化

​登入

​服務呼叫

​取得 EntityKey

​呼叫 GetFiles

​清除

​非同步 API 模式

​錯誤處理

​偵錯

​參考

快速入門：Linux

需求

專案設定

將 PlayFab C SDK 整合至您自己的專案

將二進位檔新增至您的遊戲

新增 .so 檔案

初始化和登入

標頭

初始化

登入

服務呼叫

取得 EntityKey

呼叫 GetFiles

清除

非同步 API 模式

錯誤處理

偵錯

參考