データストアへの API リクエストの処理

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

標準のデータストア と 注文のデータストア へのリクエストを Open Cloud API に送信する前に、それらを適切に処理する方法を理解する必要があります。API の使用に関する情報は、使用ガイド を参照してください。

認証

すべてのオープンクラウド API と同様、データストアエンドポイントには、リクエストに API キーが含まれる x-api-key ヘッダーを含むすべてのリクエス保管が必要です。これには、リクエストに十分な権限を持つ API が含まれています。これには、キーをエクスペリエンスとデータストアに適用し、エンドポイント操作が許可される必要があります。キーが無効である場合、403 Unauthorized が返されます。API キーに関する詳細情報は、API キーの管理 を参照してください。

スロットル

すべてのエンドポイントには、2種類のユニバースレベル制限があります： リクエスト毎分制限 と スループット制限 。すべてのエクスペリエンスで、 リクエスト毎分制限 は、分ごとに特定のリクエスト数を送信でき、 スループット制限 は、API キーの数に関係なく、分ごとに特定の量のデータを送信できます。

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

標準データストアは制限をスロットする

リクエストタ入力プ手法スロットル制限
書く
  • 入力を設定
  • 入力を増加
  • 入力を削除
  • 10 MB/min/universe 書き込み速度
  • 300 reqs/min/universe
読む
  • データストア一覧
  • エントリ一覧
  • エントリを取得
  • エントリバージョン一覧
  • エントリバージョンを取得
  • 20 MB/min/universe 書き込み速度
  • 300 reqs/min/universe

データストアの制限を設定した順序

リクエストタ入力プ手法スロットル制限
書く
  • 作成
  • 増加
  • 更新
  • 削除
  • 300reqs/min/universe
読む
  • リスト
  • 取得
  • 300reqs/min/universe

入力検証

リクエストを送信する前に、次の表に基づいて形式要件と制限に端末パラメータを有効化してください。Before sending your request, make sure to validate endpoint parameters on formatting requirements and constraints based on the following table.個々のエンドポイントには、これら以上の追加要件がある可能性があります。パラメータが次の制限を満たさない場合、エンドポイントは 400 Bad Request を返します。

入力種類ノート
universeId番号
  • あなたのエクスペリエンスのユニークな識別子。見る ユニバースID 。
datastoreName文字列
  • 長さは 50バイト以下でなければなりません。
  • 空白または null にはできません。
scope文字列
  • データストアの保管囲。スコープ を参照してください。
  • 長さは 50バイト以下である必要があります。
entryKey文字列
  • 長さは 50バイト以下でなければなりません。
  • 空白または null にはできません。
content-md5文字列
roblox-entry-attributes文字列
  • JSON オブジェクトでSerializationされます。
  • 長さは 300バイト未満である必要があります。
roblox-entry-userids文字列
  • 0-4の数字の JSON 配列でシリアライズ。
  • 4人のユーザーID 以上はありません。
cursor文字列
  • リクエストされた結果セットに利用可能なより多くのデータの指標。見る カーソル 。

ユニバースID

ユニバースID は、データストアにアクセスしたい経験の唯一の識別子です。エクスペリエンスのユニバースIDの値は、DataModel.GameId 、 同じではありません 、エクスペリエンスの開始場所を識別する 開始場所ID とは異なる、開始場所のエクスペリエンスではない値です。

次の手順で、エクスペリエンスの ユニバースID を取得できます：

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

  2. アクセスしたいデータストアをアクセス, 書き込み権限 (write access)つエクスペリエンスを見つけます。

  3. エクスペリエンスのサムネイルにカーソルを置き、 ⋯ ボタンをクリックし、 ユニバースIDをコピー を選択します。

スコープ

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

スコープは、文字列と「/」で区切られた分離符でデータをカテゴリ化します。たとえば:

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

すべてのデータストア入力操作方法には、非デフォルトのスコープで保存されたエントリにアクセスする必要があるときの Scope パラメータがあります。たとえば、デフォルトの 1234 スコープで global キーがあり、同じキーが special スコープでもあるかもしれません。前者にスコープパラメータを使用せずにアクセスできますが、後者にアクセスするには、スコープパラメータを に または API呼び出しで指定する必要があります。

さらに、データストアに 1つまたは複数の非デフォルトスコープがある場合、デフォルトではないスコープをすべて枚挙したい場合は、 メソッドの パラメータを に設定して、呼び出しはキー文字列とスコープを持つツプルを返します。前の例では、 は、応答で両方（》、》）を返し、》、》を返します。

同じリクエストで Scope と AllScopes パラメータを通過することはできません、そうしないとコールバックがエラーを返します。データストアモジュールのオープンクラウド APIからヘルプ機能を利用することで、次のコードは、カスタムスコープでデータストアのすべてのキーを読む方法を示しています：

異なるスコープのキーのリスト
# 設定する

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)

# すべてのスコープが true に設定されたキーのリスト

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

コンテンツ-MD5 は、コンテンツの ベース-64 符号化 MD5 チェックサム です。データの完全性をチェックし、潜在的な問題を検出する セットエントリ エンドポイントのオプションリクエストヘッダーです。

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

コンテンツ-MD5を生成中
# プロンプトで With prompts

$ 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 文字設定するを返す可能性もあります。これは、リクエストされた結果セットにより多くのデータが利用可能であることを示します。受け取るには、次のリクエストの cursor クエリパラメータにこの文字列を提供します。カーソルパラメータが提供されているが無効である場合、エンドポイントは 400 Bad Request を返します。

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

フィルタ

注文されたデータストアにリクエストを送信するとき、指定された範囲の値を持つエントリを返すためのオプションの メソッドへのクエリパラメータを追加できます。When sending requests to the method for ordered data stores, you can add an optional query parameter to return entries with values in a specified range.

filter パラメータは、1つの論理オペレーター、&&、および2つの比較オペレーター、<= で最大値を設定し、>= で最小値を設定します。最大値と最小値の両方を設定したい場合は、2つのシーケンスの間に && を追加します。

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

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

  • entry <= 10 - シーケンスの各部分間に白いスペースはありません。
  • 10 <= entry - entry と比較値が間違った側にあります。
  • entry <= 10 && entry <= 50 - && は、最小値と最大値の両方の比較演算子を使用して範囲を指定するのにのみ使用できます。

欠落したフラグを許可する

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

flag を に設定するとき：

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

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

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