> ## 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. # XGameSave API 概觀 > XBOX XGameSave API 參考，涵蓋容器與 Blob 模型、提供者初始化、更新控制代碼、不可部分完成的更新與同步流程圖。 本文說明容器與 Blob 模型，並涵蓋提供者初始化、提供者關閉與更新控制代碼生命週期。內容概述不可部分完成的更新行為，並附有同步流程圖。本文也提供檔案大小與配額限制，以及最佳做法和常見問題。 `XGameSave` API 可讓您管理 Blob 與容器，以管理 Game Saves 資料。對於 Microsoft Game Development Kit (GDK) 遊戲的 Game Saves，我們建議使用 [XGameSaveFiles](/zh-TW/build/core-features/common/game-save/xgamesavefiles)。如果無法使用 `XGameSaveFiles`，請使用 `XGameSave`。 如需 XGameSave 的系統 API 參考，請參閱 [XGameSave (API 內容)](/zh-TW/reference/system/xgamesave/xgamesave_members)。 下列詞彙經常出現在 `XGameSave` 中。 * **鎖定**：一種機制，可針對特定使用者在其目前使用的裝置上，授與對遊戲 Game Saves 的獨佔存取權。它可確保在持有鎖定期間，沒有其他裝置可以修改該使用者的 Game Saves。 * 例如，如果使用者在裝置 A 上玩遊戲 T，裝置 A 就會為該使用者持有遊戲 T 的鎖定。 * **提供者**：與 Game Save 系統通訊並負責管理遊戲資料的中介處理程序。提供者也會管理使用者在裝置上的鎖定。 * **容器**：類似於資料夾。 * **Blob**：類似於個別檔案。 ## 提供者管理 若要取得儲存空間，遊戲必須初始化提供者。連線之後，遊戲會呼叫 `XGameSaveInitializeProvider` 或 `XGameSaveInitializeProviderAsync`，嘗試取得遊戲雲端儲存空間的鎖定。 如果遊戲因連線中斷而無法從雲端同步，請決定使用者是否可以在離線模式下繼續遊玩。 當遊戲暫停或終止時，遊戲必須使用 [XGameSaveCloseProvider](/zh-TW/reference/system/xgamesave/functions/xgamesavecloseprovider) 關閉提供者。提供者無法跨暫停/繼續界限重複使用。 此問題僅適用於 `XGameSave`。`XGameSaveFiles` 會自動關閉提供者。 ## 容器管理 為了避免在存取容器時遺失資料 (例如在同步完成之前建立容器)，請呼叫 `XGameSaveEnumerateContainerInfo` 或 `XGameSaveEnumerateContainerInfoByName` 來檢視使用者擁有的容器。 使用 `XGameSaveCreateContainer` 取得新的或現有容器的容器控制代碼。如果容器已存在，會提供其控制代碼。如果容器不存在，會建立新容器並提供其控制代碼。 使用 `XGameSaveDeleteContainer` 刪除容器。容器內的所有 Blob 也會一併刪除。 為了防止控制代碼流失，當容器不再使用，或遊戲暫停或終止時，請使用 `XGameSaveCloseContainer` 關閉所有容器控制代碼。 ## Blob 管理 呼叫 `XGameSaveCreateUpdate` 即可操作容器內的資料。 下列詳細資料概述 `XGameSaveUpdate` 如何管理容器內的 Blob 變更，以及如何建立、修改與提交每個更新。 * 一個更新會套用到一個容器。 * 一個更新最多可寫入 GS\_MAX\_BLOB\_SIZE (16 MB)。 * 單一更新中可以修改多個 Blob。 * 每個更新中，單一 Blob 只能有一項修改。 * 提交更新會耗用 `XGameSaveUpdate` 控制代碼。無論提交成功或失敗，都請關閉控制代碼。 * 更新是不可部分完成的。如果其中任何部分失敗，整個更新就會失敗。 * `XGameSaveCreateUpdate` 會建立更新內容，以儲存您所有的 Blob 修改。 * `XGameSaveSubmitBlobWrite` 會將資料寫入新的或現有的 Blob，並需要更新內容。 * `XGameSaveSubmitBlobDelete` 會刪除 Blob。 * `XGameSaveSubmitUpdate` 會提交更新內容。 * `XGameSaveCloseUpdate` 會關閉更新控制代碼。遊戲在每次提交後都會呼叫它，以防止流失。 * 使用 `XGameSaveEnumerateBlobInfo` 或 `XGameSaveEnumerateBlobInfoByName` 存取容器中的所有 Blob。 以 XML 匯出資料時，寫入 Blob 的資料會以 `Base64` 表示。 ## 實作 下列步驟顯示 `XGameSave` 實作的一般流程。 1. 在遊戲啟動或繼續時，初始化提供者。 2. 列舉並建立容器控制代碼。 3. 定期提交包含 Blob 修改的 `XGameSaveUpdates`，並在提交時清除更新控制代碼。 4. 在遊戲暫停或終止時，關閉容器與提供者控制代碼。 請在遊戲啟動及繼續時呼叫 `XGameSaveInitializeProvider`。此呼叫可確保提供者正確初始化，並在遊戲執行期間保持作用中。如果未呼叫，遊戲的行為可能無法預測。 ### 程式碼範例 如需示範如何使用 `XGameSave` API 的程式碼範例，請參閱 [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/)。 ## Game Saves 流程 以下是簡化 Game Saves 流程的流程圖。說明如下。 簡化 Game Saves 同步程序的流程圖。 ### 遊戲啟動 使用者啟動或繼續遊戲時，即為遊戲啟動。 ### 使用者登入 遊戲會起始使用者登入。您也會在此呼叫中叫用 `XGameSaveInitializeProvider`。 如需使用者設定的詳細資訊，請參閱[使用者模型](/zh-TW/build/core-features/common/game-save/game-saves-developer-guide#user-models)。 ### 連線檢查 遊戲會判斷是否能連線到 XBOX 網路。如果無法連線，則由您決定是否為遊戲啟用[離線模式](/zh-TW/build/core-features/common/game-save/game-saves-syncing#connection-check)。 ### 資料擁有權檢查 裝置會檢查使用者目前是否正在其他裝置上遊玩。對於特定遊戲，一次只能有一部裝置存取使用者的資料。 ### 與雲端同步資料 裝置會將 Game Saves 本機儲存空間資料與雲端同步。如果發生衝突，系統會以衝突解決對話方塊提示使用者。 對話方塊：[您要使用哪一個？](/zh-TW/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) 當裝置上的資料比雲端資料新時，遊戲會提示使用者選擇使用本機資料或雲端資料。 ### 遊戲迴圈 遊戲可以自由讀取與寫入 Game Saves 本機儲存空間。 ### 遊戲工作階段結束 遊戲工作階段結束時，系統會自動嘗試將資料上傳到雲端。請確保您的遊戲在結束流程中呼叫 `XGameSaveUninitializeProvider`，以避免讓提供者保持初始化狀態。結構化的關機可確保資料在結束前完整儲存。 如需詳細的同步資訊，請參閱[了解 Game Saves 同步流程](/zh-TW/build/core-features/common/game-save/game-saves-syncing)。 ## 限制與配額 ### 限制 `XGameSaveUpdate` 將每個更新限制為 16 MB。因此，`XGameSave` 只能管理最多 16 MB 的個別檔案更新。此限制與支援最多 64 MB 檔案的 `XGameSaveFiles` 不同。 ### 配額 使用者可為每個遊戲儲存的資料上限為 256 MB。使用 [XGameSaveGetRemainingQuota](/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquota) 取得剩餘配額。若要為您的遊戲取得儲存空間擴充，請連絡您的開發人員合作夥伴經理 (DPM)。 ## 最佳做法 * 請勿在儲存資料後立即查詢並要求取回相同的資料。 * 跨容器的資料相依性並不可靠。每個 `XGameSaveSubmitUpdate` 呼叫都會以不可部分完成的方式套用所有變更，或完全不套用。 * 每次更新呼叫使用的 Blob 越多，完成儲存資料所需檔案系統作業之不可部分完成作業的時間就越長。 ## 常見問題 ### 我正在升級我的 Game Saves 實作。正確的方法是什麼？ 使用 [XGameSaveFiles](/zh-TW/build/core-features/common/game-save/xgamesavefiles)。 ### 我可以將 XGameSave 與 XGameSaveFiles 搭配使用嗎？ 可以。不過，請僅在移轉時這麼做。如需詳細資訊，請參閱 [XGameSave 與 XGameSaveFiles 之間的互通性](/zh-TW/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles)。 ### XGameSave 會儲存到哪個檔案路徑？ **主機**：遊戲作用中時會提供暫存路徑。無法使用檔案總管存取主機檔案。 **PC**：`%AppData%\Local\Packages\\SystemAppData\wgs\_\` 請注意，`XGameSave` 的 PC 路徑與 `XGameSaveFiles` 不同。後者使用 `xgs`。 ### 我可以指定資料應儲存的路徑嗎？ 可以，但僅限 PC。我們只建議在您從另一個遊戲移植解決方案時使用此方法。此解決方案使用[無程式碼雲端存檔](/zh-TW/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。 ### 是否有任何情況需要使用 Sync on Demand？ 否。保留它是為了支援舊版。 ## 參考 API 文件 * [XGameSave (API 內容)](/zh-TW/reference/system/xgamesave/xgamesave_members) * 函式 * [XGameSaveCloseProvider](/zh-TW/reference/system/xgamesave/functions/xgamesavecloseprovider) * [XGameSaveGetRemainingQuota](/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquota) ## 另請參閱 [Game Saves 目錄](/zh-TW/build/core-features/common/game-save/game-saves-toc) ## Related topics - [XGameSave](/reference/system/xgamesave/xgamesave_members.md) - [Save](/ko/reference/system/Wrappers/classes/provider/methods/xgamesave_wrapper_provider_save.md) - [XGameSave API overview](/build/core-features/common/game-save/xgamesave.md) - [XGameSave API 概述](/zh-CN/build/core-features/common/game-save/xgamesave.md)