7. データストア

7.1. はじめに

データストアとは任意のデータのアップロード、ダウンロード、更新、削除などの機能を提供するストレージサービスです。 データストアではデータをアップロードするサーバーとして、ゲームサーバーと専用のストレージサーバー (以下ストレージサーバー) が存在します。 利用する際の組み合わせとして、ゲームサーバーのみを利用する場合と、ゲームサーバーに加えてストレージサーバーを利用する二種類の方法があり、データをアップロードする際はどちらかの方法を選択します。それぞれのメリット、デメリットは以下のようになっています。

  • ゲームサーバーのみの利用(ストレージサーバーを利用しない)

    メリット:ゲームサーバーへのアクセスのみで処理が完結するため高速に処理が行われます。

    デメリット:アップロード可能なデータのサイズが最大 1024 バイトです。

  • ゲームサーバー+ストレージサーバーを利用

    メリット:アップロード可能なデータのサイズが最大 10 メガバイトです。 ゲームサーバーのデータ領域 (メタバイナリ) と、ストレージサーバーのデータ領域の片方もしくは両方を利用することができます。 両方を利用する場合、サイズの大きいデータの実体はストレージサーバーにアップロードし、タイトルや作者名など、よくアクセスする、また DataStoreClient::SearchObject() などを呼び出して複数のデータを一括で取得して表示するものはゲームサーバー側に保存するといった使い分けができます。

    デメリット:ゲームサーバーへのアクセスに加え、 API によってはストレージサーバーへの HTTP アクセスが発生するので処理に時間がかかります。

選択する際の判断基準としては基本的にはアップロードするデータのデータサイズを基準に上記どちらかの方法を選択します。

7.2. データストア全体の流れ

データストア全体の流れは以下のようになります。

  1. ゲームサーバーにログインする。
  2. HTTP ライブラリを初期化する。(この処理はゲームサーバーのみの利用の場合必要ありません)
  3. サービスクライアントを初期化する。
  4. データのアップロードを行う。必要に応じてデータのダウンロード、更新や削除・検索・評価機能やメタ情報の取得・編集を利用する。
  5. HTTP ライブラリを終了する。(この処理はゲームサーバーのみの利用の場合必要ありません)
  6. サービスクライアントの終了処理を行い、ゲームサーバーからログアウトする。

7.3. 初期化・終了

DataStoreClient の初期化・終了処理はマッチメイクでのサービスクライアントの初期化・終了処理と同じとなります。 ただし、ストレージサーバーを利用する場合は HTTP ライブラリの初期化・終了処理が必要となります( Code 7.1 )。

Code 7.1 データストアクライアントの初期化・終了処理
// ゲームサーバーにログイン
LoginGameSevrer(pNgsFacade);
Credentials* pCredentials = pNgsFacade->GetCredentials();



// HTTP ライブラリの初期化
nn::http::Initialize();

// ログインの都度 ServiceClient を生成する。
DataStoreClient* pDataStoreClient = qNew DataStoreClient();

pDataStoreClient->Bind(pCredentials);

// 処理を行う
pDataStoreClient->DoSomething();

// ログアウト前にオブジェクトを破棄
qDelete pDataStoreClient;

// ゲームサーバーからログアウトしてオブジェクトを破棄
LogoutGameServer(pNgsFacade)
qDelete pNgsFacade;

// HTTP ライブラリの終了
nn::http::Finalize();

7.4. データのアップロード

データのアップロードには DataStoreClient::PostObject() を使用します。データのアップロードには以下の方法が用意されています。

【ゲームサーバーのみの利用】

  • DataStorePostParam オブジェクトに対して DataStorePostParam::SetMetaBinary() を用いて、アップロードしたいデータをセットしてください。 アップロード可能なデータサイズは最大 1024 バイトです。 DataStorePostParam::SetSize() は呼び出さずデフォルト値 (0) で利用するか、明示的に 0 を指定する必要があります。

【ゲームサーバー+ストレージサーバーを利用】

二種類のアップロード方法があります。どちらの方法でもアップロード可能なデータサイズは最大 10 メガバイトです。

  • 引数に直接バッファを指定する方法

    buffer 引数にアップロードするデータを指定し、そのサイズを DataStorePostParam オブジェクト の DataStorePostParam::SetSize() にセットします。

  • イベントリスナーを利用する方法

    eventListener 引数に DataStorePostObjectEventListener を継承し DataStorePostObjectEventListener::PostChunkedBuffer() をオーバーライドしたクラスのオブジェクトを指定します。 メモリを一度に確保できないときなど、分割してデータをアップロードしたい場合に使用してください。

正常に処理が成功すると dataId 引数にアップロードされたデータを識別するユニークな ID が格納されます。これをデータ ID と呼びます。 アップロードする際にデータのメタ情報として DataStorePostParam で Table 7.1 にあるパラメータをセットすることが可能です。 アップロード者はそのデータのオーナーとなり、オーナーのプリンシパル ID はオーナー ID としてサーバーに記録されます。 権限とパスワードタグ評価の初期化メタバイナリ設定フラグ についてはそれぞれ個別に説明があります。

補足

データ ID は 64 ビットの有限個となります。使用されたデータ ID は、データが削除された後も再利用されませんので、サービス期間内にこれを超えないような利用をしてください。

ただし、 CTR で いつの間に通信との連携 を利用する場合はデータ ID が 32 ビットの範囲を超えないようにしてください。

また、以下を想定した実装は行わないでください。

  • データ ID が 1 から順番に割り振られる
  • データ ID の数値が増え続ける

データには有効期限が存在します。 アップロードするデータの有効期限が切れた場合、データに対するすべての操作ができなくなります。 有効期限が切れた際にデータが削除されても問題ないような適切な有効日数を指定して実装してください (最大 365 日)。 指定には DataStorePostParam::SetPeriod() を利用します。 有効期限は API の呼び出しにより延長されることがあります。 詳細については タイムスタンプ値の変化について を参照してください。

