實體控制代碼

PFEntityHandle 是您進行 PlayFab 服務呼叫的主要認證。它代表一個已驗證的實體 (玩家 (title_player_account) 或遊戲)，並保存 SDK 授權要求所需的實體權杖。每個登入或驗證呼叫都會傳回 PFEntityHandle，而每個服務呼叫都需要一個。

取得實體控制代碼

您不會直接建立實體控制代碼，而是在成功的登入或驗證呼叫中以輸出的形式取得。 玩家登入 (Windows 範例)：

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

XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &async);
hr = XAsyncGetStatus(&async, true);

PFEntityHandle entityHandle{ nullptr };
size_t bufferSize{};
hr = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize);

std::vector<char> loginResultBuffer(bufferSize);
PFAuthenticationLoginResult const* loginResult{};
hr = PFAuthenticationLoginWithXUserGetResult(
    &async, &entityHandle,
    loginResultBuffer.size(), loginResultBuffer.data(),
    &loginResult, nullptr);

遊戲實體 (伺服器)： 遊戲實體使用祕密金鑰而非使用者認證進行驗證。傳回的 PFEntityHandle 運作方式相同，但它代表的是遊戲而非玩家。如需詳細資訊，請參閱使用遊戲實體存取 PlayFab。

控制代碼擁有權和參考計數

PFEntityHandle 會進行參考計數。當您從登入呼叫收到控制代碼時，您擁有一個參考。您可以使用 PFEntityDuplicateHandle 建立其他參考，並使用 PFEntityCloseHandle 釋放它們。只有在最後一個參考關閉時，基礎實體物件才會被終結。 規則：

每次呼叫登入 GetResult 函式或 PFEntityDuplicateHandle 都會給您一個必須關閉的控制代碼。
關閉某個控制代碼不會讓同一實體的其他控制代碼失效。
在呼叫 PFServicesUninitializeAsync 之前關閉所有控制代碼。

// Duplicate a handle for another component
PFEntityHandle secondHandle{ nullptr };
HRESULT hr = PFEntityDuplicateHandle(entityHandle, &secondHandle);

// Both handles are independently valid
// ...

// Each owner closes their own handle
PFEntityCloseHandle(secondHandle);
PFEntityCloseHandle(entityHandle);

取得實體資訊

實體索引鍵

實體索引鍵會識別實體 (其類型和識別碼)。請使用兩次呼叫模式：先取得大小，再取得資料。

size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size);

std::vector<char> buffer(size);
PFEntityKey const* entityKey{};
hr = PFEntityGetEntityKey(entityHandle, buffer.size(), buffer.data(), &entityKey, nullptr);

// entityKey->type is "title_player_account" for players
// entityKey->id is the entity's unique ID

實體權杖

實體權杖會授權服務呼叫。SDK 會自動管理權杖，但您可以視需要擷取目前的權杖。

XAsyncBlock async{};
HRESULT hr = PFEntityGetEntityTokenAsync(entityHandle, &async);
hr = XAsyncGetStatus(&async, true);

size_t size{};
hr = PFEntityGetEntityTokenResultSize(&async, &size);

std::vector<char> buffer(size);
const PFEntityToken* entityToken{};
hr = PFEntityGetEntityTokenResult(&async, buffer.size(), buffer.data(), &entityToken, nullptr);

// entityToken->token is the token string
// entityToken->expiration is the optional expiration time (UTC)

檢查實體類型

使用 PFEntityIsTitlePlayer 進行快速檢查，而不需檢查實體索引鍵類型字串：

bool isTitlePlayer{};
HRESULT hr = PFEntityIsTitlePlayer(entityHandle, &isTitlePlayer);

玩家實體與遊戲實體

玩家實體和遊戲實體都使用 PFEntityHandle，但它們能做的事情有所不同：

	玩家實體	遊戲實體
取得方式	登入呼叫 (例如 `PFAuthenticationLoginWithXUserAsync`)	`PFAuthenticationGetEntityWithSecretKeyAsync`
實體類型	`title_player_account`	`title`
PFEntityIsTitlePlayer	傳回 `true`	傳回 `false`
PFEntityGetSecretKey	失敗並傳回 `E_PF_NOSECRETKEY`	傳回祕密金鑰
可用的 API	具有 Client 前置詞和沒有前置詞的 API	具有 Server 前置詞和沒有前置詞的 API

