Title Storage Interface

Title Storage インターフェース を使用することで、デベロッパーは Epic Online Services (EOS) をクラウド サーバーから暗号化したデータを取得することができます。このインターフェースで格納したデータは、ログイン可能なデバイス上のすべてのユーザーがアクセスできます。Player Data Storage インターフェイス と同様に、このインターフェイスは、ユーザー固有ではなくゲーム固有のデータの処理に特化しており、ユーザーのプラットフォーム、地域、またはその他の条件に応じてファイルをさまざまな形式で提供することができます。Title Storage インターフェースと Player Data Storage インターフェースの詳しい違いについては、このドキュメントの後半の「Player Data Storage との違い」セクションを参照してください。

Title Storage インターフェースを利用するには、Platform インターフェース 関数 EOS_Platform_GetTitleStorageInterface で EOS_HTitleStorage ハンドルを取得します。Title Storage インターフェースの関数はすべて、最初のパラメータとしてこのハンドルを必要とします。リクエストが完了したときにコールバックがトリガーされるようにするには、EOS_HPlatform ハンドルがティックしていることを確認する必要があります。

EOS のファイル名は以下の形式です。Directory0/Directory1/DirectoryN/Filename.Extension 「Directory」と「Extension」の部分はオプションです。「/」文字を各ディレクトリ名の後ろに追加する必要がありますが、これは最初や最後の文字を含め他の場所には使用できません。ファイル名に以下の文字を使用できます。

• すべての ASCII 英数字
• !
• -
• _
• +
• .
• '
• (
• )

ファイル名は EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES (64) 文字を超えてはいけません。

EOS SDK では、いくつかのクエリ API を呼び出すことで、クラウドに保存されているファイルに関する情報を取得できます。クエリは、各ファイルの名前、サイズ (バイト単位)、MD5 ハッシュなど、1 つ以上のファイルに関するメタデータを返します。次に、このメタデータの独自のコピーを要求および管理し、それを使用してファイルにアクセスまたは変更することができます。ファイルはバックエンドに暗号化された形式で保存されるため、ファイルサイズや MD5 ハッシュなどのメタデータは、Dev Portal を通じてアップロードした元のファイルではなく、暗号化されたファイルを反映します。

単一のファイルに関する情報のみが必要で、そのファイルの名前がわかっている場合は、EOS_TitleStorage_QueryFile 関数を呼び出して、次のように初期化された EOS_TitleStorage_QueryFileOptions 構造体を渡します。

操作が完了すると、EOS は (EOS_TitleStorage_OnQueryFileCompleteCallback タイプの) コールバックを EOS_TitleStorage_QueryFileCallbackInfo 構造で実行します。呼び出しが成功すると、EOS はファイルに関するデータをキャッシュに保持します。

一度に複数のファイルをクエリしたり、正確なファイル名を知らないファイルをクエリするには、まず Dev Portal からファイルにタグを適用する必要があります。EOS SDK は、これらのタグに基づいてファイルをクエリすることができます。ファイル タグは、EOS ファイル名と同じフォーマット規則を使用する文字列です。この方法でファイルをクエリする場合、1 つ以上のタグを指定する必要があります。EOS SDK は、少なくともタグの 1 つを含むすべてのファイルのリストを取得します。これを行うには、EOS_TitleStorage_QueryFileListOptions を指定して EOS_TitleStorage_QueryFileList を呼び出します。

完了すると、EOS は (EOS_TitleStorage_OnQueryFileListCompleteCallback タイプ) ）コールバック関数を EOS_TitleStorage_QueryFileListCallbackInfo データ構造で実行します。呼び出しが成功すると、データ構造には検出されたファイルの数が含まれ、それらのファイルに関する情報は EOS キャッシュで利用できます。

Title Storage インターフェースは、すべてのファイルをクエリするための特定の API コールは提供しません。ただし、アップロードするすべてのファイルに特定のタグを適用する場合、そのタグで EOS_TitleStorage_QueryFileListOptions を使用して、すべてのファイルに関するデータを取得できます。

EOS 1 つ以上のファイルに関する情報を取得してキャッシュすると、ファイル名で EOS_TitleStorage_CopyFileMetadataByFilename を呼び出すか、キャッシュにあるファイルのゼロベースのインデックスで EOS_TitleStorage_CopyFileMetadataAtIndex を呼び出すことで、特定のファイルの情報を取得できます。キャッシュにあるファイルの数を知る必要がある場合は、 EOS_TitleStorage_GetFileMetadataCount を呼び出すことができます。この情報のコピーが不要になったら EOS_PlayerDataStorage_FileMetadata_Release を呼び出して使用していたメモリを解放します。

Title Storage インターフェースは、クラウドからのファイルの非同期読み取りをサポートしています。読み込みはストリーミング操作です。EOS では、ストリームの進行状況を確認したり、ストリームを調整または中断するために使用できるハンドルを提供します。

ファイルの読み取り

名前がわかっているファイルをクラウド (またはローカル キャッシュ) から読み取るには、EOS_TitleStorage_ReadFile を呼び出します。以下のように初期化した EOS_TitleStorage_ReadFileOptions を渡す必要があります。

この関数は、転送の進行状況の確認、ファイル名の取得、または転送のキャンセルに使用できる EOS_HTitleStorageFileTransferRequest ハンドルを返します。転送中のいつでも、 EOS_TitleStorageFileTransferRequest_GetFileRequestState を呼び出して現在の状態をポーリングし、EOS_TitleStorageFileTransferRequest_GetFilename を呼び出して転送中のファイルの名前を確認するか、または EOS_TitleStorageFileTransferRequest_CancelRequest を呼び出して (エラーを生成せずに) 取り消します。転送を直接ポーリングするのではなく、EOS から更新を受信する場合は、転送を開始するときに有効な EOS_TitleStorage_OnFileTransferProgressCallback 関数を ( FileTransferProgressCallback パラメーターとして) 提供し、EOS がそれを (EOS_TitleStorage_FileTransferProgressCallbackInfoパラメーターで) 呼び出して、ファイルの転送状況を定期的に通知します。このルートを選択すると、コールバック関数への呼び出しを少なくとも 1 つ以上受け取ることが保証されます。コールバック関数を使用した場合もハンドルを使用できますが、両者はほぼ同様の目的を果たすので、両方が必要なユースケースはほとんどありません。

