快速入門：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 中開啟 [屬性管理員] 視窗，以滑鼠右鍵按一下專案，然後選擇 Add Existing Property Sheet。

疑難排解

如果您在專案中連結 SDK 時遇到問題，可能需要透過 Visual Studio 安裝程式安裝 17.5 建置工具和程式庫。針對 VS2022 按一下 Modify，然後安裝這兩個元件。

初始化和登入

標頭

納入 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 之後，您就可以使用它進行玩家登入呼叫。在 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 服務 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

Win32 快速入門

快速入門：Win32

需求

專案設定

疑難排解

初始化和登入

標頭

初始化

登入

服務呼叫

取得 EntityKey

呼叫 GetFiles

清除

非同步 API 模式

錯誤處理

偵錯

參考

​快速入門：Win32

​需求

​專案設定

​疑難排解

​初始化和登入

​標頭

​初始化

​登入

​服務呼叫

​取得 EntityKey

​呼叫 GetFiles

​清除

​非同步 API 模式

​錯誤處理

​偵錯

​參考

快速入門：Win32

需求

專案設定

疑難排解

初始化和登入

標頭

初始化

登入

服務呼叫

取得 EntityKey

呼叫 GetFiles

清除

非同步 API 模式

錯誤處理

偵錯

參考