沒有前置詞的 API (例如 Inventory、Leaderboards、Data) 通常可由玩家實體和遊戲實體呼叫，除非其文件中另有說明。具有 Client 前置詞的 API 僅限玩家使用，而具有 Server 前置詞的 API 僅限遊戲使用。 PFEntityGetSecretKey 會擷取與遊戲實體相關聯的祕密金鑰。對於玩家實體，它會失敗，因為玩家實體沒有祕密金鑰。

size_t keySize{};
HRESULT hr = PFEntityGetSecretKeySize(entityHandle, &keySize);
if (SUCCEEDED(hr))
{
    std::vector<char> secretKey(keySize);
    hr = PFEntityGetSecretKey(entityHandle, secretKey.size(), secretKey.data(), nullptr);
}

PFEntityGetSecretKey 僅適用於 Windows、Linux 和 macOS 平台。

權杖事件處理常式

SDK 會在實體權杖到期之前自動重新整理。您可以註冊回呼來觀察這些事件。

權杖已到期

如果自動重新整理失敗 (例如，原始登入認證已不再有效)，SDK 會引發權杖到期事件。請註冊處理常式以提供新的認證並重試登入。

PFRegistrationToken registrationToken{};
HRESULT hr = PFEntityRegisterTokenExpiredEventHandler(
    nullptr,  // XTaskQueueHandle, or nullptr for default
    nullptr,  // optional context
    [](void* ctx, PFEntityKey const* entityKey)
    {
        // Re-authenticate the player with a fresh credential
        // See relogin.md for a complete example
    },
    &registrationToken);

權杖已重新整理

如果您想知道 SDK 何時在背景中成功重新整理權杖，請註冊權杖已重新整理處理常式。這僅供參考，您不需要採取任何動作。

PFRegistrationToken registrationToken{};
HRESULT hr = PFEntityRegisterTokenRefreshedEventHandler(
    nullptr,  // XTaskQueueHandle, or nullptr for default
    nullptr,  // optional context
    [](void* ctx, PFEntityKey const* entityKey, const PFEntityToken* newToken)
    {
        // Log the refresh or update cached token references
    },
    &registrationToken);

何時註冊和取消註冊

請及早註冊處理常式，也就是在 SDK 初始化之後、登入之前。這可確保您不會遺漏任何事件。
請在關閉期間、關閉實體控制代碼之前取消註冊處理常式。

PFEntityUnregisterTokenExpiredEventHandler(expiredRegistrationToken);
PFEntityUnregisterTokenRefreshedEventHandler(refreshedRegistrationToken);

如需權杖到期處理和重新登入的完整逐步解說，請參閱處理權杖到期。

公用程式存取子

您可以從實體控制代碼擷取 API 端點和遊戲識別碼。這些值來自登入期間所使用的 PFServiceConfigHandle。

// Get API endpoint
size_t endpointSize{};
HRESULT hr = PFEntityGetAPIEndpointSize(entityHandle, &endpointSize);

std::vector<char> endpoint(endpointSize);
hr = PFEntityGetAPIEndpoint(entityHandle, endpoint.size(), endpoint.data(), nullptr);

// Get title ID
size_t titleIdSize{};
hr = PFEntityGetTitleIdSize(entityHandle, &titleIdSize);

std::vector<char> titleId(titleIdSize);
hr = PFEntityGetTitleId(entityHandle, titleId.size(), titleId.data(), nullptr);

完整範例

此範例示範如何建立、複製、查詢和關閉實體控制代碼：

#include <playfab/core/PFEntity.h>
#include <playfab/services/PFServices.h>

