> ## 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 モデルを説明し、プロバイダーの初期化、プロバイダーのクローズ、および更新ハンドルのライフサイクルを取り上げます。原子的な更新の動作を概説し、同期フロー図を含めています。また、ファイル サイズおよびクォータの制約、ならびにベスト プラクティスとよくある質問についても説明します。 `XGameSave` API を使用すると、Game Saves データを管理するために BLOB とコンテナーを管理できます。Microsoft Game Development Kit (GDK) タイトルの Game Saves では、[XGameSaveFiles](/build/core-features/common/game-save/xgamesavefiles) の使用をお勧めします。`XGameSaveFiles` を使えない場合は `XGameSave` を使用してください。 XGameSave のシステム API リファレンスについては、[XGameSave (API 目次)](/reference/system/xgamesave/xgamesave_members) を参照してください。 `XGameSave` では、次の用語がよく登場します。 * **ロック**: 特定のユーザーが現在アクティブに使用しているデバイス上で、タイトルの Game Saves への排他アクセスを付与するメカニズムです。これは、ロックが保持されている間、他のデバイスがそのユーザーの Game Saves を変更できないようにします。 * たとえば、ユーザーがデバイス A でタイトル T をプレイしている場合、そのユーザーのタイトル T に対するロックを持っています。 * **プロバイダー**: Game Save システムと通信する仲介プロセスで、タイトル データの管理を担当します。プロバイダーはデバイス上のユーザーのロックも管理します。 * **コンテナー**: フォルダーに相当します。 * **BLOB**: 個別のファイルに相当します。 ## プロバイダーの管理 ストレージ スペースを取得するために、ゲームはプロバイダーを初期化する必要があります。接続後、タイトルは `XGameSaveInitializeProvider` または `XGameSaveInitializeProviderAsync` を呼び出して、タイトルのクラウド ストレージへのロックの取得を試みます。 接続喪失によりクラウドからの同期に失敗した場合、ユーザーがオフライン モードでプレイを続行できるかを判断してください。 タイトルは、中断または終了時に [XGameSaveCloseProvider](/reference/system/xgamesave/functions/xgamesavecloseprovider) でプロバイダーを閉じる必要があります。プロバイダーは中断-再開の境界を越えて再利用することはできません。 この問題は `XGameSave` にのみ該当します。`XGameSaveFiles` は自動的にプロバイダーを閉じます。 ## コンテナー管理 同期完了前にコンテナーを作成するなど、コンテナーへのアクセス時のデータ損失を避けるには、`XGameSaveEnumerateContainerInfo` または `XGameSaveEnumerateContainerInfoByName` を呼び出して、ユーザーが持っているコンテナーを表示します。 `XGameSaveCreateContainer` を使用して、新規または既存のコンテナーへのコンテナー ハンドルを取得します。コンテナーが既に存在する場合は、そのハンドルが提供されます。コンテナーが存在しない場合は、新しいコンテナーが作成され、そのハンドルが提供されます。 コンテナーを削除するには、`XGameSaveDeleteContainer` を使用します。コンテナー内のすべての BLOB も削除されます。 ハンドル リークを防ぐため、コンテナーが使用されなくなったとき、またはタイトルが中断もしくは終了するときには、`XGameSaveCloseContainer` ですべてのコンテナー ハンドルを閉じてください。 ## BLOB 管理 コンテナー内のデータの操作は、`XGameSaveCreateUpdate` を呼び出して行います。 次の詳細では、`XGameSaveUpdate` がコンテナー内の BLOB 変更をどのように管理し、各更新がどのように作成、変更、および送信されるかを概説しています。 * 更新は 1 つのコンテナーに適用されます。 * 更新は最大で GS\_MAX\_BLOB\_SIZE (16 MB) まで書き込めます。 * 単一の更新で複数の BLOB を変更できます。 * 単一の BLOB に対しては、1 回の更新につき 1 つの変更しか行えません。 * 更新を送信すると、`XGameSaveUpdate` ハンドルが消費されます。送信が成功したか失敗したかに関わらず、ハンドルを閉じてください。 * 更新は原子的です。どこか一部でも失敗すると、更新全体が失敗します。 * `XGameSaveCreateUpdate` は、すべての BLOB 変更を保存するための更新コンテキストを作成します。 * `XGameSaveSubmitBlobWrite` は、新規または既存の 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/) を参照してください。 ## Game Saves フロー 以下は、簡略化された Game Saves フローのフローチャートです。以下のように説明されます。 簡略化された Game Saves 同期プロセスのフローチャート。 ### タイトル開始 タイトル開始は、ユーザーがタイトルを起動または再開したときに発生します。 ### ユーザー サインイン タイトルはユーザー サインインを開始します。この呼び出しは、`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) を有効にするかどうかはあなた次第です。 ### データ所有権チェック デバイスは、ユーザーが現在他のデバイスでプレイしていないかを確認します。特定のタイトルのユーザーのデータには、一度に 1 つのデバイスのみがアクセスできます。 ### クラウドとのデータ同期 デバイスは、Game Saves のローカル ストレージ データをクラウドと同期します。競合がある場合、システムは競合解決ダイアログでユーザーに確認を求めます。 ダイアログ: [どちらを使用しますか?](/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) デバイス上のデータがクラウドのデータより新しい場合、タイトルは、ローカル データを使うかクラウド データを使うかをユーザーに選択するよう求めます。 ### ゲームプレイ ループ タイトルは、Game Saves のローカル ストレージへの読み書きを自由に行えます。 ### ゲーム セッションの終了 ゲーム セッションが終了すると、システムは自動的にデータのクラウドへのアップロードを試みます。プロバイダーが初期化されたまま残らないように、タイトルの終了フローで `XGameSaveUninitializeProvider` を呼び出すようにしてください。整然としたシャットダウンにより、終了する前にデータがクリーンに保存されるようになります。 同期の詳細については、[Game Saves の同期フローについて](/build/core-features/common/game-save/game-saves-syncing) を参照してください。 ## 制限とクォータ ### 制限 `XGameSaveUpdate` は各更新を 16 MB に制限しています。その結果、`XGameSave` は最大 16 MB までの個別ファイル更新のみを管理できます。この制限は、64 MB までのファイルをサポートする `XGameSaveFiles` とは異なります。 ### クォータ ユーザーがタイトルごとに保存できる最大データは 256 MB です。残りのクォータを取得するには、[XGameSaveGetRemainingQuota](/reference/system/xgamesave/functions/xgamesavegetremainingquota) を使用します。タイトルのストレージ拡張を取得するには、開発パートナー マネージャー (DPM) に連絡してください。 ## ベスト プラクティス * データを保存した直後に、同じデータを問い合わせて要求しないでください。 * コンテナー間のデータ依存関係は信頼できません。各 `XGameSaveSubmitUpdate` 呼び出しは、すべての変更を原子的に適用するか、まったく適用しないかのどちらかです。 * 1 回の更新呼び出しで使用する BLOB が多いほど、データを保存するために必要なファイル システム操作の原子的な操作を完了するのに必要な時間が長くなります。 ## よくある質問 ### Game Saves の実装をアップグレードしています。正しいアプローチは何ですか? [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) ## 関連項目 [Game Saves 目次](/build/core-features/common/game-save/game-saves-toc) ## Related topics - [Game Saves の概要](/ja-jp/build/core-features/common/game-save/game-saves-overview.md) - [XGameSaveFiles API の概要](/ja-jp/build/core-features/common/game-save/xgamesavefiles.md) - [XGameSave Wrapper リファレンス インデックスおよびメンバー一覧](/ja-jp/reference/system/Wrappers/xgamesave_wrapper_members.md) - [XBOX 認定の概要](/ja-jp/publishing/certification/overview.md) - [DirectStorage の概要](/ja-jp/build/console-features/storage/directstorage/directstorage-overview.md)