處理資料儲存的 API 請求

在向 標準資料儲存 和 訂購資料儲存 傳送請求之前，您需要了解如何正確處理它們。有關API使用的資訊，請參閱使用指南。

授權

與所有開放雲端 API 一樣，數據存儲端點需要所有請求包含 x-api-key 頭籤，包含具有足夠權限的 API 鑰匙，用於回邀請。這需要您將鑰匙應用到體驗和資料商店 商家存中，並允許端點操作。如果鑰匙無效，403 Unauthorized將被返回。有關API鑰匙的更多資訊，請參閱管理API鑰匙。

限制速度

所有終端點都有兩種宇宙等級限制： 每分鐘請求限制 和 吞吐量限制 。每次體驗時， 每分鐘請求限制 讓您每分鐘發送一定數量的請求， 吞吐限制 讓您每分鐘發送一定數量的數據，無論API鑰匙數量如何。

與 Luau API 不同，這些限制目前不會根據使用者數量進行縮放。超出這些限制會導致端點返回 429 Too Many Requests 。

標準數據儲存限制速度

排序數據儲存限制速度限制

輸入驗證

在傳送請邀請之前，請確認端點參數是否符合以下表格要求和限制。個別終端可能有超出這些要求的額外需求。如果參數不符合以下限制，端點將返回 400 Bad Request 。

宇宙ID

宇宙ID 是您想要存取數據儲存的體驗唯一標識。體驗宇宙ID的值是其 的值，與開始地點ID不同，它標識體驗的開始地點而不是整個體驗。

您可以透過以下步驟獲得體驗的 宇宙ID ：

1. 導航到 創作者面板。

2. 找到您想要使用權 通行權 存取取的資料儲存體驗。

3. 將鼠標懸停在體驗縮略縮圖上，點擊 ⋯ 按鈕，然後選擇 複製宇宙ID 。

   

範圍

您可以透過設定獨特字串為範圍來組織數據儲存，指定入口的子目錄。一旦您設置範圍，它將自動添加到所有操作在資料商店 商家存上執行的所有鍵。範圍是可選的，並且默認為 global 對標準資料儲存來說，但對訂購的資料儲存來說是必需的。

範圍會將您的資料分類為字串和與 "/" 分隔符，例如：

所有數據儲存入口操作方法都有 Scope 參數，當您需要存取非預設範圍下儲存的入口時。例如，你可能會在預設的 1234 範圍下擁有一個 global 鑰匙，在 special 範圍下擁有相同的鑰匙。你可以不使用範圍參數來存取前者，但要存取後者，你必須在 或 API呼叫中指定範圍參數為 。

此外，如果您想枚舉一個或多個非預設範圍的數據儲存中所儲存的所有鑰匙，您可以在 方法中設置 參數為 ,在此情況下，呼叫返回包含鑰匙字串和範圍的tuple。在上一個例子中， List Entries 將返回兩者（1234， global）和（1234， special）在回應中。

您不能在同一請邀請中傳送 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)
# 將所有範圍設為真實的列鑰
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":""}

// 對於 AllScopes 的回應
{"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檢查sum。它是可選的 設定入口 端點的要求頭，用於檢查數據完整性並偵測潛在問題。

您可以使用自選語言來計算 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 值時遇到問題，您可能需要在計算檢查sum之前將請求體編碼為 UTF-8 二進制格式。

指標

返回數據列表的終端點也可能返回 nextPageCursor 字串。這表示在要求的結果設定中有更多可用的資料。要收到它，在下一個請邀請上提供此字串在 cursor 查詢參數。如果커서參數提供但無效，端點返回 400 Bad Request 。

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

過濾器

當向 List 方法發送訪問請求給訂購的數據儲存時，您可以添加可選的 filter 查詢參數來返回值在指定範圍內的入口。

filter支持一個邏輯運算符，&&，和兩個比較運算符，<=用於設置最大值和>=用於設置最小值。如果您想設置帶有最大值和最小值的範圍，請在兩個順序之間添加 &&。

例如，要返回值小於或等於 10 的入口記錄，您需要輸入 entry <= 10 作為 filter 值。要返回值在 10 和 50 之間的輸入，輸入 entry <= 50 && entry >= 10 。

以下例子是錯誤的 filter 值，可能會導致請求失敗：

• entry <= 10 - 每個部分之間沒有空格。
• 10 <= entry - entry 和比較值在錯誤的一邊。
• entry <= 10 && entry <= 50 - && 只能用於指定兩個比較操作符的範圍，用於最小值和最大值。

允許缺少的旗幟

當向 Update 方法發送要求以更新現有命令的數據存儲入口時，您可以添加可選的 allow_missing 標籤，以允許即使入口不存在，也可以創建一個入口。

當您將 allow_missing 旗設為 True 時：

• 如果入口不存在，回應將返回新的入口。

• 如果入口存在但內容與現有入口的值匹配，現有入口將保持不變。

• 如果入口存在且內容不與現有入口值匹配，回應將返回包含更新的新內容值的入口。