ファイルのチャンクを受け取ると、(EOS_TitleStorage_OnReadFileDataCallback 型の) ReadFileDataCallback は EOS_TitleStorage_ReadFileDataCallbackInfo 型のパラメータで実行します。この構造体には、ファイルからの実際のデータのチャンクと、これがそうであるかどうかを示す変数が含まれます。また、列挙型の戻り型 EOS_TitleStorage_EReadResult があります。これを使用して、転送を続行するか、エラーのために終了するか、エラーを報告せずにキャンセルするのかを EOS に指示できます。

ファイル転送が完了すると、EOS は EOS_TitleStorage_ReadFileCallbackInfo パラメーターを指定して EOS_TitleStorage_OnReadFileCompleteCallback コールバック関数を実行します。このパラメータは成功や失敗の結果を表し、ファイル名を含みます。

EOS にはファイルをローカルにキャッシュして、将来の読み取り操作を高速化する機能があります。これらのファイルは EOS プラットフォームの初期化中に指定したキーで暗号化されます。一方、ReadFileDataCallback 機能に送信するデータ チャンクは暗号化しません。

次のタイムライン図は、仮定に基づいた読み取り操作の動作を示しています。

複数のファイルを連続してダウンロードする場合、最初にファイル リストをクエリし、メタデータをキャッシュしてからダウンロードを実行することで、パフォーマンスを向上させることができます。この方法は複数のクエリを実行せず、ファイルをダウンロードするごとに結果を待つ必要がありません。

Title Storage インターフェースは、ファイル データとメタデータをクライアント システムの「CacheDirectory」フォルダーにキャッシュします。可能な限り EOS は、MD5 チェックサム テストを使ってクラウドからストリーミングするのではなくこのデータを使用して、データの破損を防ぎ、ローカルにキャッシュされたファイルがクラウド上のバージョンと一致して、いつ読み取り操作を単一コールバックで完了することができるかを判断します。読み取り操作が成功すると、キャッシュが更新されます。EOS はシャットダウン時にキャッシュをクリアしないため、以降のセッションでキャッシュ ファイルを再利用できます。

Title Storage ファイルは、EOS プラットフォームの初期化中に指定したキーを使用して、常に暗号化されて保存されます。暗号化キー自体はクラウドに保存されないため、Epic Games と悪意のあるサードパーティの両方がキーを使用してデータにアクセスすることはできません。暗号化キーは、製品のすべてのユーザーで同一です。

バージョンが古い、または未使用のキャッシュ ファイルは EOS によって定期的に自動的に削除されますが、EOS_TitleStorage_DeleteCache 関数を呼び出すことにより、キャッシュを手動でクリアできます (ローカル ストレージのスペースが非常に限られている場合など)。次のように初期化された EOS_TitleStorage_DeleteCacheOptions を渡す必要があります。

ゲームコードでデフォルト ファイルを管理できますが、これらのファイルの代替バージョンを提供したい場合があります。たとえば、各ゲームサーバーには独自の構成設定があり、それを使用する場合です。これらの代替ファイルはデベロッパー ポータルを使って管理する必要があります。ここでファイルの設定を構成することができます (代替ファイルを受け取る人の指定など)。Title Storage インターフェースでファイルを照会すると、Title Storage インターフェースは代替ファイルを返します (適宜)。 詳細については、「タイトル ストレージの管理」ドキュメントを参照してください。

ファイル復号化ツール を使うと、新規ファイルを作成したり、タイトル ストレージ または プレイヤー データ ストレージ にロードされたファイルを簡単かつ便利に復号化することができます。

タイトル ストレージによって、Epic Online Services (EOS) を使用するデベロッパーはクラウド サーバーから暗号化したデータを取得することができます。データはタグによってグループ化され、すべてのプラットフォームのすべてのユーザーが使用することができます。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「サービス使用上の制限事項」を参照してください。

現在、タイトル ストレージには個々のファイルに対するサイズの制限はありませんが、以下のような制限があります。

Title Storage インターフェースと Player Data Storage インターフェース はどちらもクラウドベースのデータファイルを扱いますが、方法や目的が異なります。主な違いは次のとおりです。

1. Title Storage インターフェースは、デベロッパー ポータルを介してクラウドに配置されたファイルのみをクエリおよびダウンロードしますが、Player Data Storage インターフェースはファイルの作成、変更、および削除もできます。

2. Title Storage インターフェースは、製品ごとにファイルを扱います。これらのファイルは、製品のすべてのユーザーに共通です。Player Data Storage インターフェイスはユーザーごとに機能し、ファイルは各ユーザーに対してプライベートです。

3. 2 つのインターフェースは、ファイルの暗号化の実装方法が異なります。詳細については、「データのキャッシュと暗号化」セクションを参照してください。

4. Title Storage インターフェースは条件付きファイルのオーバーライドをサポートしているため、開発者は異なるバージョンを提供できます。詳細については、「ファイルのオーバーライド」セクションを参照してください。

5. Title Storage インターフェースを使用したファイル クエリでは、タグ付けシステムを利用して関連ファイルをグループ化できます。

6. Title Storage インターフェースはファイルをアップロードしないため、ユーザー スロットリングは心配ありません。