> ## 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 개요 > 컨테이너 및 blob 모델, 공급자 초기화, 업데이트 핸들, 원자적 업데이트, 동기화 흐름 다이어그램을 다루는 XBOX XGameSave API 참조입니다. 이 문서에서는 컨테이너 및 blob 모델을 설명하고 공급자 초기화, 공급자 종료, 업데이트 핸들 수명 주기를 다룹니다. 원자적 업데이트 동작을 개괄하며 동기화 흐름 다이어그램이 있습니다. 또한 이 문서에서는 파일 크기 및 할당량 제약과 함께 모범 사례 및 FAQ를 제공합니다. `XGameSave` API를 사용하면 게임 저장 데이터를 관리하기 위한 blob과 컨테이너를 관리할 수 있습니다. Microsoft Game Development Kit(GDK) 타이틀의 게임 저장에는 [XGameSaveFiles](/build/core-features/common/game-save/xgamesavefiles)를 권장합니다. `XGameSaveFiles`가 옵션이 아닐 때는 `XGameSave`를 사용하세요. XGameSave에 대한 시스템 API 참조는 [XGameSave(API 콘텐츠)](/reference/system/xgamesave/xgamesave_members)를 참조하세요. `XGameSave`에서 다음 용어가 자주 나타납니다. * **잠금**: 활성적으로 사용하는 디바이스에서 특정 사용자에 대한 타이틀의 게임 저장에 대한 배타적 접근을 부여하는 메커니즘입니다. 잠금이 유지되는 동안 다른 디바이스가 사용자의 게임 저장을 수정할 수 없도록 보장합니다. * 예를 들어, 사용자가 디바이스 A에서 타이틀 T를 플레이하면 해당 사용자의 타이틀 T에 대한 잠금을 갖게 됩니다. * **공급자**: 게임 저장 시스템과 통신하며 타이틀 데이터 관리를 담당하는 중개 프로세스입니다. 공급자는 또한 디바이스에서 사용자의 잠금을 관리합니다. * **컨테이너**: 폴더에 해당합니다. * **Blob**: 개별 파일에 해당합니다. ## 공급자 관리 저장 공간을 획득하려면 게임이 공급자를 초기화해야 합니다. 연결 후 타이틀은 `XGameSaveInitializeProvider` 또는 `XGameSaveInitializeProviderAsync`를 호출하여 타이틀의 클라우드 스토리지에 대한 잠금을 획득하려고 시도합니다. 타이틀이 연결 손실로 인해 클라우드에서 동기화하는 데 실패하는 경우, 사용자가 오프라인 모드에서 계속 플레이할 수 있는지 여부를 결정하세요. 타이틀은 일시 중단되거나 종료될 때 [XGameSaveCloseProvider](/reference/system/xgamesave/functions/xgamesavecloseprovider)로 공급자를 닫아야 합니다. 공급자는 일시 중단-재개 경계를 넘어 다시 사용할 수 없습니다. 이 문제는 `XGameSave`에만 적용됩니다. `XGameSaveFiles`는 자동으로 공급자를 닫습니다. ## 컨테이너 관리 동기화가 완료되기 전에 컨테이너를 만드는 것과 같이 컨테이너에 접근할 때 데이터 손실을 피하려면 `XGameSaveEnumerateContainerInfo` 또는 `XGameSaveEnumerateContainerInfoByName`을 호출하여 사용자가 가진 컨테이너를 확인하세요. `XGameSaveCreateContainer`를 사용하여 새 컨테이너 또는 기존 컨테이너에 대한 컨테이너 핸들을 가져옵니다. 컨테이너가 이미 있으면 해당 핸들이 제공됩니다. 컨테이너가 없으면 새 컨테이너가 만들어지고 해당 핸들이 제공됩니다. 컨테이너를 삭제하려면 `XGameSaveDeleteContainer`를 사용합니다. 컨테이너 내의 모든 blob도 삭제됩니다. 핸들 누수를 방지하려면 컨테이너가 더 이상 사용되지 않거나 타이틀이 일시 중단되거나 종료될 때 `XGameSaveCloseContainer`로 모든 컨테이너 핸들을 닫으세요. ## Blob 관리 컨테이너 내의 데이터 조작은 `XGameSaveCreateUpdate`를 호출하여 수행됩니다. 다음 세부 정보는 `XGameSaveUpdate`가 컨테이너 내 blob 변경 사항을 관리하는 방법과 각 업데이트가 어떻게 만들어지고, 수정되고, 제출되는지를 개괄합니다. * 업데이트는 하나의 컨테이너에 적용됩니다. * 업데이트는 최대 GS\_MAX\_BLOB\_SIZE(16MB)를 쓸 수 있습니다. * 하나의 업데이트에서 여러 blob을 수정할 수 있습니다. * 단일 blob은 업데이트당 하나의 수정만 가질 수 있습니다. * 업데이트를 제출하면 `XGameSaveUpdate` 핸들이 소비됩니다. 제출이 성공하든 실패하든 핸들을 닫으세요. * 업데이트는 원자적입니다. 일부가 실패하면 전체 업데이트가 실패합니다. * `XGameSaveCreateUpdate`는 모든 blob 수정 사항을 저장할 업데이트 컨텍스트를 만듭니다. * `XGameSaveSubmitBlobWrite`는 새 blob 또는 기존 blob에 데이터를 쓰며 업데이트된 컨텍스트가 필요합니다. * `XGameSaveSubmitBlobDelete`는 blob을 삭제합니다. * `XGameSaveSubmitUpdate`는 업데이트 컨텍스트를 제출합니다. * `XGameSaveCloseUpdate`는 업데이트 핸들을 닫습니다. 누수를 방지하기 위해 타이틀은 매 제출 후에 이를 호출합니다. * 컨테이너 내의 모든 blob에 접근하려면 `XGameSaveEnumerateBlobInfo` 또는 `XGameSaveEnumerateBlobInfoByName`을 사용합니다. Blob에 쓰인 데이터는 XML로 내보낼 때 `Base64`로 표현됩니다. ## 구현 다음 단계에서는 `XGameSave` 구현의 일반적인 흐름을 보여 줍니다. 1. 타이틀 시작 또는 재개 시 공급자를 초기화합니다. 2. 컨테이너 핸들을 열거하고 만듭니다. 3. Blob 수정 사항이 포함된 `XGameSaveUpdates`를 주기적으로 제출하고 제출 시 업데이트 핸들을 정리합니다. 4. 타이틀 일시 중단 또는 종료 시 컨테이너 및 공급자 핸들을 닫습니다. 타이틀이 시작될 때와 재개될 때 `XGameSaveInitializeProvider`를 호출합니다. 이 호출은 공급자가 올바르게 초기화되고 타이틀이 실행되는 동안 활성 상태로 유지되도록 보장합니다. 호출되지 않으면 타이틀이 예측할 수 없게 동작할 수 있습니다. ### 코드 샘플 `XGameSave` API 사용 방법을 보여 주는 코드 샘플은 [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/)를 참조하세요. ## 게임 저장 흐름 다음은 단순화된 게임 저장 흐름의 순서도입니다. 다음과 같이 설명됩니다. 단순화된 게임 저장 동기화 프로세스의 순서도. ### 타이틀 시작 타이틀 시작은 사용자가 타이틀을 실행하거나 재개할 때 발생합니다. ### 사용자 사인인 타이틀이 사용자 사인인을 시작합니다. `XGameSaveInitializeProvider`도 이 호출에서 호출합니다. 사용자 설정에 대한 자세한 내용은 [사용자 모델](/build/core-features/common/game-save/game-saves-developer-guide#user-models)을 참조하세요. ### 연결 확인 타이틀이 XBOX 네트워크에 연결할 수 있는지 결정합니다. 연결할 수 없으면 타이틀에 대한 [오프라인 모드](/build/core-features/common/game-save/game-saves-syncing#connection-check)를 활성화하는 것은 사용자의 몫입니다. ### 데이터 소유권 확인 디바이스는 사용자가 현재 다른 디바이스에서 플레이하고 있는지 확인합니다. 한 번에 하나의 디바이스만 특정 타이틀에 대한 사용자의 데이터에 접근할 수 있습니다. ### 클라우드와 데이터 동기화 디바이스가 게임 저장 로컬 스토리지 데이터를 클라우드와 동기화합니다. 충돌이 있는 경우 시스템은 충돌 해결 대화상자로 사용자에게 요청합니다. 대화상자: [어느 것을 사용하시겠습니까?](/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) 디바이스의 데이터가 클라우드 데이터보다 최신인 경우, 타이틀은 사용자에게 로컬 데이터를 사용할지 클라우드 데이터를 사용할지 선택하도록 요청합니다. ### 게임 플레이 루프 타이틀은 게임 저장 로컬 스토리지에 자유롭게 읽고 쓸 수 있습니다. ### 게임 세션 종료 게임 세션이 종료되면 시스템은 자동으로 클라우드에 데이터 업로드를 시도합니다. 공급자를 초기화된 상태로 두지 않도록 타이틀이 종료 흐름에서 `XGameSaveUninitializeProvider`를 호출하는지 확인하세요. 구조화된 종료는 종료하기 전에 데이터가 깔끔하게 저장되도록 보장합니다. 자세한 동기화 정보는 [게임 저장 동기화 흐름 이해](/build/core-features/common/game-save/game-saves-syncing)를 참조하세요. ## 제한 및 할당량 ### 제한 `XGameSaveUpdate`는 각 업데이트를 16MB로 제한합니다. 따라서 `XGameSave`는 최대 16MB까지의 개별 파일 업데이트만 관리할 수 있습니다. 이 제한은 최대 64MB까지의 파일을 지원하는 `XGameSaveFiles`와 다릅니다. ### 할당량 사용자가 타이틀당 저장할 수 있는 최대 데이터는 256MB입니다. 남은 할당량을 가져오려면 [XGameSaveGetRemainingQuota](/reference/system/xgamesave/functions/xgamesavegetremainingquota)를 사용합니다. 타이틀의 스토리지 확장을 위해서는 개발자 파트너 관리자(DPM)에게 문의하세요. ## 모범 사례 * 데이터를 저장한 다음 즉시 동일한 데이터를 다시 쿼리하고 요청하지 마세요. * 컨테이너 간 데이터 종속성은 신뢰할 수 없습니다. 각 `XGameSaveSubmitUpdate` 호출은 모든 변경 사항을 원자적으로 적용하거나 전혀 적용하지 않습니다. * 업데이트 호출당 사용하는 blob이 많을수록 데이터 저장을 위한 파일 시스템 작업의 필요한 원자적 작업을 완료하는 데 더 많은 시간이 필요합니다. ## FAQ ### 게임 저장 구현을 업그레이드하고 있습니다. 올바른 접근 방식은 무엇인가요? [XGameSaveFiles](/build/core-features/common/game-save/xgamesavefiles)를 사용하세요. ### XGameSave를 XGameSaveFiles와 함께 사용할 수 있나요? 예. 그러나 마이그레이션 목적으로만 사용하세요. 자세한 내용은 [XGameSave와 XGameSaveFiles 간 상호 운용성](/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에서만 가능합니다. 다른 타이틀에서 솔루션을 이식하는 경우에만 이 접근 방식을 권장합니다. 이 솔루션은 [코드 없는 클라우드 저장](/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 콘텐츠)](/reference/system/xgamesave/xgamesave_members) * 함수 * [XGameSaveCloseProvider](/reference/system/xgamesave/functions/xgamesavecloseprovider) * [XGameSaveGetRemainingQuota](/reference/system/xgamesave/functions/xgamesavegetremainingquota) ## 참고 항목 [게임 저장 TOC](/build/core-features/common/game-save/game-saves-toc) ## Related topics - [게임 저장 개요](/ko/build/core-features/common/game-save/game-saves-overview.md) - [XGameSaveCloseProvider](/ko/reference/system/xgamesave/functions/xgamesavecloseprovider.md) - [XGameSaveGetRemainingQuota](/ko/reference/system/xgamesave/functions/xgamesavegetremainingquota.md) - [XGameSave](/ko/reference/system/xgamesave/xgamesave_members.md) - [XGameSaveFiles API 개요](/ko/build/core-features/common/game-save/xgamesavefiles.md)