Table 7.1 DataStorePostParam パラメータ一覧
項目名 概要 初期値 設定関数
サイズ(必須 アップロードするデータサイズ。実際にアップロードするデータのサイズと一致している必要があります。最大値は 10485760 バイトです。ストレージサーバーを利用しない場合は 0 を指定する必要があります。 0 SetSize()
名前 アップロードするデータの名前を指定します。 空文字列 SetName()
データタイプ アップロードするデータタイプ。セットした値は DataStoreClient::SearchObject() や DataStoreClient::SearchObjectLight() で検索条件にすることができます。 0 SetDataType()
参照権限 アップロードするデータの参照、検索できる範囲を指定します。 DataStorePermission(DataStoreConstants::PERMISSION_PRIVATE) SetAccessPermission()
更新権限 アップロードするデータの更新権限を指定します。 DataStorePermission(DataStoreConstants::PERMISSION_PRIVATE) SetUpdatePermission()
設定フラグ アップロードについての設定フラグを指定します。 DataStoreConstants::DATA_FLAG_NONE SetDataFlag()
有効日数 アップロードするデータを参照できる期間を日数で指定します。最大値は 365 日となります。 DataStoreConstants::DEFAULT_PERIOD SetPeriod()
タグ アップロードするデータに付加するタグを指定します。最大 DataStoreConstants::NUM_TAG_SLOT 個指定できます SetTags()
評価スロットの初期化 評価機能を利用する場合は初期化が必要となります。map のキーに 0 - 15 までのスロット番号の値を、バリューには各スロットの初期化パラメータを指定します。 SetRatingSetting()
メタバイナリ メタ情報内のバイナリデータを指定します。ストレージサーバーを利用せずゲームサーバーのみを利用する場合はこちらにアップロードしたいデータを格納します。 SetMetaBinary()
永続化設定 アップロードすると同時に永続化する場合に設定します。 DataStorePersistenceInitParam() SetPersistenceInitParam()

7.4.1. データタイプ

データタイプはアプリケーション側で定義する値で、データの種類を表します。 DataStoreClient::SearchObject() や DataStoreClient::SearchObjectLight() でデータタイプを検索条件に指定することにより、データの種類を絞って検索をすることができます。 またデータタイプを分けることはデータを検索する際のパフォーマンス向上につながりますので、アップロードするデータの種類に応じてデータタイプの値は変えるようにしてください。

データタイプを分けずに、1つのデータタイプに多数のデータが偏ってアップロードされていると、データの検索時にゲームサーバの負荷が高まり、検索の応答速度が遅くなる、ゲームサーバへのログインの失敗率が高まるといった状況が発生し得ますので、ご注意ください。

タグを使用してデータの種類を表現することも可能ですが、タグを指定した検索はデータによっては応答速度が遅くなることがあるため、タグではなくデータタイプでデータの種類を分けることを強く推奨します。

7.4.2. 権限とパスワード

データをアップロードする際に以下の 5 つの権限を参照・更新に分けてデータに対して設定することができます。 これにより特定のフレンドとのデータのやり取りなどが可能となります。

Table 7.2 権限のタイプ
権限 説明
DataStoreConstants::PERMISSION_PUBLIC すべてのプリンシパル ID に対して許可されます
DataStoreConstants::PERMISSION_FRIEND オーナーとフレンド関係にあるプリンシパル ID のみが許可されます
DataStoreConstants::PERMISSION_SPECIFIED 指定した複数のプリンシパル ID に対して許可されます。
DataStoreConstants::PERMISSION_PRIVATE オーナーのみに許可されます
DataStoreConstants::PERMISSION_SPECIFIED_FRIEND 指定した複数のプリンシパル ID かつフレンド関係にあるプリンシパル ID に対して許可されます。なお、フレンド関係にあるプリンシパル ID はサーバー側で確認されます。

データをアップロードしたユーザーはオーナー権限を持ちます。 オーナー権限を持っているユーザーは対象データの参照・更新に加えてオーナーのみに許可される一部の操作を実行できます。

権限を持っていないユーザーはパスワードを指定することでも対象のデータを操作することができます。 パスワードの取得は DataStoreClient::GetPasswordInfo() で行います。 すべてのデータにはアップロード時に参照パスワードと更新パスワードが設定されます。 それをオーナーから伝えてもらい各操作で指定することにより各権限保持者と同等の操作を実行できるようになります。 もし権限を持っているユーザーが誤ったパスワードを指定してもエラーとはならず、操作は許可されます。 オーナー権限に相当するパスワードはありません。 また、一部の関数はパスワードの指定ができません。 データのステータスによっては権限を持っていても参照・更新ができません。 詳しくは データのステータス を参照してください。

操作ごとに必要な権限は Table 7.3 の通りです。

Table 7.3 操作に必要な権限
関数名 必要な権限
DataStoreClient::GetObject() 参照
DataStoreClient::PostObject() N/A
DataStoreClient::UpdateObject() 更新
DataStoreClient::DeleteObject() 更新
DataStoreClient::ChangeMeta() 更新
DataStoreClient::GetMeta() 参照
DataStoreClient::SearchObject() 参照
DataStoreClient::SearchObjectLight() 参照
DataStoreClient::GetRating() 参照
DataStoreClient::RateObject() 参照
DataStoreClient::ResetRating() 更新
DataStoreClient::TouchObject() 参照
DataStoreClient::GetPersistenceInfo() 参照
DataStoreClient::PerpetuateObject() オーナー
DataStoreClient::UnperpetuateObject() オーナー
DataStoreClient::GetPasswordInfo() オーナー
DataStoreClient::CompleteSuspendedPostObject() オーナー

補足

アップロードしたデータをいつの間に通信でダウンロードしたい場合は、アップロードする際に DataStoreConstants::PERMISSION_FRIEND、DataStoreConstants::PERMISSION_SPECIFIED、DataStoreConstants::PERMISSION_SPECIFIED_FRIEND のいずれかを参照権限に指定すると同時に、データの設定フラグ( 7.4.6. )に DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST を指定する必要があります。

いつの間に通信との連携については 7.13. を参照してください。

7.4.3. タグ

アップロードするデータのメタ情報としてタグ情報を最大 NUM_TAG_SLOT 個設定することができます。 1 つのタグ情報として使用できるのは、アスキー印字可能文字、もしくはマルチバイト文字で、最大 MAX_TAG_LENGTH 文字となります。空文字列のタグは指定できません。マルチバイト文字は、NEX_T() マクロにより指定してください。タグ文字列の末尾に半角スペース (0x20)を使用しないでください。使用した場合、タグの設置時、検索時に末尾の空白を無視して取り扱われます。 また、1 つのデータに対して同じタグを設定することはできません。

Code 7.2 タグのセット
DataStorePostParam postParam;
// タグのセット。1 つのデータに対して同じタグを設定することはできません。
qVector<String> tags;
tags.push_back("ABC");
tags.push_back(NEX_T("DEF"));
tags.push_back(NEX_T("GHI"));
postParam.SetTags(tags);

7.4.4. 評価の初期化

データストアではアップロードしたデータに対して評価を行うことができます。 この機能はデータを最初にアップロードする際に DataStorePostParam::SetRatingSetting() に DataStoreRatingInitParam オブジェクトをセットし、初期化する必要があります。設定できる値は Table 7.4 のようになっています。 初期化されたデータについてはデータの評価用関数( 7.10. )を用いることで評価機能を利用することができます。

Table 7.4 DataStoreRatingInitParam パラメータ一覧
項目名 概要 初期値 設定関数
評価合計値の初期値 評価合計値の初期値を設定します。 0 SetInitialValue()
評価値の最低値 一度に評価可能な評価値の最低値を設定します。 設定なし SetRangeMin()
評価値の最大値 一度に評価可能な評価値の最大値を設定します。 設定なし SetRangeMax()
重複ロック 評価の際の重複ロックを設定します。1 回評価したら 1 時間再評価できない、1 日 1 回だけ評価できるなどの制限をかけることができます。 設定なし SetLock()
オプションフラグ 評価時のオプションを指定します。 Table 7.5 を参照してください。 設定なし SetFlag()
Table 7.5 評価時のオプションフラグ一覧
権限 説明
DataStoreConstants::RATING_FLAG_MODIFIABLE 変更可能で、同じユーザーが一度評価した後に再度評価すると最初の評価値を置き換える形で評価に反映されます。フラグがオフの時はそれぞれ別の評価として追加されます。
DataStoreConstants::RATING_FLAG_ROUND_MINUS 評価合計値が負数になる場合 0 に丸められます。
DataStoreConstants::RATING_FLAG_DISABLE_SELF_RATING 自己評価をできなくします。

補足

重複ロックについて( Code 7.4

DataStoreRatingInitParam::SetLock() で DataStoreRatingLockInitParam オブジェクトを指定することによりロック方法を指定できます。

  • DataStoreRatingLockInitParam::SetIntervalLock() で設定

    秒数指定ロックとなります。intervalSec に秒数を指定し、以前の評価から 900 秒ロックするといった使い方ができます。

  • DataStoreRatingLockInitParam::SetPeriodicLock() で設定

    特定の期間を指定したロックとなります。period には毎月曜日から毎日曜日、月初などを指定し、hour には時刻 -23 ~ 23 (UTC)を指定します。毎週月曜日本時間 0 時にロックをリセットするなどの使い方ができます。

  • DataStoreRatingLockInitParam::SetDaysAfterLock() で設定

    日数を指定したロックとなります。days には日数を指定し、hour には時刻 -23 ~ 23 (UTC)を指定します。 1 日 1 回評価できるようにするといった使い方ができます。

  • DataStoreRatingLockInitParam::SetPermanentLock() で設定

    永久ロックとなります。こちらを指定すると永久にロックがかかるため一度評価したものを再度評価することができなくなります。

Code 7.3 評価の初期化
DataStorePostParam postParam;
DataStoreRatingInitParam ratingInitParam;
// 評価の初期化 (スロット 3 つ使用)
qMap<qInt8, DataStoreRatingInitParam> ratings;
for (qInt8 i = 0; i < 3; ++i) {
    ratings.insert(std::make_pair(i, ratingInitParam));
}
postParam.SetRatingSetting(ratings);
Code 7.4 重複ロックの指定例
// 秒数指定ロック。900 秒ロックする
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetIntervalLock(900);
ratingInitParam.SetLock(ratingLockInitParam);

// 日数指定ロック。1 日 1 回評価できる。JST 0 時 (UTC 15 時) にロックをリセット
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetDaysAfterLock(0, 15);
ratingInitParam.SetLock(ratingLockInitParam);

// 期間指定ロック。毎週月曜の UTC 0 時にロックをリセット
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetPeriodicLock(DataStoreConstants::RATING_LOCK_PERIOD_MON, 0);
ratingInitParam.SetLock(ratingLockInitParam);

// 期間指定ロック。JST 月末にロックをリセット
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetPeriodicLock(DataStoreConstants::RATING_LOCK_PERIOD_DAY1, -9);
ratingInitParam.SetLock(ratingLockInitParam);

7.4.5. メタバイナリ

メタ情報内に 1024 バイトまでのバイナリデータを格納することができます。 メタバイナリの格納 / 取得は、ゲームサーバーへのアクセスのみで処理が完結するため、ストレージサーバーを利用するよりも高速な処理が行えます。このため、サイズの小さいデータはメタバイナリを利用し、サイズの大きいデータはストレージサーバーを利用するなど、データのサイズや用途に応じて使い分けることができます。

Code 7.5 メタバイナリのセット
static const META_BINARY_SIZE = 3;
DataStorePostParam postParam;
// バイナリデータのセット
qByte metaBinary[META_BINARY_SIZE];
memcpy(metaBinary, "123", META_BINARY_SIZE);
postParam.SetMetaBinary(metaBinary, META_BINARY_SIZE);

7.4.6. 設定フラグ

アップロードするデータに対する設定を DataStorePostParam::SetDataFlag() で行います。 各フラグの意味は Table 7.6 の通りです。表に載っていないフラグは指定しないでください。

Table 7.6 設定フラグ一覧
フラグ 説明
DataStoreConstants::DATA_FLAG_NONE いずれの設定フラグも使用しません。
DataStoreConstants::DATA_FLAG_NEED_REVIEW アップロードが完了するとデータのステータスが DataStoreConstants::DATA_STATUS_PENDING となり、オーナー以外からは見えない状態になります。見えるようにするには運用者が 7.18. の NMAS を使いステータスを変更する操作が必要になります。
DataStoreConstants::DATA_FLAG_PERIOD_FROM_LAST_REFERRED GetObject() 、UpdateObject() 、ChangeMeta() などでデータが参照または更新されたときに有効期限を延長します。詳細については 7.16.2. を参照してください。
   
DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST アップロードしたデータを BOSS を使ってデータをダウンロードできるようにします。 ( 7.13. 参照)
DataStoreConstants::DATA_FLAG_NEED_COMPLETION DataStoreClient::PostObject() 完了後に DataStoreClient::CompleteSuspendedPostObject() を実行するまでサーバー上のデータを無効状態にします。詳細については 7.4.7. を参照してください。

7.4.7. 一括アップロード

関連するデータを複数アップロードしたい場合は一括アップロード機能が利用できます。 この機能を利用すると、複数のデータをアップロードする際にすべてがアップロードされるか、もしくはすべてされないかというアトミック性を保証することができます。 例えば不意に電源が切られたりネットワークから切断されたりした場合に、一部のデータだけがアップロードされることを防ぐことができます。

この機能を利用するにはまず設定フラグに DataStoreConstants::DATA_FLAG_NEED_COMPLETION を指定して任意個数のデータをDataStoreClient::PostObject() でアップロードします。 アップロードが完了するとオーナーを含む誰からも参照できない状態でデータがサーバーに登録されます。 すべてのデータをアップロード後にそのデータ ID を DataStoreClient::CompleteSuspendedPostObject() の引数に指定すると、そのデータがサーバー上で同時に有効化され通常のデータと同様に参照などが可能になります。

DataStoreClient::CompleteSuspendedPostObject() で指定したデータに一つでも不正なものがあったり、処理に失敗するとその時点で処理をロールバックします。 CallContext::GetOutcome() では最初に発生したエラーが取得できます。 もし永続化設定がなされていた場合は本非同期処理が成功したときに設定されます。 DataStoreClient::PostObject() を開始してから 3 時間以内に本関数で有効化する必要があります。 3 時間以上経過すると自動的にサーバー上のデータが削除されます。 DataStoreConstants::DATA_FLAG_NEED_COMPLETION を指定していない場合は DataStoreClient::PostObject() の完了と同時にサーバー上のデータが有効化されるため本関数の呼び出しは不要です。 一つのデータをアップロードする場合は本機能を使用する必要はありません。 DataStoreConstants::DATA_FLAG_NEED_COMPLETION を指定しない場合でも一つのデータに対するアトミック性は保証されており、一つのデータの一部だけがサーバーに登録されることはありません。

7.4.8. データ ID 指定アップロード

通常アップロードしたデータは、自動でデータ ID が採番されますが、あらかじめ決めたデータ ID に対してデータをアップロードしたい場合にデータ ID を指定してアップロードする機能が利用できます。 この機能を利用すると、指定したデータ ID にデータがない場合にはアップロードおよび評価スロットの初期化を行ってから、通常通り評価を行うといった流れの一連の処理を実現することができます。

評価については、上記の一連の処理を一括しておこなう DataStoreClient::RateObjectWithPosting(), DataStoreClient::RateObjectsWithPosting() があります。 これらは、データ ID で指定したデータが存在しない場合に評価の初期化と評価を同時に実行し、 データ ID で指定したデータが存在する場合に通常通り評価します。

この機能では、以下の制限があります。

  • 指定できるデータ ID は 900000 から 999999 までの範囲になります。負荷の関係上、アップロードする総データ数は、1万件程度にとどめてください。 通常のアップロードデータは 1000000 から採番されるため、範囲を超えて指定はできません。
  • ゲームサーバーのみの利用となり、ストレージサーバーへのデータアップロードはできません。
  • オーナー ID はシステム用のプリンシパル ID (2 番)で設定され、アップロード者のプリンシパル ID は反映されません。
  • データの有効期限は無期限となり、削除されません。
  • 参照権限、更新権限は DataStoreConstants::PERMISSION_PUBLIC 固定です。
  • DataStoreClient::DeleteObject() による削除はできません。削除が必要な場合は NMAS で削除を行うことができます。
  • DataStoreClient::ChangeMeta() によるデータの更新はできません。
  • タグは設定できません。
  • 永続化スロットへの設定はできません。

補足

DataStorePostParam の参照権限、更新権限のデフォルト値は DataStoreConstants::PERMISSION_PRIVATE となっているため、 DataStorePostParam::SetAccessPermission() 、 DataStorePostParam::SetUpdatePermission() を使用して、明示的に DataStoreConstants::PERMISSION_PUBLIC を設定してください。

DataStorePostParam で指定可能なものは一部に制限されており、 Table 7.1 のうち、名前、データタイプ、評価スロットの初期化設定、メタバイナリのみです。

  • DataStorePostParam::SetName()
  • DataStorePostParam::SetDataType()
  • DataStorePostParam::SetRatingSetting()
  • DataStorePostParam::SetMetaBinary()

上記以外のメソッドを呼び出して初期値以外の値をセットした場合、 DataStoreClient::PostObject() 呼び出し時にエラーとなり、 QERROR(DataStore, InvalidArgument) が返却されます。

  • 一括処理

    複数のデータ ID を指定してアップロードすることができます。 最大 BATCH_PROCESSING_CAPACITY_POST_OBJECT 個指定できます。

  • 実行時のエラー

    CallContext::GetOutcome() で以下のエラーが返ります。 - QERROR(DataStore, OperationNotAllowed): 指定したデータ ID にはすでにデータが存在する。 - QERROR(DataStore, InvalidArgument): パラメータが不正である。

7.5. データのダウンロード

アップロードしたデータのダウンロードには DataStoreClient::GetObject() を使用します。データのダウンロードには以下の方法が用意されています。

  • 引数に直接バッファを指定する方法

    buffer 引数にダウンロードするデータを保存するバッファへのポインタを指定し、bufferSize 引数にバッファのサイズを指定します。 buffer のサイズはダウンロードするデータより大きい必要があります。

  • イベントリスナーを利用する場合

    eventListener 引数に DataStoreGetObjectEventListener を継承し DataStoreGetObjectEventListener::ProcessResponse() を オーバーライドしたクラスのオブジェクトを指定します。 メモリを一度に確保できないときなど、分割してデータをダウンロードしたい場合に使用してください。

注意

イベントリスナーを使用する場合、オーバーライドしたクラスの DataStoreGetObjectEventListener::ProcessResponse() の返値で一定時間 false を返し続けるとストレージサーバとの接続が切れるためデータのダウンロードに失敗します。10 秒以上 false を返す実装は避けてください。また、本機能はフローコントロール用途に使用し、ダウンロードの一時停止を目的としては使用しないでください。

正常に処理が成功した際には、データアップロード時に DataStoreConstants::DATA_FLAG_PERIOD_FROM_LAST_REFERRED を指定している場合、有効期限が更新されます。 詳細については 7.16.2. を参照してください。

注意

ストレージサーバーを利用しない場合は DataStoreClient::GetObject() は利用できません。 データを取得したい場合はメタ情報の取得( 7.11. )、DataStoreClient::GetMeta() を使用してください。

7.6. データの更新

アップロードしたデータの更新には DataStoreClient::UpdateObject() を使用します。 データの更新には以下の方法が用意されています。イベントリスナーはメモリを一度に確保できなく、分割してデータをアップロードしたい場合などに使用してください。

  • バッファを利用する場合

    引数には、ProtocolCallContext オブジェクトへのポインタ、DataStoreUpdateParam オブジェクト、アップロードしたいバッファへのポインタ、バッファの内容をライブラリ内部にコピーするかを指定します。

  • イベントリスナーを利用する場合

    引数には、ProtocolCallContext オブジェクトへのポインタ、DataStoreUpdateParam オブジェクト、 DataStorePostObjectEventListener オブジェクトへのポインタを指定します。

正常に処理が成功した際には、更新したデータのメタ情報である更新日時、有効期限が更新されます。 詳細については 7.16.2. を参照してください。

注意

ストレージサーバーを利用しない場合は DataStoreClient::UpdateObject() は利用できません。 データの更新をしたい場合はメタ情報の更新( 7.12. )、DataStoreClient::ChangeMeta() を使用してください。

7.7. データの削除

アップロードしたデータの削除には DataStoreClient::DeleteObject() を使用します。 一度削除したデータについてはデータの復元などはできませんので、注意してください。 永続化スロット ID を指定してデータを削除する場合は DataStoreClient::UnperpetuateObject() を使用してください。 永続化されているデータを削除した場合は自動的に非永続化されます。

7.7.1. 一括処理

アップロードしたデータを一括して削除することが可能です。単体削除の時と同様に DataStoreClient::DeleteObject() を使用します。

7.7.2. データの論理削除と物理削除

DataStoreClient::DeleteObject() によって手動で削除されたデータは論理削除の状態になります。DataStorePersistenceInitParam::SetDeleteLastObject() に true を指定した場合も同様に論理削除の状態になります。論理削除されたデータは取得や復元などはできませんが、サーバー上のデータとしては存在し続けます。 その後、データに設定された有効期限を超過した時に物理削除の状態になります。物理削除が行われた時、データはゲームサーバー及びストレージサーバーから完全に削除されます。

7.9. データ ID の表示について

データ ID をそのまま表示することでアプリケーションによってはサービス規模や成長度が比較的容易に推測できたり、データ ID によって検索できる仕様の場合に、想定していない ID を指定されて不正にデータを取得される危険があります。

DataStoreDataCode クラスでデータ ID を変換することで、タイトルごとに独立した簡単には予測できない、アプリケーション内での表示に適したデータコード文字列を取得することができます。

データコード文字列とは、データ ID (最大 56 ビット) と チェックサム (8 ビット) を含む、 0 1 2 3 4 5 6 7 8 9 B C D F G H J K L M N P R T V W X Y の28文字 からなる 最大 14 文字の文字列です。 長さはデータ ID の値によって可変で、データ ID が 268,435,455 までの場合は、1 ~ 8 文字、 4,294,967,295 までで 1 ~ 9 文字となります。

データコード文字列は、 DataStoreDataCode::CreateFromDataId() で、DataStoreDataCode オブジェクトを取得して、 DataStoreDataCode::ToDataCodeString() で取得できます。 DataStoreDataCode::ToDataCodeStringZeroPad() で、データコードの上位を 0 で埋めて、14文字の固定長のデータコード文字列を取得できます。

また、データコード文字列からは、 DataStoreDataCode::CreateFromDataCodeString() で、DataStoreDataCode オブジェクトへ変換できます。 データコード文字列の妥当性は、 DataStoreDataCode::IsValid() で検証でき、 DataStoreDataCode::GetDataId() で、データ ID を取得できます。 DataStoreDataCode::CreateFromDataCodeString() では、データコード文字列に小文字が含まれる場合には大文字に変換され、入力ミスが疑われる文字は適切な文字に変換されます。 (I->1, Q->0, O->0, Z->2, S->5)

DataStoreDataCode::CreateFromDataId() や DataStoreDataCode::CreateFromDataCodeString() では、チェックサム算出時の鍵として、自タイトルのアクセスキーを指定してください。 自タイトルのアクセスキーでなくても動作しますが、クライアント以外でのデータコード文字列の算出や検証ができなくなります。

7.10. データの評価

データストアではアップロードされたデータ ID 単位ごとにスロットと呼ばれるフィールドが 16 個用意されており、評価合計値、評価された回数の情報を持ち参照することができます。 5 段階評価での利用や「いいね!」といった不特定多数の人からの評価を付けてもらい参照するということを想定しています。

こちらの機能を利用するにはデータのアップロード時に必ず評価の初期化( 7.4.4. )をしておく必要があります。 初期化が済んでいるものについて以下にある機能が利用できます。

注意

評価合計値は 64 bit signed int の範囲に収まるように実装を行ってください。この範囲を超えた場合範囲内の上限値、下限値に丸められます。

  • 評価合計値の加減算

    評価合計値の加減算を行うには DataStoreClient::RateObject() を使用します。 評価の初期化をする際に用意したスロットに対してのみ評価できます。

  • 評価情報の取得

    評価情報や評価ログの取得を行うには DataStoreClient::GetRating() を使用します。 評価の初期化をする際に用意したスロットからのみ評価情報を取得できます。 評価情報は DataStoreRatingInfo 、評価ログは DataStoreRatingLog のオブジェクトで取得でき、ここから得られる情報はそれぞれ Table 7.9Table 7.10 となります。

  • 評価情報のリセット

    評価情報と評価ログをリセットするには DataStoreClient::ResetRating() を使用します。 評価合計値は初期値に戻り、評価された回数は 0 になります。評価ログはクリアされます。

7.10.1. 一括処理

Table 7.9 DataStoreRatingInfo で取得できる情報一覧
項目名 取得関数
評価合計値 GetTotalValue()
評価された回数 GetCount()
評価合計値の初期値 GetInitialValue()
Table 7.10 DataStoreRatingLog で取得できる情報一覧
項目名 取得関数
自分が過去に評価をしたか IsRated()
自分が前回評価をした際の評価値 GetRatingValue()
重複ロック解除日時 GetLockExpirationTime()

7.11. メタ情報の取得

アップロードしたデータのメタ情報の取得には DataStoreClient::GetMeta() を使用します。

取得したいメタ情報が、タグ、評価情報、メタバイナリ、権限を持ったプリンシパル ID の場合 DataStoreGetMetaParam::SetResultOption() に取得したいデータのフラグを指定してください。 処理が成功するとメタ情報の値が DataStoreMetaInfo オブジェクトに格納されます。 DataStoreMetaInfo オブジェクトから取得できる情報は Table 7.11 となります。

Table 7.11 DataStoreMetaInfo で取得できる情報一覧
項目名 取得関数
データ ID GetDataId()
プリンシバル ID GetOwnerId()
データサイズ GetSize()
ステータス GetStatus()
名前 GetName()
データタイプ GetDataType()
参照権限 GetAccessPermission()
更新権限 GetUpdatePermission()
作成日時 GetCreatedTime()
更新日時 GetUpdatedTime()
有効日数 GetPeriod()
設定フラグ GetDataFlag()
有効期限 GetExpireTime()
タグ GetTags()
評価情報 GetRating()
メタバイナリ GetMetaBinary()

7.11.1. 一括処理

アップロードしたデータのメタ情報を一括して取得することが可能です。単体取得処理と同様に DataStoreClient::GetMeta() を使用します。

注意

メタバイナリを含んだものを一括処理で取得する場合には、全体のサイズが大きくならないように取得数を調整し、実装を行ってください。 全体のサイズが大きい場合、パケットの転送効率が悪化してデータの取得時間が長くなる可能性があります。 目安としてメタ情報のメタバイナリの合計値が 20 KB 以下に収まるように、メタバイナリのサイズが 1 KB であれば一度に取得する件数を 20 件にするなど調整してください。

7.12. メタ情報の更新

アップロードしたデータのメタ情報の更新には DataStoreClient::ChangeMeta() を使用します。 更新したいメタ情報のフラグを DataStoreChangeMetaParam::SetModificationFlag() にセットしてください。 更新したいメタ情報としてセットできるフラグは Table 7.12 となります。

正常に処理が完了し、フラグに DataStoreConstants::MODIFICATION_FLAG_PERIOD、DataStoreConstants::MODIFICATION_FLAG_UPDATED_TIME をセットした場合 更新時間、有効期限は 7.16.2. のように更新されます。

Table 7.12 メタ情報変更フラグ一覧
フラグ 説明
DataStoreConstants::MODIFICATION_FLAG_NONE 設定なし
DataStoreConstants::MODIFICATION_FLAG_NAME タイトルを変更
DataStoreConstants::MODIFICATION_FLAG_ACCESS_PERMISSION 参照権限を変更
DataStoreConstants::MODIFICATION_FLAG_UPDATE_PERMISSION 更新権限を変更
DataStoreConstants::MODIFICATION_FLAG_PERIOD 有効日数を変更
DataStoreConstants::MODIFICATION_FLAG_METABINARY メタバイナリを変更
DataStoreConstants::MODIFICATION_FLAG_TAGS タグを変更
DataStoreConstants::MODIFICATION_FLAG_UPDATED_TIME 更新日時を現在時刻に更新
DataStoreConstants::MODIFICATION_FLAG_DATA_TYPE データタイプを変更
DataStoreConstants::MODIFICATION_FLAG_STATUS ステータスを変更

7.12.1. 一括処理

アップロードしたデータのメタ情報を一括して更新することが可能です。単体更新処理と同様に DataStoreClient::ChangeMeta() を使用します。

7.12.2. コンペアアンドスワップ

DataStoreChangeMetaParam::SetChangeMetaCompareParam() で DataStoreChangeMetaCompareParam を設定すると、メタ情報はコンペアアンドスワップで更新されます。 DataStoreChangeMetaCompareParam には、比較する情報のフラグと値を設定します。

この時、設定した値と実際の値が一致しなかった場合は変更されず、 CallContext::GetOutcome() で QERROR(DataStore, ValueNotEqual) が返ります。

Table 7.13 メタ情報比較フラグ一覧
フラグ 説明
DataStoreConstants::COMPARISON_FLAG_NONE 設定なし
DataStoreConstants::COMPARISON_FLAG_NAME タイトルを比較
DataStoreConstants::COMPARISON_FLAG_ACCESS_PERMISSION 参照権限を比較
DataStoreConstants::COMPARISON_FLAG_UPDATE_PERMISSION 更新権限を比較
DataStoreConstants::COMPARISON_FLAG_PERIOD 有効日数を比較
DataStoreConstants::COMPARISON_FLAG_METABINARY バイナリデータを比較
DataStoreConstants::COMPARISON_FLAG_TAGS タグを比較
DataStoreConstants::COMPARISON_FLAG_DATA_TYPE データタイプを比較
DataStoreConstants::COMPARISON_FLAG_STATUS ステータスを比較
DataStoreConstants::COMPARISON_FLAG_ALL すべて比較

7.13. いつの間に通信との連携

いつの間に通信( BOSS )を使って、アプリケーションが起動していないときでもバックグラウンドで DataStore のサーバーにアクセスし、 データをアップロードしたりダウンロードしたりすることができます。

この機能は CTR_SDK に含まれる BOSS を利用します。 タスクの登録方法や BOSS ストレージの使用方法については「CTR プログラミングマニュアル 無線通信編 4.2 いつの間に通信」を参照してください。 この機能を利用するには事前に OMAS での申請が必要です。BOSS の API を利用する前に NEX の初期化やゲームサーバーへの接続を行う必要はありません。

注意

DataStore アップロードタスクと DataStore ダウンロードタスクには、ユーザーにサービス終了を通知する仕組みはありません。 サービスが終了したことをユーザーへ通知する必要がある場合は以下のような手段でサービス終了を検知してください。

CTR で 本機能を利用する場合はデータ ID が 32 ビットの範囲を超えないようにしてください。

7.13.1. アップロード

いつの間に通信を利用した DataStore のアップロードは nn::boss::DataStoreUploadAction クラスをタスクに登録することにより行うことができます。 DataStore アップロードタスク一つに付き一つのデータをアップロードできます。 複数のデータをアップロードしたい場合や宛先ごとにデータ内容を変えたい場合はデータ数分のタスクを用意する必要があります。 いつの間に通信で DataStore にアップロードするときに必要なゲームサーバーの設定パラメータは Table 7.14 の通りです。

Table 7.14 いつの間に通信でアップロードするときのゲームサーバー設定パラメータ
項目名 設定可能な値 設定関数
ゲームサーバ ID OMAS で発行されたもの nn::boss::DataStoreUploadAction::Initialize()
アクセスキー OMAS で発行されたもの nn::boss::DataStoreUploadAction::Initialize()

いつの間に通信でアップロードできるデータのパラメータは Table 7.15 の通りです。 設定関数が「なし」となっているものはすべて固定値となります。 設定フラグには DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST が指定されています。 これは参照権限で指定された参照可能者に対して通知を送るオプションです。 この通知を受け取った人は BOSS のダウンロード( 7.13.2. 参照)でこのデータを受信することができます。

注意

通知はストレージサーバへのアップロードが完了したタイミングで開始されます。ストレージサーバを利用せず、メタバイナリのみアップロードを行った場合には通知は送られません。

Table 7.15 いつの間に通信でアップロードされるデータのパラメータ
項目名 設定可能な値 設定関数
サイズ nn::boss::DataStoreUploadAction::Initialize() で指定したファイルハンドルが指すファイルのサイズが自動的にセットされます。 自動的にセットされます
名前 空文字列。 なし
データタイプ 任意の値。 nn::boss::DataStoreUploadAction::Initialize()
参照権限
nn::boss::DstKind_FRIEND (DataStoreConstants::PERMISSION_FRIEND と同等)
nn::boss::DstKind_SPECIFIED (DataStoreConstants::PERMISSION_SPECIFIED と同等)
nn::boss::DstKind_SPECIFIED_FRIEND (DataStoreConstants::PERMISSION_SPECIFIED_FRIEND と同等)

nn::boss::DstKind_SPECIFIED もしくは nn::boss::DstKind_SPECIFIED_FRIEND を指定した場合は宛先のプリンシパルIDを指定する必要があります。100個まで指定可能です。
nn::boss::DataStoreUploadAction::Initialize() および nn::boss::DataStoreUploadAction::AddDstPrincipalId()
更新権限 DataStorePermission( DataStoreConstants::PERMISSION_PRIVATE ) なし
設定フラグ DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST なし
有効日数 1~365 nn::boss::DataStoreUploadAction::Initialize()
タグ なし
評価スロットの初期化情報 なし
メタバイナリ なし
永続化設定 DataStorePersistenceInitParam() なし

注意

一度アップロードが成功したタスクはその後何も行いません。つまり消尽回数を 2 以上にしてもデータが複数アップロードされることはありません。 消尽回数を増やすと、アップロードエラーになった場合にその回数分リトライが行われるようになります。 DataStore のアップロードタスクでデータがサーバーにアップロードされたかどうかをアプリケーションから正確に判断する方法はありません。

参照権限に nn::boss::DstKind_FRIEND もしくは nn::boss::DstKind_SPECIFIED_FRIEND を指定した場合は、データアップロード時とダウンロード時の二つのタイミングで相手とフレンド関係が結ばれているかどうかがチェックされます。 この挙動に問題がある場合は nn::boss::DstKind_SPECIFIED を使用し、ダウンロード時にデータのオーナーが自分のフレンドであるかどうかを確認する実装をしてください。

7.13.2. ダウンロード

自分宛に通知する設定をしてアップロードされたデータを、いつの間に通信でダウンロードすることができます。 具体的には 7.4.2. の補足に記載されたパラメータをセットしてアップロードされたデータと、いつの間に通信でアップロードされたデータ( 7.13.1. 参照)が対象となります。 いつの間に通信を利用した DataStore のダウンロードは nn::boss::DataStoreDownloadAction クラスを BOSS タスクに登録することにより行います。 タスクの登録方法については「CTR プログラミングマニュアル 無線通信編 4.2 いつの間に通信」を参照してください。 DataStore ダウンロードタスクの登録は 1 ゲームサーバーにつき一つまでです。一つのタスクで自分に通知されたデータをすべて受信します。

いつの間に通信を使って DataStore からダウンロードするときに必要なゲームサーバーの設定パラメータは Table 7.16 の通りです。

Table 7.16 いつの間に通信でダウンロードするときのゲームサーバー設定パラメータ
項目名 設定可能な値 設定関数
ゲームサーバ ID OMAS で発行されたもの nn::boss::DataStoreDownloadAction::Initialize()
アクセスキー OMAS で発行されたもの nn::boss::DataStoreDownloadAction::Initialize()

データがダウンロードされたときにユーザーに受信を知らせるために、おしらせリストにおしらせを出すことができます。 nn::boss::DataStoreDownloadAction::SetNewsPublication() を呼び出すことによりおしらせ発行の有効化および設定を行います。 nn::boss::DataStoreDownloadAction::SetNewsPublication() で指定するパラメータの第一引数 (おしらせのシリアル ID) には必ず任天堂から発行された ID を指定してください。おしらせの内容は定型文となります。送信元や受信データ内容によって文面を変更することはできません。

ダウンロードされたデータに付加されているメタ情報が格納されている場所は Table 7.17 の通りです。

Table 7.17 いつの間に通信でダウンロードするときのゲームサーバー設定パラメータ
メタ情報名 格納されている NS データパラメータ名
データ ID シリアル ID
データタイプ プライベートデータタイプ

DataStore のダウンロードタスクが登録されると、設定された実行間隔で自分宛に通知が送られてきていないかをサーバーに問い合わせます。 送られていることを確認したらそのデータのダウンロードを行い BOSS ストレージに書き込まれます。 データのダウンロードは通知を受けた順に直列で行われます。BOSS ストレージがいっぱいになると古いデータから自動的に削除されます。

注意

タスクにはどこまでデータをダウンロードしたかが記録されています。 そのためタスクが存在する限りデータが二重にダウンロードされることはありませんが、タスクが削除された後にタスクを再登録した場合は過去に受信したデータを再度受け取ることがあります。 このとき再受信するデータは最大で過去 20 件分です。 重複したデータをユーザーに見せないようにするには過去 20 件分の受信済みシリアル ID をアプリケーションで覚えておく等の対策を採ってください。

7.14. データの永続化

通常アップロードしたデータは有効期限が切れると自動的に削除されますが、永続化機能を使用することにより自動削除されないように設定できます。 ユーザー一人につき最大 16 個のデータを永続化できます。 永続化されたデータはプリンシパル ID と 永続化情報を保存するスロット ID (永続化スロット ID: 0 ~ 15) で参照することができます。 以下のような利用を想定しています。

  • すべてのプレイヤーは永続化スロット ID の 0 番にプロフィール情報を保存したデータ ID を保存しておく。 ネットワーク上で出会った他のプレイヤーの情報を永続化スロット ID の 0 番から取得する。 この手法を使うと別途データ ID を交換する必要が無くなり、なおかつ常にデータが存在することを保証できます。
  • ランキングライブラリを使いスコアをアップロードする際に、スコアと関連する情報を別途データストアにアップロードして永続化し、その永続化スロット ID をランキングのパラメータに保存する。 この手法を使うとランキングには登録されているがデータストアのデータだけ有効期限切れし不整合が発生するといった現象を防ぐことができます。

7.14.1. 永続化する

すでにアップロードしてあるデータを永続化するには DataStoreClient::PerpetuateObject() を使用します。 永続化を行うと有効期限が DataStoreConstants::PERMANENT_DATE_TIME となります。 もし以前に同じ永続化スロット ID を使っていた場合は、そのデータは非永続化されます。 同じデータ ID を複数の永続化スロットに設定することはできません。

新規にデータをアップロードすると同時に永続化するには DataStoreClient::PostObject() 呼び出し時に指定する DataStorePostParam クラスのオブジェクトに対して永続化設定を行います。 具体的には、DataStorePostParam::SetPersistenceInitParam() を使い、永続化スロット ID を指定した DataStorePersistenceInitParam クラスのオブジェクトをセットすることで永続化が行われるようになります。 過去に同じ永続化スロット ID が使われていた場合、以前のデータは非永続化されます。 非永続化と同時にデータを削除する場合は DataStorePersistenceInitParam::SetDeleteLastObject() で true を指定します。 この一連の処理は一貫性を持って行われるため、DataStoreClient::PostObject() 呼び出し前後で永続化スロットに設定されているデータ ID は常に有効な値となります。 つまり DataStoreClient::GetObject() および DataStoreClient::GetMeta() でデータを参照する際に取得対象をデータ ID ではなく DataStorePersistenceTarget を使い永続化スロット ID で指定すると常に有効なデータを取得できます。 この特性は DataStorePersistenceInitParam::SetDeleteLastObject() での設定にかかわりません。

7.14.2. 非永続化する

永続化されたデータを元に戻すには DataStoreClient::UnperpetuateObject() を使用します。 非永続化するとデータが自動的に削除されるように戻ります。非永続化されたデータの有効期限が現在時刻プラス有効日数となります。 なお、DataStoreClient::DeleteObject() でデータを削除すると自動的に対応する永続化スロットから外され非永続化されます。 DataStoreClient::UnperpetuateObject() で過去のデータを削除するオプションを有効にした場合は実質的に DataStoreClient::DeleteObject() で データを削除した場合と同じ動作になります。

7.14.3. 永続化情報を取得する

プリンシパル ID と永続化スロット ID からデータ ID 取得するには DataStoreClient::GetPersistenceInfo() を使用します。 一つの永続化スロット ID を指定する単体取得と、複数の永続化スロット ID を指定する一括取得する API があります。

7.15. パスワードの取得

アップロードされたすべてのデータには参照パスワードと更新パスワードが設定されます。 パスワードを他人に伝えることにより事前に権限を与えられていないユーザーから対象のデータを操作できるようになります。 パスワードについての詳細は 7.4.2. を参照してください。 パスワードを取得するには DataStoreClient::GetPasswordInfo() を利用します。

7.16. データストアにおける共通仕様

7.16.1. データのステータス

アップロードしたデータにはそれぞれステータスを持ち、それによって行える操作が変化します。 ステータスは DataStoreClient::GetMeta() で取得できます。

Table 7.18 データステータス
データステータス 説明
NONE 通常状態です。アップロードが完了したデータはこのステータスに自動的に遷移します。設定した権限やパスワードに応じて参照・変更が可能です。
CREATING データをアップロード中です。オーナーを含め誰からも参照・変更できません。
PENDING 審査中のデータです。 DataStoreConstants::DATA_FLAG_NEED_REVIEW のフラグを付けてアップロードしたデータは NONE の代わりにこのステータスに遷移します。設定した権限やパスワードでのアクセスはできず、参照・変更共にオーナーのみが行えます。
DELETING 削除リクエストを受け付けたデータです。オーナーを含め誰からも参照・変更できません。 DataStoreClient::DeleteObject() や NMAS でデータを削除するとこのステータスに遷移します。その後有効期限が切れると自動的に DELETED に遷移します。
DELETED ストレージサーバーに対して削除処理が実行されたデータです。オーナーを含め誰からも参照・変更できません。有効期限が切れたデータはこのステータスに遷移します。その後自動的にレコードが削除されます。
REJECTED 審査で却下されたデータです。システムがデータをこのステータスに自動的に遷移させることはありません。 PENDING と同様に設定した権限やパスワードでのアクセスはできず、参照・変更共にオーナーのみが行えます。

CREATING, DELETING, DELETED のデータはクライアントから参照することができず、 NMAS からのみ存在を確認できます。 NMAS からデータを操作することにより、 NONE, PENDING, DELETING, REJECTED の間をお互いに遷移させることができます。 NONE, PENDING, REJECTED へはデータの編集で、 DELETING へはデータの削除を行うことにより遷移が可能です。

DELETING に一度でも遷移させたデータはいつの間に通信を使って受信することができなくなります。

7.16.2. タイムスタンプ値の変化について

データストアの各 API 利用時のタイムスタンプ値がどのように変化するかについてまとめたものが Figure 7.2 となります。

_images/Fig_Datastore_Timestamp.png

Figure 7.2 API 利用時のタイムスタンプ値の変化

DataStoreClient::TouchObject() は、データの有効期限を更新する機能です。 ストレージサーバーを利用しないメタバイナリのみのデータや、評価情報などその他のメタデータを参照した際に、データのダウンロード ( 7.5. ) 時と同様に有効期限を更新したい場合は、DataStoreClient::TouchObject() をご利用ください。 ただし対象のデータのアップロード時に DataStoreConstants::DATA_FLAG_PERIOD_FROM_LAST_REFERRED を指定している必要があります。

7.16.3. 一括処理における注意点

いくつかの API には一度に複数のデータを処理できるオーバーロード関数が用意されています。 一括で処理できるのは最大で 100 件となります。100 件以上処理する必要がある場合は 100 件以下に分割して本関数を複数回呼び出してください。

非同期処理が失敗した場合はデータごとの結果(qVector<qResult>)には値が格納されません。 CallContext::GetState() で非同期処理が成功したことを確認した後、必要に応じて qVector<qResult> を確認してください。 すべて成功する場合のみ処理を行うかのフラグが用意されている関数の場合、これを true とすると処理中に最初に発生したエラーが CallContext::GetOutcome() で取得できます。その場合サーバー上のデータは変更されません。 なお、qResult に格納された結果のうち処理が成功しているかどうかについては QSUCCEEDED マクロまたは qBool へのキャストで判定してください。

7.16.4. HTTP 通信時の注意点

HTTP の処理中に ProtocolCallContext::Cancel() で処理をキャンセルした時点や DataStoreClient オブジェクトを破棄した時点では、 HTTP 処理が完了していることは保証されません。 HTTP の処理が完了していることが保証されるのは、 NgsFacade オブジェクトが破棄された時ですので、 nn::http::Finalize() する前に、 NgsFacade オブジェクトが破棄されているようにしてください。

7.17. エラーハンドリング

エラーハンドリングの方法についてはマッチメイクと同じとなりますので、 4.25. を参照してください。 データストアで発生しうるエラーについては Table 7.19 となります。 ただし、NEX の通信処理等で発生する共通エラーを除いています。

Table 7.19 データストアエラー一覧
ReturnCode 値 概要
QERROR(DataStore, Unknown) 不明なエラー。サーバーで予期せぬエラーが起きた場合に発生する可能性があります。
QERROR(DataStore, InvalidArgument) 引数が不正。アプリケーションの実装の誤りにより発生します。
QERROR(DataStore, PermissionDenied) 権限を持っていないデータに対してパスワードを指定せずに操作しようとした場合に発生します。基本的にはアクセス権限がないデータはそもそも ID がわからないのでこのエラーは発生しないはずです。ただしなんらかの方法でデータ ID がわかった場合などに発生する可能性があります。アプリケーションでハンドリングすべきエラーです。
QERROR(DataStore, NotFound) 指定したデータ ID や 永続化スロット にデータが見つからない。アプリケーションでハンドリングすべきエラーです。
QERROR(DataStore, AlreadyLocked) 未使用です。現在発生することはありません。
QERROR(DataStore, UnderReviewing) 審査中のため参照不可。オーナー以外からデータステータスが PENDING もしくは REJECTED のデータを参照・更新しようとしたときに発生します。基本的には PENDING や REJECTED のデータをオーナー以外が見つけることはできないためこのエラーは通常発生しません。ただしなんらかの方法でデータ ID がわかった場合などに発生する可能性があります。アプリケーションでハンドリングすべきエラーです。
QERROR(DataStore, Expired) 未使用です。現在発生することはありません。
QERROR(DataStore, InvalidCheckToken) 未使用です。現在発生することはありません。
QERROR(DataStore, SystemFileError) システムファイルの読み込みに失敗。基本的には発生しないエラーです。
QERROR(DataStore, OverCapacity) 一括処理できる数を超えている。アプリケーション側での実装の誤りにより発生します。
QERROR(DataStore, OperationNotAllowed) 要求された操作は許可されていない。アプリケーション側での実装の誤りにより発生します。
QERROR(DataStore, InvalidPassword) 権限を持っていないデータに対して誤ったパスワードを指定して操作しようとした場合に発生します。アプリケーションでハンドリングすべきエラーです。
QERROR(Transport, DnsError) ストレージサーバーとの HTTP 通信時に DNS に関するエラーが起きた場合に発生します。
QERROR(Transport, ProxyError) ストレージサーバーとの HTTP 通信時にプロキシに関するエラーが起きた場合に発生します。
QERROR(Transport, ConnectionReset) ストレージサーバーとの HTTP 通信中にコネクションが切断された場合に発生します。
QERROR(Transport, Unknown) ストレージサーバーとの HTTP 通信時にその他通信エラーが起きた場合に発生します。

7.18. NEX ゲームサーバ管理ツール (NMAS)

NEX ゲームサーバ管理ツール (NMAS, Nex server MAnagement System) のデータストア管理機能では、データストアにアップロードされたデータの閲覧やダウンロードなどを行うことができます。 開発環境、製品環境のどちらも対応しています。

7.18.1. NMAS へのアクセス方法

NMAS へは以下の URL からアクセスすることができます。

https://nmas.mng.nintendo.net/nmas/

ログイン ID とパスワードは OMAS と同じものを使用してください。