データストアのAPI リクエストを処理する

*このコンテンツは、ベータ版のAI（人工知能）を使用して翻訳されており、エラーが含まれている可能性があります。このページを英語で表示するには、 こちら をクリックしてください。

標準データストア と オーダードーデータストア のクラウド API へのリクエストを送信する前に、正しく処理する方法を理解する必要があります。API の使用に関する情報は、1>使用ガイド1> を参照してください。

認可

すべてのオープンクラウド API のデータストアエンドポイントは、リクエストに含まれる必要があります x-api-key ヘッダー、これには、リクエス保管に無効なパーミッションが含まれています。これにより、キーをエクスペリエンスに適

スロットリング

すべてのエンドポイントには、リクエスト-per-minute サロと、通信量-per-minute サロの 2種類の宇宙レベルの制限があります。すべてのエクスペリエンスで、リクエスト-per-minute サロ は、2>通信量-per-minute

Lua API とは異なり、これらの制限は現在ユーザーの数に基づいてスケールしません。これらの制限を超えると、エンドポイントが 429 Too Many Requests を返します。

標準データストアのスロットリング制限

リクエストタイプメソッドスロットルの制限
書き込む

  • エントリを設定する
  • エントリをインクリメントする
  • エントリを削除する
    • >

  • 10 MB/min/universe write throughput
  • 300 requs/min/universe
読む

    データストアをリストする データのエントリをリストする 入力を取得する 1> データのバージョンをリストする1>

    4> 入口バージョンを取得する

    4>

  • 20 MB/min/universe write throughput
  • 300 requs/min/universe

オーダーされたデータストアのスロットル制限

リクエストタイプメソッドスロットルの制限
書き込む
  • 作成
  • 増加
  • 更新

    • 1> 削除1> >

  • 300要求/分/宇宙
読む
  • リストを取得する
  • Get
  • 300要求/分/宇宙

入力の有効化

リクエストを送信する前に、フォーマット要件と制限に基づいてエンドポイントパラメータを検証してください。個々のエンドポイントは、次の表に基づく形式要件と制限を追加で持つことがあります。パラメータが次の制限を満たさない場合、エンドポイントは 400 Bad Request を返します。

入力タイプ注意
universeId番号

  • あなたのエクスペリエンスのユニークな識別子。参照 宇宙ID。
    • >

datastoreNameストリング

  • 長さは 50 バイト以下でなければなりません。
  • 空であってはなりません。
    • >

scopeストリング
  • データスト保管のスコープ。参照 スコープ。
  • 長さは 50バイト以下でなければなりません。
entryKeyストリング

  • 長さは 50 バイト以下でなければなりません。
  • 空であってはなりません。
    • >

content-md5ストリング

  • コンテンツのベース-64エンコードされた MD5 チェックサム
    • を参照してください。コンテンツ-MD5 。

    エクスポート用の MD5

roblox-entry-attributesストリング

  • JSON オブジェクトでサーマル化されます。
  • 長さは 300 バイト未満になる必要があります。
    • >

roblox-entry-useridsストリング
  • 0-4 数の JSON 配列でセリアライズされます。
  • 4 ユーザー ID 以上ありません。
cursorストリング

  • リクエストされた結果セットにあるデータの可用性を示すインジケーター。 参照 カーソル 。
    • >

ユニバースID

ユニバースID は、データストアにアクセスしたいエクスペリエンスのユニークな識別子です。エクスペリエンスの DataModel.GameId の値は、エクスペリエンスの開始場所IDであり、全体のエクスペリエンスではなく、開始場所のみを識別します。

次のステップで、エクスペリエンスの 宇宙ID を入手できます：

  1. ナビゲート to the クリエイターダッシュボード。

  2. アクセスしたいデータストアでエクスペリエンスを見つけます。

  3. ターゲットエクスペリエンスのサムネイルで ⋯ ボタンをクリックしてオプションのリストを表示し、 コピーユニバース ID を選択します。

    Copy Universe ID option from Creator Dashboard

スコープ

ユニークな文字列を設定して、エントリのサブフォルダを指定するサブフォルダを設定できます。スコープを設定すると、データストアで実行されるすべての操作のスコー保管が自動的に追加されます。スコープはオプションでデフォルトでは global ですが、注文されたデータストアの場合は必須です。

