> ## 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 统一 SDK 中已通过身份验证的 PFEntityHandle，从 Windows 游戏中检索实体键并调用 PlayFab 服务 API。

本指南向您展示如何使用统一 SDK 进行 PlayFab 服务 API 调用。您将学习如何调用各种 PlayFab 服务来管理玩家数据、检索文件以及与其他 PlayFab 功能进行交互。

## 先决条件

在开始之前，请确保您已：

* 完成 [Core SDK 设置和身份验证](/services/playfab/sdks/unified-sdk/quickstart-core)
* 在登录流程中获得已通过身份验证的 `PFEntityHandle`
* 设置了 PlayFab Title ID 和服务配置

<Note>
  本指南假设您已按照 [Core 快速入门指南](/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;
}
```

🎉 \*\*恭喜！\*\*您已成功使用统一 SDK 进行了第一次 PlayFab 服务 API 调用。

## 理解 API 调用模式

所有 PlayFab 服务 API 调用都遵循相似的模式：

1. **准备请求** - 创建并填充请求结构体
2. **发起异步调用** - 调用 `*Async` 函数
3. **等待完成** - 使用 `XAsyncGetStatus` 等待操作完成
4. **获取结果大小** - 调用 `*GetResultSize` 以确定缓冲区需求
5. **检索结果** - 调用 `*GetResult` 以获取实际数据

一旦理解了基础，此模式适用于所有 PlayFab 服务 API，从而可以方便地使用不同的服务。

## 后续步骤

现在您已成功调用了 PlayFab 服务，可以探索这些附加功能：

### 常见服务 API

* **玩家数据管理** - 存储和检索自定义玩家数据
* **玩家统计** - 跟踪玩家统计数据和成就
* **Title Data** - 访问游戏配置数据
* **Cloud Script** - 执行服务器端逻辑

### 高级功能

* **排行榜** - 通过排名实现竞争性功能
* **经济和货币化** - 添加虚拟货币和物品
* **多人游戏** - 集成匹配和大厅服务
* **分析** - 跟踪玩家行为和游戏指标

### 最佳实践

* [异步操作](/services/playfab/sdks/unified-sdk/async-model) - 了解 PlayFab 的异步编程模型
* [内存管理](/services/playfab/sdks/unified-sdk/memory-management) - 管理 SDK 内存的最佳实践
* [跟踪与诊断](/services/playfab/sdks/unified-sdk/debug-trace) - 调试和监控您的集成

## 故障排除

**常见问题及解决方案：**

| 问题       | 解决方案                                   |
| -------- | -------------------------------------- |
| 无效的实体句柄  | 确保您已成功完成身份验证                           |
| API 调用超时 | 检查网络连接和 PlayFab 服务状态                   |
| 访问被拒绝错误  | 验证您的 Title ID 和实体权限                    |
| 缓冲区大小错误  | 在 `*GetResult` 之前始终调用 `*GetResultSize` |

有关更详细的错误信息，请在应用程序中启用[跟踪与诊断](/services/playfab/sdks/unified-sdk/debug-trace)。

## 参考文档

* [PlayFab 统一 SDK API 参考](/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [PlayFab Services API 参考](/services/playfab/api-references)
* [PlayFab Data API 文档](https://docs.microsoft.com/gaming/playfab/api-references/data/)


## Related topics

- [Unity 快速入门](/zh-CN/services/playfab/sdks/unity3d/quickstart.md)
- [快速入门 (Windows) - Core SDK 设置](/zh-CN/services/playfab/sdks/unified-sdk/quickstart-core.md)
- [快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Android 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-android.md)
- [GDK 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-gdk.md)