處理資料儲存 API 請求 | 文件

在發送要求到開放雲端 API 以儲存標準資料存檔和指定資料存檔之前，您需要了解如何正確處理它們。有關 API 使用方式的資訊，請參閱使用指南。

授權

與所有開放雲 API 相同，資料存取端口需要所有請求包含 x-api-key 標題，包含足夠的權限為請邀請。這需要您將鑰匙應用到體驗和資料存商店商家，並且允許端口操作。如果鑰匙無效，403 Unauthorized 將

Throttling

所有端點都有兩種宇宙級別的限制：請求每分鐘限制和通過限制。與每個體驗，請求每分鐘限制允許您發送特定數量的請求每分鐘，並且2>通過限制2>允許您發送特定數據每分�

與 Lua API 不同，這些限制目前不會依據使用者數量來調整。超出這些限制會導致端口發出 429 Too Many Requests。

一般資料商店限制

請求類型	方法	限制馬力
寫入	設定入口增量入口刪除入口 >	10 MB/分鐘/宇宙書寫輸出 300 需要/分鐘/宇宙 >
閱讀	清單資料存取器清單項目獲取項目 1> 列出版本1> 4> 獲取版本 4> >	20 MB/分鐘/宇宙書寫輸出 300 需要/分鐘/宇宙 >

已命令數據儲存限制

請求類型	方法	限制馬力
寫入	建立增量更新 1> 刪除 1> ”	300需求/分鐘/宇宙
閱讀	清單取得	300需求/分鐘/宇宙

輸入驗證

在發送請邀請之前，請確認端口參數在格式要求和限制按照以下表格式要求。個別端口可以有額外的要求。如果參數不滿足以下限制，端口將返回 400 Bad Request。

命令數據商店端點使用百分比轉碼對於所有的查詢和體參數。除非您在參數值中有特殊字符，否則您不需要處理轉碼自己。

輸入	類型	注意
universeId	數字	您的體驗獨一無二的識別器。請參閱宇宙ID 。 >
datastoreName	字串	長度必須為 50 位元或更小。不能為空或為零。
scope	字串	資商店商家存取的範圍。請參閱儲存存取的範圍。長度必須少於 50 位元。 >
entryKey	字串	長度必須為 50 位元或更小。不能為空或為零。
content-md5	字串	基礎 64 位碼 MD5 檢查摘要的內容。請參閱內容-MD5 。
roblox-entry-attributes	字串	由 JSON 對物件串化。長度必須少於 300 個字元。
roblox-entry-userids	字串	由JSON 0-4 數字串組合而成。不超過 4 個使用者ID。
cursor	字串	資料可用度指標。請參閱指標 Cursors。 >

宇宙 ID

宇宙 ID 是您想要存取資料儲存的體驗的獨一無二的識別器。體驗的宇宙 ID 值是體驗的 DataModel.GameId ，不是開始位置 ID ，它是體驗的起始位置。

您可以使用以下步驟獲得體驗的宇宙 ID ：

導航到創作者控制板。
查找您想要使用權通行權存取取的資料儲存。
點擊目標體驗的缩略圖上的 ⋯ 按鈕，顯示選項清單，然後選擇複製宇宙 ID 。

範圍

您可以設置獨一無二的字串作為範圍，指定對應入口的子目錄。一旦設置範圍，它就會自動預付在所有操作完成後的所有鑰商店商家上。鑰匙是可選的，並且預設為 global 對於標準資料存取。但對於已命名的資料存取，需要使用 local 作為預設值。

建議使用 prefix 參數，而不是 prefix 來排序和列出標準 scope 。

標準儲存鏡鏡會以字串和 "/" 分隔符來分類您的資料，例如：

鑰匙	範圍
房屋/User_1	房屋
ets/User_1	寵物
inventory/用戶_1	道具欄

所有數據存取入口操作方式都有一個 Scope 參數，當您需要存取非預設範��

此外，如果您想要列出所有存在於資料存取存在中有一個或多個非預設範圍的

您不能在同一個請邀請上傳 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

Content-MD5 是內容的基礎-64 編碼 MD5 檢查摘要。它是一個可選的請求標題，對於設置入口端口，檢查資料完整性並偵測潛在問題。

如果您沒有包含 content-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 字串。這表示要求結果設定中的資料數量增加。要獲得它，請在下一個邀請求參數中提供此字串。如果此參數為無效，則會返回 cursor 。

曲標字串的格式是未定義。你不應該將它們解釋或解析，因為它們可能會隨時變更。

過濾器

當發送要求到 List > 方法為已命名的數據儲存，您可以添加可選的 filter 查詢參數以返回具有指定範圍的結果。

篩選器ilter 參數支援一個論理運算器，&&，以及兩個比較運算器，<=，以設定最大值和1>>=1>，以設定最小值。如果您想要設置範圍，並且設置最大值和最小值，請在兩個順序之間添加 4>&&4> 。

例如，要以 entry <= 10 的值返回結果，您需要輸入 filter 作為 entry <= 50 && entry >= 10 值。要以 2>number12> 的值返回結果，您需要輸入 5>number15> 。

要輸入有效的 filter 值，你必須格式化每個 filter 字串之間的白格。左部分每個順序的字串必須以 Filter 開始，右部分必須有數字值。1> Filter1> 字串也是敏感的。

下列例子是不正確的 filter 值，可能會失敗您的請求：

entry <= 10 - 不要在每個部分的順序之間留白。
10 <= entry 和比較值在錯誤的一邊。
entry <= 10 && entry <= 50 至少需要使用兩個比較運算符號才能指定範圍，且最大值為 min 和 max。

允許遺失的旗幟

當發送要求到 Update > 方法更新已訂購的資料存入，您可以添加可選的 allow_missing 旗幟，允許創建存在即使資料沒有存在。

當你將 allow_missing 設定為 True 時：

如果沒有輸入，則會返回新的輸入。
如果條目存在，但條目的內容與條目的現有值相匹配，條目將保持不變。
如果存在入口，且內容與指定值不一致，則會以更新的新內容值將入口返回。