Title Storage インターフェース

すべてのプレイヤーに共有される暗号化されたデータをクラウドからダウンロードするためのインターフェースです。

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

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

このインターフェースを使用するには、次の追加パラメーターを使用して EOS プラットフォームを初期化する必要があります。

  • const char* EncryptionKey:この 64 文字の 16 進数文字列は 256 ビットのキーを構成し、EOS がこれをユーザー データの暗号化に使用します。Epic のバックエンド サーバーはこのキーを格納しません。キーを指定せずに Title Storage インターフェースからファイル管理関数を呼び出すと、失敗して EOS_TitleStorage_EncryptionKeyNotSet エラー コードを返します。

  • const char* CacheDirectory:これはローカル ディレクトリへのフルパスで、インターフェースがデータ ファイルを転送する際に一時的なストレージとして使用します。これは任意の場所を指定できます。通常は、システムの一時ディレクトリやゲームのデータ ディレクトリを選択します。指定したディレクトリが存在しない場合、EOS は作成を試みます。そして、EOS はディレクトリの競合をしないようにするので、複数のユーザーや製品に対して同じディレクトリを使用できます。このディレクトリに問題がある状態でファイル管理関数を呼び出すと、失敗して EOS_CacheDirectoryMissing または EOS_CacheDirectoryInvalid のエラーコードを返します。使用可能なフォルダに関するプラットフォーム別の制限については「EOS プラットフォーム ドキュメント」を参照してください。

ファイルを管理する

ファイル名の形式

EOS のファイル名は以下の形式です。Directory0/Directory1/DirectoryN/Filename.Extension

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

  • すべての ASCII 英数字

  • !

  • -

  • _

  • +

  • .

  • '

  • (

  • )

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

ファイルのクエリ

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

クエリのコールバック関数の実行中に必ず、必要な情報をキャッシュからコピーする ようにしてください。このデータのライフタイムは、コールバック関数の期間を超えて持続することが保証されていません。複数のクエリを実行する場合、クエリが成功するたびにキャッシュの内容が変更される可能性があるため、これは特に重要です。

ほとんどの関数は、トラックを向上させるための Product User ID パラメータ (省略可能) を含みます。Product User ID を使わずに (nullptr を渡すことによって) データをクエリすることが可能ですが、Dev Portal で設定した User ID のオーバーライドは使用できません。Callbacks は渡された同じ User Product ID 値を含みます。

単一のファイルをクエリする

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

プロパティ

ApiVersion

EOS_TITLESTORAGE_QUERYFILEOPTIONS_API_LATEST

LocalUserId

ファイル データを陸枝うとするローカル ユーザーの EOS_ProductUserId (省略可能)

Filename

クエリするファイルの名前

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

タグを使って複数のファイルをクエリする

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

プロパティ

ApiVersion

EOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST

LocalUserId

ファイル データを陸枝うとするローカル ユーザーの EOS_ProductUserId (省略可能)

NumTags

タグのリスト内のタグの数 (正である必要があります)

ListOfTags

ファイルをクエリするタグ (ASCII 文字列) の配列

完了すると、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 を呼び出して使用していたメモリを解放します。

単一のファイルに関する情報を EOS にクエリした結果、EOS_PlayerDataStorage_GetFileMetadataCount により複数のファイルがキャッシュに存在することが判明する場合があります。これは、以前クエリした結果がキャッシュに残っている場合に発生することがあります。このような場合のベスト プラクティスは、EOS_TitleStorage_QueryFileCallbackInfo にある ResultCodeEOS_Success であることを確認してから、EOS_TitleStorage_CopyFileMetadataByFilename を呼び出して情報にアクセスすることです。以前にキャッシュされたメタデータは、複数ファイルのクエリが成功すると削除されます。

ファイルへアクセスする

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

ファイルの読み取り

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

プロパティ

ApiVersion

EOS_TITLESTORAGE_READFILEOPTIONS_API_LATEST

LocalUserId

リクエストしたファイルを読み取るローカル ユーザーのアカウント ID (省略可能)

Filename

読み取るファイルの名前

ReadChunkLengthBytes

1 回の EOS_TitleStorage_OnReadFileDataCallback 呼び出しで読み取るデータの最大量

ReadFileDataCallback

入ってくるデータを処理し、転送を早期に停止できるコールバック関数

FileTransferProgressCallback

転送状況を通知するオプションのコールバック関数で、設定すると少なくとも 1 回呼び出されます

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

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

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

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

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

ReadOperationDiagram.png

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

データのキャッシュと暗号化を行う

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

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

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

プロパティ

ApiVersion

EOS_TITLESTORAGE_DELETECACHEOPTIONS_API_LATEST

LocalUserId

ローカル ユーザーのアカウント ID

ほとんどの場合、この機能は必要ありません。キャッシュを削除すると、システムによるダウンロード数が増加し、ゲームとバックエンド サービスの両方のパフォーマンスに悪影響を与える可能性があります。

ファイルのオーバーライド

場合によっては、さまざまな条件に基づいてファイルの異なるバージョンを提供したい場合があります。たとえば、さまざまなゲームサーバーに独自の構成設定がある場合、Title Storage レベルで、特定のファイル名のリクエストを代替ファイルにリダイレクトすることができます。これを行うには、Developer Portal を使用してファイルの構造体を設定します。バックエンド サービスは、受信クエリに基づいてどのファイルを返すかを決定します。この設定の最終結果は、開発者がアプリケーション内から EOS SDK を使用して単一のファイル名を要求できるが、バックエンド システムの基準に従って異なるファイル データが提供されることです。

ファイル復号化ツール

File Decryption Tool を使うと、新規ファイルを作成したり、(Interfaces/TitleStorage) または [Player Data Storage**]Player Data Storage にロードされたファイルを簡単かつ便利に復号化することができます。

使用上の制限事項

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

[](Overview#ServiceUsageLimitations)
」を参照してください。

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

機能

サービスの制限事項

フォルダ サイズ制限

10 GB

ファイル最大数

100

プレーヤーのデータストレージとの違い

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

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

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

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

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

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

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