> ## 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.

# PlayFab GDPR - 导出玩家数据

> 如何使用 ExportMasterPlayerData 为遵守 GDPR 导出 PlayFab 玩家的数据，涵盖统计、库存、购买和事件历史记录。

# 导出数据

本文介绍如何从 PlayFab 导出玩家和事件数据。

## 导出玩家账户数据

当你发出导出玩家数据的请求时，请求会被发送到**队列处理代理**（类似于删除玩家）。

[ExportMasterPlayerData](https://learn.microsoft.com/en-us/rest/api/playfab/admin/account-management/export-master-player-data) API 导出与给定 `PlayFabId` 关联的所有数据，包括跨你所有标题的数据，例如：

* **统计信息**
* **自定义数据**
* **库存**
* **购买**
* **玩家创建的物品/UGC**
* **交易历史**
* **虚拟货币余额**
* **角色**
* **组成员资格**
* **发布者数据**
* **凭据数据**
* **账户关联**
* **好友列表**
* **PlayStream 事件历史**。

请阅读[确保找到所有数据](/services/playfab/data-analytics/privacy-compliance/playfab-gdpr-deleting-and-exporting-player-data)，其中详细说明了如何确保获得玩家的所有 PlayFabId。

此 API 立即返回一个 `JobReceiptId`，你应将其存储在记录中以供将来参考。导出可供下载可能需要一些时间。

导出完成后，会向为该标题配置的通知电子邮件地址发送包含导出下载链接的电子邮件。

任务的完成还会触发 [`player_data_exported` PlayStream 事件](/services/playfab/api-references/events/PlayerIdentity/player-data-exported)。该事件将 `JobReceiptId` 作为属性，还包含 `ExportDownloadUrl` 属性，可用于访问导出的数据。使用[带 Azure Functions 的自动化规则](/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart#azure-functions-in-automation-rules)或 [Webhook](/services/playfab/data-analytics/acting-data/webhooks-overview)，你可以在你选择的端点上注册接收这些事件，并根据需要处理。

以下示例是如何在 [C# SDK](/services/playfab/sdks/c-sharp) 中使用管理 API。如果你想使用不同的 SDK，请从 [PlayFab SDK](/services/playfab/sdks/playfab-sdk-intro) 列表中选择一个。

```csharp theme={null}
public static async void ExportMasterPlayerExample(Action<PlayFabError> callback)
{
    var task = await PlayFabAdminAPI.ExportMasterPlayerDataAsync(new ExportMasterPlayerDataRequest()
    {
        PlayFabId = PlayFabId
    });

    if(task.Error != null)
    {
        callback(task.Error);
    }

    var jobReceiptId = task.Result.JobReceiptId;

    Console.WriteLine(string.Format("Export Player Request Received - Receipt: {0}", jobReceiptId));

    callback(null);
}
```

<Note>
  URL 在导出完成后最长可用 30 天。此时间之后，文件将被删除，你需要发起*新的*导出请求。
</Note>

## 导出数据的格式

导出的数据被打包在一个 ZIP 归档中，其名称包含 `JobReceiptId` 和导出的时间。归档包含组织成目录结构的多个文件。

| 文件路径                                                                                                                         | 说明                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /master\_player\_export.json                                                                                                 | <p>一个 JSON 文件，包含在 PlayFab 中记录的玩家数据。这包括玩家参与的每个标题的数据。</p><p>JSON 文档的架构以 OpenAPI 规范形式提供。请参阅 `https://<your_title_id>.playfabapi.com/Swagger/MasterPlayerDataExport.swagger.json` 中的对象 `MasterPlayerDataExport`</p>     |
| /CustomFiles/MasterPlayerFiles/\*                                                                                            | 包含与玩家的 `master_player_account` 实体关联的自定义[实体文件](/services/playfab/live-service-management/game-configuration/entities/entity-files)。                                                                                  |
| /CustomFiles/TitlePlayerFiles/\<TitlePlayerAccountId>/\*                                                                     | <p>包含与玩家的 `title_player_account` 实体关联的自定义[实体文件](/services/playfab/live-service-management/game-configuration/entities/entity-files)。</p><p>文件按玩家参与的每个标题组织到一个子目录中。每个子目录的名称是玩家在标题中的 `title_player_account` 实体 ID。</p> |
| /TitlePlayerEvents/\<TitleId>/event-history\_1.jsonl <br />...<br /> /TitlePlayerEvents/\<TitleId>/event-history\_\<N>.jsonl | <p>关于玩家记录的 PlayStream 和遥测事件。</p><p>文件按玩家参与的每个标题组织到一个子目录中。每个子目录的名称是标题 ID。</p><p>每个子目录包含一个或多个 `event-history` 文件，取决于玩家在给定标题中有多少数据。文件包含被序列化为 JSON 对象的事件，每行一个事件。</p>                                                    |

## 导出事件数据

PlayFab 提供多种类型的事件数据——自定义数据、实体对象和实体文件。

### 导出自定义数据

自定义数据指的是一大类允许你将任意数据与玩家关联的功能。PlayFab 提供从游戏逻辑与数据交互的方法，但除此之外不解释或理解这些数据。

#### 旧版玩家数据

在使用 [ExportMasterPlayerData](https://learn.microsoft.com/en-us/rest/api/playfab/admin/account-management/export-master-player-data) API（如"导出 PlayFab 数据"部分所引用）时，所有玩家数据属性都可以在 ZIP 归档根目录的 master\_player\_export.json 文件中找到：

* "Publisher" 数据可以在 JSONPath 找到：\$.PublisherData
* 每个标题的数据可以在 JSONPath 找到：\$.Titles\[\*].CustomData

如果你只需要导出这些值，也可以通过专用的 "get" API 检索这些值。专用 API 的优点是它们会立即返回。但是，根据此功能的设计，需要根据所需数据的特定类型调用正确的 API：

GetUserData、GetUserInternalData、GetUserReadOnlyData、GetUserPublisherData、GetUserPublisherInternalData、GetUserPublisherReadOnlyData

### 导出实体对象

使用 [ExportMasterPlayerData](https://learn.microsoft.com/en-us/rest/api/playfab/admin/account-management/export-master-player-data) API 时，所有实体对象都可以在 ZIP 归档根目录的 **master\_player\_export.json** 文件中找到：

对于 **master\_player\_account** 实体对象，位于 JSONPath：**\$.CustomObjects**

对于 **title\_player\_account** 实体对象，位于 JSONPath：**\$.Titles\[\*].CustomObjects**

对于角色实体对象，位于 JSONPath：**\$.Titles\[*].Characters\[*].CustomObjects**

也可以通过 [GetObjects](https://learn.microsoft.com/en-us/rest/api/playfab/data/object/get-objects) API 检索实体对象。如果你已经知道要查找哪些实体的对象，使用专用 API 可能更容易，因为它会立即返回对象。但是，缺点是需要为玩家的 **master\_player\_account** 实体、每个 **title\_player\_account** 实体以及每个角色实体分别调用 API。

### 导出实体文件

使用 [ExportMasterPlayerData](https://learn.microsoft.com/en-us/rest/api/playfab/admin/account-management/export-master-player-data) API 时，与玩家关联的所有实体文件都按原样添加到 ZIP 归档中的 /CustomFiles/ 目录，具体如下：

对于玩家的 **master\_player\_account** 实体，文件位于 /CustomFiles/MasterPlayerFiles/\*

对于 **title\_player\_account**，文件位于 /CustomFiles/TitlePlayerFiles/\<TitlePlayerAccountId>/\*

<Note>
  每个实体都有一个子目录，目录名为 title\_player\_account 实体 ID。
</Note>

也可以直接下载实体文件。首先，调用 [GetFiles](https://learn.microsoft.com/en-us/rest/api/playfab/data/file/get-files) API 获取实体文件的元数据。每个文件元数据文档都包含一个 DownloadUrl 属性，可用于直接下载文件。