スコープは、「/」で構文子を分離したストリングとセパレーターで、データをカテゴライズします。たとえば：

キースコープ
住宅/ユーザー_1住宅
ペット/ユーザー_1ペット
インベントリ/User_1インベントリ

すべてのデータストア入力操作メソッドには、Scope パラメーターがあり、

さらに、データストアに 1つまたは複数の非デフォルトスコープを持つ場合、

同じリクエストで Scope と AllScopes パラメータを通過することはできません。そうしないと、呼び出しがエラーを返します。データストアモジュールのヘルプ機能から、カスタムスコープのパラメータを読み取るために、次のコードを示す：

異なるスコープのキーをリスト
# セットアップ

import tutorialFunctions

DatastoresApi = tutorialFunctions.DataStores()

datastoreName = "PlayerInventory"



# グローバルスコープのキーをリスト

specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global",  allScopes = False)

print(keys.content)

# 特殊なスコープのキーをリスト

specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)

print(keys.content)

# すべてのスコープのキーをリストする

specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)

print(specialScopeKeys.content)

対応するスコープのキーは、レポートで返されます:

異なるスコープの例の返答
// グローバルスコープのレポート

{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }



// 特殊なスコープの応答

{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}



// すべてのスコープに対するレポート

{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

コンテンツ-MD5

Content-MD5 は、ベース-64 エンコードされた MD5 チェックサム のコンテンツです。セットエントリ エンドポイントで、データの完全性をチェックし、潜在的な問題を検出します。

お選びの言語を使用して content-md5 ヘッダーの値を計算できます。次の例では、Python を使用しています。 hashlib.md5() および base64.b64Encode() 機能は、Python 標準ライブラリ (2.7、3+) で利用可能です。

コンテンツを MD5 に生成する
# プロンプト付き

$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"

content: 750

content-md5: sTf90fedVsft8zZf6nUg8g==

# 只今、stdin と stdout を使用しています

$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"

sTf90fedVsft8zZf6nUg8g==

有効な content-md5 値を生成する問題に遭遇した場合、チェックサムを計算する前に、リクエストボディを UTF-8 バイナリにエンコードする必要があります。

カーソル

データのリストを返すエンドポイントは、nextPageCursor のストリングを返すこともあります。これは、リクエストされた結果セットにより、より多くのデータが利用可無効であることを示します。 currency クエリパラメーターにこのストリングを提供すると、エンドポイントは

カーソルストリングの形式は 定義されていません です。あなたは彼らを解釈したり、解析したりするべきではありません、彼らはいつでも変更される可能性があります。

フィルタ

注文されたデータストアの List メソッドにリクエストを送信すると、入力に値が指定された範囲内にある filter クエリパラメータを追加して、入力を返すことができます。

filte並べ替え パラメータは、&& ロジックオペレータ、および、<= 比較オペレータをサポートしています。1> Filter パラメータは、最大値と最小値を設定するための 2つの比較オペレータ、1> を含みます。範囲を最大値

たとえば、10 未満の値を持つエントリを返すには、entry <= 10 を入力する必要があります。filter の値として、10 未満の値を返すには、entry <= 50 && entry >= 10 を入力する必要があります。0> number1 未満のエントリを返すには、0> を入力する必要がありま

次の例は、リクエストに失敗する可能性のある filter 値です：

  • entry <= 10 - 各パーツの間に白紙はありません。
  • 10 <= entry - 比較値は、entry と違う側にあります。
  • entry <= 10 && entry <= 50 - && は、入力の両方のオペレーターで最小値と最大値の両方を指定するのにのみ使用できます。

フラグの欠落を許可

既存の注文されたデータストアのエントリを更新するために、Update メソッドにリクエストを送信するとき、オプションのallow_missingフラグを追加して、エントリが存在しない場合でもエントリの作成を許可できます。

allow_missing フラグを True に設定すると：

  • もしエントリが存在しない場合、応答は新しいエントリを返します。

  • エントリが存在しているが、コンテンツがエントリの既存値と一致している場合、既存のエントリは変更されません。

  • エントリが存在し、コンテンツがエントリの既存値と一致しない場合、レポンスは、更新された新コンテンツの値をエントリに返します。