void EntityHandleExample(PFServiceConfigHandle serviceConfigHandle, XUserHandle userHandle)
{
    //
    // Log in and get an entity handle
    //
    PFAuthenticationLoginWithXUserRequest request{};
    request.createAccount = true;
    request.user = userHandle;

    XAsyncBlock asyncLogin{};
    HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &asyncLogin);
    hr = XAsyncGetStatus(&asyncLogin, true);

    PFEntityHandle entityHandle{ nullptr };
    size_t resultSize{};
    hr = PFAuthenticationLoginWithXUserGetResultSize(&asyncLogin, &resultSize);

    std::vector<char> loginBuffer(resultSize);
    PFAuthenticationLoginResult const* loginResult{};
    hr = PFAuthenticationLoginWithXUserGetResult(
        &asyncLogin, &entityHandle,
        loginBuffer.size(), loginBuffer.data(),
        &loginResult, nullptr);

    //
    // Register token event handlers
    //
    PFRegistrationToken expiredToken{};
    hr = PFEntityRegisterTokenExpiredEventHandler(nullptr, nullptr,
        [](void* ctx, PFEntityKey const* entityKey)
        {
            // Handle re-authentication
        }, &expiredToken);

    PFRegistrationToken refreshedToken{};
    hr = PFEntityRegisterTokenRefreshedEventHandler(nullptr, nullptr,
        [](void* ctx, PFEntityKey const* entityKey, const PFEntityToken* newToken)
        {
            // Log token refresh
        }, &refreshedToken);

    //
    // Duplicate the handle for a subsystem
    //
    PFEntityHandle subsystemHandle{ nullptr };
    hr = PFEntityDuplicateHandle(entityHandle, &subsystemHandle);

    //
    // Query entity info
    //
    bool isTitlePlayer{};
    hr = PFEntityIsTitlePlayer(entityHandle, &isTitlePlayer);

    size_t keySize{};
    hr = PFEntityGetEntityKeySize(entityHandle, &keySize);

    std::vector<char> keyBuffer(keySize);
    PFEntityKey const* entityKey{};
    hr = PFEntityGetEntityKey(entityHandle, keyBuffer.size(), keyBuffer.data(), &entityKey, nullptr);

    //
    // ... make service calls with entityHandle or subsystemHandle ...
    //

    //
    // Cleanup: unregister handlers, then close all handles
    //
    PFEntityUnregisterTokenExpiredEventHandler(expiredToken);
    PFEntityUnregisterTokenRefreshedEventHandler(refreshedToken);

    PFEntityCloseHandle(subsystemHandle);
    PFEntityCloseHandle(entityHandle);
}

API 參考

函式	描述
PFEntityDuplicateHandle	複製控制代碼，並遞增參考計數。這兩個控制代碼都必須分別關閉。
PFEntityCloseHandle	關閉控制代碼，並遞減參考計數。當最後一個控制代碼關閉時，實體會被終結。
PFEntityGetEntityKeySize	取得儲存實體索引鍵所需的緩衝區大小。
PFEntityGetEntityKey	取得實體的實體索引鍵 (類型和識別碼)。
PFEntityGetEntityTokenAsync	以非同步方式擷取快取的實體權杖。
PFEntityGetEntityTokenResultSize	取得實體權杖結果所需的緩衝區大小。
PFEntityGetEntityTokenResult	從已完成的 PFEntityGetEntityTokenAsync 呼叫取得實體權杖。
PFEntityIsTitlePlayer	傳回實體是否為 title_player_account。
PFEntityGetSecretKeySize	取得祕密金鑰所需的緩衝區大小。如果實體不是遊戲實體，則會失敗。
PFEntityGetSecretKey	取得遊戲實體的祕密金鑰。僅適用於 Windows、Linux 和 macOS。
PFEntityGetAPIEndpointSize	取得 API 端點字串所需的緩衝區大小。
PFEntityGetAPIEndpoint	從實體相關聯的服務設定取得 API 端點。
PFEntityGetTitleIdSize	取得遊戲識別碼字串所需的緩衝區大小。
PFEntityGetTitleId	從實體相關聯的服務設定取得遊戲識別碼。
PFEntityRegisterTokenExpiredEventHandler	註冊在自動權杖重新整理失敗時的回呼。
PFEntityUnregisterTokenExpiredEventHandler	取消註冊權杖到期回呼。
PFEntityRegisterTokenRefreshedEventHandler	註冊在 SDK 成功重新整理權杖時的回呼。
PFEntityUnregisterTokenRefreshedEventHandler	取消註冊權杖已重新整理回呼。

如需完整的 API 參考，請參閱 PFEntity 成員。

XBOX Services

PlayFab

取得實體控制代碼

控制代碼擁有權和參考計數

取得實體資訊

實體索引鍵

實體權杖

檢查實體類型

玩家實體與遊戲實體

權杖事件處理常式

權杖已到期

權杖已重新整理

何時註冊和取消註冊

公用程式存取子

完整範例

API 參考

另請參閱

​取得實體控制代碼

​控制代碼擁有權和參考計數

​取得實體資訊

​實體索引鍵

​實體權杖

​檢查實體類型

​玩家實體與遊戲實體

​權杖事件處理常式

​權杖已到期

​權杖已重新整理

​何時註冊和取消註冊

​公用程式存取子

​完整範例

​API 參考

​另請參閱

取得實體控制代碼

控制代碼擁有權和參考計數

取得實體資訊

實體索引鍵

實體權杖

檢查實體類型

玩家實體與遊戲實體

權杖事件處理常式

權杖已到期

權杖已重新整理

何時註冊和取消註冊

公用程式存取子

完整範例

API 參考

另請參閱