> ## 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 匯出 PlayFab 玩家資料以符合 GDPR 規範，內容涵蓋統計資料、物品欄、購買和事件歷程記錄。

# 匯出資料

本文說明如何從 PlayFab 匯出玩家和事件資料。

## 匯出玩家帳戶資料

當您提出匯出玩家資料的要求時，該要求會傳送給**佇列處理代理程式** (與刪除玩家類似)。

[ExportMasterPlayerData](https://learn.microsoft.com/en-us/rest/api/playfab/admin/account-management/export-master-player-data) API 會匯出與指定 `PlayFabId` 相關聯的所有資料，包括您所有遊戲中的資料，例如：

* **統計資料**
* **自訂資料**
* **物品欄**
* \**購買* \*
* **玩家建立的物品/UGC**
* **交易歷程記錄**
* **虛擬貨幣餘額**
* **角色**
* **群組成員資格**
* **發行者資料**
* **認證資料**
* **帳戶連結**
* **好友清單**
* **PlayStream 事件歷程記錄**。

請閱讀[確定您找到所有資料](/zh-TW/services/playfab/data-analytics/privacy-compliance/playfab-gdpr-deleting-and-exporting-player-data)，其中詳細說明如何確保您擁有玩家的所有 PlayFabId。

此 API 會立即傳回 `JobReceiptId`，您應該將其儲存在記錄中以供日後參考。匯出可能需要一些時間才能供下載。

匯出完成後，系統會將包含匯出下載連結的電子郵件傳送至為遊戲設定的通知電子郵件地址。

工作完成也會觸發 [`player_data_exported` PlayStream 事件](/zh-TW/services/playfab/api-references/events/PlayerIdentity/player-data-exported)。該事件包含 `JobReceiptId` 屬性，以及提供匯出資料存取權的 `ExportDownloadUrl` 屬性。使用[搭配 Azure Functions 的自動化規則](/zh-TW/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart#azure-functions-in-automation-rules)或 [Webhook](/zh-TW/services/playfab/data-analytics/acting-data/webhooks-overview)，您可以註冊在您選擇的端點上接收這些事件，並視需要處理。

下列範例示範如何搭配 [C# SDK](/zh-TW/services/playfab/sdks/c-sharp) 使用 Admin API。如果您想使用不同的 SDK，請從 [PlayFab SDK](/zh-TW/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>包含 PlayFab 中所記錄玩家資料的 JSON 檔案。其中包括玩家參與之每個遊戲的資料。</p><p>JSON 文件的結構描述以 OpenAPI 規格提供。請參閱 `https://<your_title_id>.playfabapi.com/Swagger/MasterPlayerDataExport.swagger.json` 中的物件 `MasterPlayerDataExport`</p> |
| /CustomFiles/MasterPlayerFiles/\* | 包含與玩家之 `master_player_account` 實體相關聯的自訂[實體檔案](/zh-TW/services/playfab/live-service-management/game-configuration/entities/entity-files)。 |
| /CustomFiles/TitlePlayerFiles/\<TitlePlayerAccountId>/\* | <p>包含與玩家之 `title_player_account` 實體相關聯的自訂[實體檔案](/zh-TW/services/playfab/live-service-management/game-configuration/entities/entity-files)。</p><p>這些檔案會依玩家參與的每個遊戲組織成一個子目錄。每個子目錄的名稱是玩家在該遊戲中的 `title_player_account` 實體識別碼。</p> |
| /TitlePlayerEvents/\<TitleId>/event-history\_1.jsonl <br />...<br /> /TitlePlayerEvents/\<TitleId>/event-history\_\<N>.jsonl | <p>記錄的玩家相關 PlayStream 和 Telemetry 事件。</p><p>這些檔案會依玩家參與的每個遊戲組織成一個子目錄。每個子目錄的名稱是遊戲識別碼。</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 檔案中找到：

* 「發行者」資料位於 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 實體識別碼作為目錄名稱。
</Note>

您也可以直接下載實體檔案。首先，呼叫 [GetFiles](https://learn.microsoft.com/en-us/rest/api/playfab/data/file/get-files) API 以取得實體檔案的中繼資料。每個檔案中繼資料文件都包含 DownloadUrl 屬性，可用來直接下載檔案。


## Related topics

- [PlayFab GDPR - 刪除和匯出玩家資料](/zh-TW/services/playfab/data-analytics/privacy-compliance/playfab-gdpr-deleting-and-exporting-player-data.md)
- [PlayFab GDPR - 刪除玩家資料](/zh-TW/services/playfab/data-analytics/privacy-compliance/gdpr-deleting-player-data.md)
- [PlayFab 玩家進度文件](/zh-TW/services/playfab/player-progression/index.md)
- [PlayFab 資料與分析文件](/zh-TW/services/playfab/data-analytics/index.md)
- [匯出主要玩家資料](/zh-TW/services/playfab/api-references/rest/admin/account-management/export-master-player-data.md)