> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入門 (Windows) - 呼叫 PlayFab 服務

> 使用 PlayFab Unified SDK 中已驗證的 PFEntityHandle 擷取實體索引鍵，並從 Windows 遊戲呼叫 PlayFab 服務 API。

本指南說明如何使用 Unified SDK 進行 PlayFab 服務 API 呼叫。您將了解如何呼叫各種 PlayFab 服務來管理玩家資料、擷取檔案，以及與其他 PlayFab 功能互動。

## 必要條件

開始之前，請確定您已：

* 完成 [Core SDK 設定和驗證](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-core)
* 從登入程序取得已驗證的 `PFEntityHandle`
* 設定好您的 PlayFab 遊戲識別碼和服務設定

<Note>
  本指南假設您已依照 [Core 快速入門指南](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-core)初始化 PlayFab SDK 並驗證了玩家。如果您尚未這麼做，請先完成該指南。
</Note>

## 您將完成的工作

完成本快速入門之後，您將會：

* 擷取已驗證玩家的實體索引鍵
* 進行您的第一次 PlayFab 服務 API 呼叫
* 處理來自 PlayFab 服務的回應

## 進行您的第一次服務 API 呼叫

驗證成功之後，您可以使用登入期間取得的 `PFEntityHandle` 進行 PlayFab API 呼叫。此範例示範如何擷取為目前玩家儲存的檔案。

### 步驟 1：取得實體索引鍵

首先，從已驗證的實體控制代碼擷取實體索引鍵：

```cpp theme={null}
PFEntityKey const* pEntityKey{};
std::vector<char> entityKeyBuffer;
size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get entity key size: 0x" << std::hex << hr << std::endl;
    return hr;
}

entityKeyBuffer.resize(size);
hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), 
    entityKeyBuffer.data(), &pEntityKey, nullptr);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get entity key: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"Entity ID: " << pEntityKey->id << std::endl;
```

### 步驟 2：呼叫 GetFiles API

現在進行您的第一次 PlayFab 服務呼叫，以取得與玩家相關聯的檔案：

```cpp theme={null}
// Prepare the request
XAsyncBlock async{};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = pEntityKey;  // Use the entity key from above

// Make the async API call
HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async);
if (FAILED(hr))
{
    std::wcerr << L"Failed to start GetFiles request: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Wait for the call to complete
hr = XAsyncGetStatus(&async, true);
if (FAILED(hr))
{
    std::wcerr << L"GetFiles request failed: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Get the result size and allocate buffer
size_t resultSize;
hr = PFDataGetFilesGetResultSize(&async, &resultSize);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get result size: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Retrieve the actual result
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), 
    getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
if (SUCCEEDED(hr))
{
    std::wcout << L"Successfully retrieved files. Count: " 
               << (getFilesResponseResult->metadata ? getFilesResponseResult->metadataCount : 0) 
               << std::endl;
    
    // Process the files as needed
    if (getFilesResponseResult->metadata)
    {
        for (uint32_t i = 0; i < getFilesResponseResult->metadataCount; ++i)
        {
            std::wcout << L"File: " << getFilesResponseResult->metadata[i].fileName << std::endl;
        }
    }
}
else
{
    std::wcerr << L"Failed to get GetFiles result: 0x" << std::hex << hr << std::endl;
}
```

🎉 **恭喜！** 您已成功使用 Unified SDK 進行第一次 PlayFab 服務 API 呼叫。

## 了解 API 呼叫模式

所有 PlayFab 服務 API 呼叫都遵循類似的模式：

1. **準備要求** - 建立並填入要求結構
2. **起始非同步呼叫** - 呼叫 `*Async` 函式
3. **等待完成** - 使用 `XAsyncGetStatus` 等待作業
4. **取得結果大小** - 呼叫 `*GetResultSize` 以決定緩衝區需求
5. **擷取結果** - 呼叫 `*GetResult` 以取得實際資料

此模式適用於所有 PlayFab 服務 API，因此只要了解基本概念，就能輕鬆使用不同的服務。

## 後續步驟

現在您已成功呼叫 PlayFab 服務，請探索這些其他功能：

### 常見服務 API

* **玩家資料管理** - 儲存和擷取自訂玩家資料
* **玩家統計資料** - 追蹤玩家統計資料和成就
* **遊戲資料** - 存取遊戲設定資料
* **Cloud Script** - 執行伺服器端邏輯

### 進階功能

* **排行榜** - 透過排名實作競爭性功能
* **經濟和營利** - 新增虛擬貨幣和物品
* **多人遊戲** - 整合配對和大廳服務
* **分析** - 追蹤玩家行為和遊戲計量

### 最佳做法

* [非同步作業](/zh-TW/services/playfab/sdks/unified-sdk/async-model) - 了解 PlayFab 的非同步程式設計模型
* [記憶體管理](/zh-TW/services/playfab/sdks/unified-sdk/memory-management) - 管理 SDK 記憶體的最佳做法
* [追蹤和診斷](/zh-TW/services/playfab/sdks/unified-sdk/debug-trace) - 偵錯和監視您的整合

## 疑難排解

**常見問題和解決方案：**

| 問題 | 解決方案 |
| - | - |
| 無效的實體控制代碼 | 確定您已成功完成驗證 |
| API 呼叫逾時 | 檢查網路連線和 PlayFab 服務狀態 |
| 存取遭拒錯誤 | 確認您的遊戲識別碼和實體權限 |
| 緩衝區大小錯誤 | 一律在 `*GetResult` 之前呼叫 `*GetResultSize` |

如需更詳細的錯誤資訊，請在您的應用程式中啟用[追蹤和診斷](/zh-TW/services/playfab/sdks/unified-sdk/debug-trace)。

## 參考文件

* [PlayFab Unified SDK API 參考](/zh-TW/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [PlayFab Services API 參考](/zh-TW/services/playfab/api-references)
* [PlayFab Data API 文件](https://docs.microsoft.com/gaming/playfab/api-references/data/)


## Related topics

- [Unity 快速入門](/zh-TW/services/playfab/sdks/unity3d/quickstart.md)
- [快速入門 (Windows) - Core SDK 設定](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-core.md)
- [Android 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-android.md)
- [GDK 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-gdk.md)
- [iOS 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-ios.md)