資料儲存的使用指南 | 文件 - Roblox 創作者中心

除了使用 Studio 中的 Lua Class.DataStoreService 以及 Studio 或 live 服務器上使用 DataStoreService 來存取並使用標準和 2>預訂資料存2> 來自外部腳本和工具，您還可以使用 Open 雲 API 來存取並使用 5>預訂資料存5> 來自外部腳本和工具，並且具有粒度

開放雲端 API 對於已命令的資料儲存是可能在未來版本中發生變更的測試版 API。

使用

您可以通過使用這些 API 來改善您的工作流程，例如：

客戶支援門戶 : 資料存儲對於儲存持續使用者資源，例如物品在用戶道具欄或技能點中。有時候您需要更新這些資源，以幫助您的客戶服務代理處理客戶客服、客服人員援請求，例如查看和修改用戶道具欄和發出退款。而不是使用 Studio 或加入體驗每次手動更新，您可
生活眾計數據面板 : 您可以使用 API 構建生活眾計數據面板，例如舉辦活動預約。您可以在資料存存中的資料配商店商家中設置時間，以發佈事件。您的體驗伺服器可以檢測此變更，讀取旗幟以啟動事件。
外部排行榜 : 要在 Roblox 外促銷您的體驗，您可以將您的體驗的資訊提取，例如賽車排行榜，並在實時時間和顯示它在外部網站。您可以授予您的指定資料商店的閱取權限，以便網站定期要求您提供最新資料。
資料移行自動化 : 資料可能會隨著您的體驗進化而變更或更新，例如升級資料模型來容納新功能。要避免損失現有用戶資料，您可能需要將資料存存從舊資料庫轉移到新資料庫。您可以寫一個外部指令碼，讀取從當前資料庫存取新資料庫的資料，並

與 Lua API 的差異

雖然 Open Cloud API 與 Lua DataStoreService 相似，但有一些需要注意的要求：

宇宙 ID 和資料存取名稱 : 與 Lua API 不同，開放雲 API 是狀態無效的，因此您必須總是提供宇宙 ID ，您的體驗的唯一標識，並且在發送請求時提供資料存取名稱。有關如何獲得宇宙 ID 的更多資訊，請參閱
分開權限來創建和更新 : Lua API 在呼叫 DataStore:SetAsync() 時會創建新的項目，但 Open Cloud 方法為創建和更新項目是分開的。分開權限可以更安全、更靈活地在某些情況下使用。例如，您可以創建一個可以編輯現有用
資料串化 : 所有開放雲端端點都需要您將所有資料串化到網路之前。串化是將對象轉換為此字串的意思，解串是其反向操作 (將字串轉換為對物件)。 Lua API 會自動串化和解串入口內容，但對於開放雲端，您需要自行生成或解析您的入口資料。

安全許可

資料儲存通常存儲敏感信息，例如使用者個人資料和虛擬貨幣。為了保持安全，每個開放雲 API 的 API 有相應的需要權限，您必須將它們添加到您的 API 鍵匙中，例如清單 API 的權限。如果您未添加所需權限，您的 API 呼叫將返回

當設定您的 API 鑰匙時，您可以為每個資料存取內的每個資料存取權限，例如閱已讀、寫入和列出項目，或者您可以給鑰匙閱取或寫入所有資料存取。您也可以限制鑰匙對於您的工具而不是將所有資料存取暴露。這樣可以在您的鑰

建造工具

您可以使用您的選擇語言來建立工具，並使用開啟雲端 API 存取資料存儲庫來滿足您的操作需求。以下例子通過在 Python 中使用標準數據存儲庫和外部持續排名排行榜使用排名榜排名榜排名榜排名榜排名榜排名榜排名榜排名榜排名��

用戶庫存支援傳送門

這個區域提供一個具體的Python中的用戶倉庫支持傳送門，在這裡，您可以列出並查看一些用戶的倉庫道具，作出編輯，然後更新回到體驗資料商商店商家。

為此範例，假設以追蹤中內容：

儲存使用者道具欄的資料存取器的名稱為 Inventory。
每個資料欄位的資料櫃檯是 "userId": {"currency": number, "weapon": string, "level": number} 。鑰匙是 userId 。
Python 指令清單一個子集的用戶道具欄，依據條件增加其虛擬貨幣 10 促銷，並更新資料。

從高等級開始，您可以通過添加 API 鑰匙權限和添加指令碼來建立您的 Python 應用程式。

為數據儲存添加 API 鑰匙權限

當建立 API 鑰匙為此示例時，請確認您執行以下設定：

從選擇 API 系統選單在存取權限區域中選擇宇宙資料商店。
(可選) 在資料儲存區域中，選擇特定資料儲存的 API 操作。
1. 啟用特定數據儲存操作切換。預設情況下，五個數據儲存會自動載入，但您可以通過 + 新增數據儲存按鈕添加額外數據儲存。
2. 選擇資料存取名稱旁邊的拉下箭頭，然後選擇您想要資料存取存取到的 API 操作。
選擇 API 操作以整個體驗。
1. 點擊選擇要新增的體驗下拉欄，然後選擇體驗。
2. 在體驗運作中，單擊下拉箭頭並選擇您想要添加到 API 的操作。這個示例選擇閱取入口、更新入口和1>列入鑰匙1> 對於整個體驗。
  您不需要 create entries API 鑰匙許可權限，因為 app 不建立新的用戶倉庫。
在安全部分中，使用CIDR 語法來設定 IP 存取鍵，並設定一個明示的過期日期，讓您的鑰匙在該日期後自動停止運作。對於此示例，如果您計劃進行本地測試，您可以移除IP限制，將它設置為0.0.0.

為使用者帳號管理員設定網頁

在建立 API 鑰匙並獲得權限為範例應App所需的時候，您需要添加 Python 指令來執行應用功能。 data_stores_methods.py 檔案會顯示

數據儲存方法.py
import hashlib
import requests
import json
import base64

class DataStores:

    def __init__(self):
        self._base_url = "https://apis.roblox.com/datastores/v1/universes/{universeId}"
        # API 鑰匙會在 'API_KEY' 指定的環境變數中儲存
        self._apiKey = str(os.environ['API_KEY'])
        self._universeId = "UNIVERSE_ID"
        self.ATTR_HDR = 'Roblox-entry-Attributes'
        self.USER_ID_HDR = 'Roblox-entry-UserIds'
        self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry'
        self._increment_url = self._objects_url + '/increment'
        self._version_url = self._objects_url + '/versions/version'
        self._list_objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries'

    def _H(self):
        return { 'x-api-key' : self._apiKey }
    def _get_url(self, path_format: str):
        return f"{self._config['base_url']}/{path_format.format(self._config['universe_id'])}"

        return r, attributes, user_ids

def get_entry(self, datastore, object_key, scope = None):
        self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry'
        headers = { 'x-api-key' : self._apiKey }
        params={"datastoreName" : datastore, "entryKey" : object_key}
        if scope:
            params["scope"] = scope
        r = requests.get(self._objects_url, headers=headers, params=params)
        if 'Content-MD5' in r.headers:
            expected_checksum = r.headers['Content-MD5']
            checksum = base64.b64encode(hashlib.md5(r.content).digest())
            #print(f'Expected {Expected_checksum}, 得到了{checksum})

        attributes = None
        if self.ATTR_HDR in r.headers:
            attributes = json.loads(r.headers[self.ATTR_HDR])
        user_ids = []
        if self.USER_ID_HDR in r.headers:
            user_ids = json.loads(r.headers[self.USER_ID_HDR])

        return r

    def list_entries(self, datastore, scope = None, prefix="", limit=100, allScopes = False, exclusive_start_key=None):
        self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries'
        headers = { 'x-api-key' : self._apiKey }
        r = requests.get(self._objects_url, headers=headers, params={"datastoreName" : datastore, "scope" : scope, "allScopes" : allScopes, "prefix" : prefix, "limit" : 100, "cursor" : exclusive_start_key})
        return r

    def increment_entry(self, datastore, object_key, incrementBy, scope = None, attributes=None, user_ids=None):
        self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry/increment'
        headers = { 'x-api-key' : self._apiKey, 'Content-Type': 'application/octet-stream' }
        params={"datastoreName" : datastore, "entryKey" : object_key, "incrementBy" : incrementBy}
        if scope:
            params["scope"] = scope

        r = requests.post(self._objects_url, headers=headers, params=params)
        attributes = None
        if self.ATTR_HDR in r.headers:
            attributes = json.loads(r.headers[self.ATTR_HDR])
        user_ids = []
        if self.USER_ID_HDR in r.headers:
            user_ids = json.loads(r.headers[self.USER_ID_HDR])

        return r

更新_道具欄
import tutorialFunctions

DatastoresApi = tutorialFunctions.DataStores()

# 設定
datastoreName = "Inventory"

# 列出用戶子集的鍵(您可能需要使用下一個頁面來查看其他項目)
keys = DatastoresApi.list_entries(datastoreName)
print(keys.content)

# 閱讀每個用戶的道具欄
for x in range(5):
    updatedObjectKey = "User_"+str(x+1)
    value = DatastoresApi.get_entry(datastoreName, updatedObjectKey)
    # 將回應類型變更為字串
    updatedValue = value.json()
    print(updatedObjectKey + " has "+str(updatedValue)+" gems in their inventory")
# 更新每個用戶的貨幣10
for x in range(5):
    updatedObjectKey = "User_"+str(x+1)
    value = DatastoresApi.increment_entry(datastoreName, updatedObjectKey, 10)
    # 將回應類型變更為字串
    updatedValue = value.json()
    print(updatedObjectKey + " now has "+str(updatedValue)+" robux in their inventory")

要測試，設定 API_KEY 環境變量，並且執行 update_inventory 檔案：


export API_KEY=... \
python update_inventory

外部持續排行榜

這個部分通過 Python 中的具體範例來創建一個外部持續排名排行榜，在此中您可以列出和閱取您用戶的信息，並且對其進行編輯，然後發布到外部網站以獲得促銷。

為此範例，假設以追蹤中內容：

代碼示例為示範目的創建預設名稱清單。對於您自己的應用程式，您應該使用您體驗中的實際用戶清單。
代碼示例為每個加入體驗的用戶添加 50 點。對於您自己的應用程式，您應該根據體驗的設計定義規則。

從高等級開始，您可以通過添加 API 鑰匙權限和添加指令碼來建立您的 Python 應用程式。

為已命令資料儲存添加 API 鑰匙權限

此範例 app 需要四個方法來達到其功能： List Create 0> Update0> 1> 2> Increment2> ，因此您需要添加以下 API 鑰匙權限：

閱讀對於 list 方法。
寫下 for Create , Update , and 0> Increment0> 方法。

當建立 API 鑰匙為此示例時，請確認您執行以下操作：

從選擇 API 系統選單在存取權限區域中，選擇命令式數據存取。
將 API 操作的許可添加到目標體驗中，以便讀取並寫入指定的資料存儲。
1. 點擊選擇要新增的體驗下拉欄，然後選擇目標體驗。
2. 在體驗運作中，將下拉列表擴展以選擇閱取和寫入操作。
在安全部分中，使用CIDR 語法來設定 IP 存取鍵，並設定一個明示的過期日期，讓您的鑰匙在該日期後自動停止運作。對於此示例，如果您計劃進行本地測試，您可以移除IP限制，將它設置為0.0.0.

為排行榜增加指令碼

在建立範例應用程App的 API 鑰匙時，您需要添加 Python 指令碼來執行應用程序功能。

了解_數據_存儲庫。py

已命令_data_stores.py
import hashlib
import requests
import json

class DataStores:
    def __init__(self, config_file):
        with open(config_file) as f:
            self._config = json.load(f)

    def _H(self):
        return { 'x-api-key' : self._config["api_key"], 'Content-Type': 'application/json'}
    def _get_url(self, path_format: str):
        return f"{self._config['base_url']}/{path_format.format(self._config['universe_id'])}"

    def list(self, datastore, scope, pageSize = 10, orderBy = "", filter = "", exclusiveStartKey = ""):
        self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries"
        headers = { 'x-api-key' : self._config["api_key"] }
        r = requests.get(self._objects_url, headers=headers, params={"max_page_size": pageSize, "order_by" : orderBy, "filter" : filter, "page_token" : ""})
        return r

    def create(self, datastore, scope, entry, data):
        self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries"
        headers = self._H()
        payload = json.dumps({
            "value": 11
            })
        return requests.post(self._objects_url, params = {"id": entry }, data=payload, headers=headers)

    def increment(self, datastore, scope, entry, incrementBy):
        self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries/"+entry+":increment"
        headers = { 'x-api-key' : self._config["api_key"] }
        payload = json.dumps({
            "amount": 1
            })
        r = requests.post(self._objects_url, headers=headers, data=payload)
        return r

排行榜。py
import leaderboardEndpoints

# 在此輸入設定檔
datastores = leaderboardEndpoints.DataStores("config.json")

# 變數
orderedDataStore = "PlayerScores"
scope = "global"
entryNames = ["Ragdoll", "Balinese", "Tabby", "Siamese"]

# 建立一個新項目，並且每個新玩家獲得 50 分，以加入遊戲
for x in range(len(entryNames)):
    r = datastores.create(orderedDataStore, scope, entryNames[x], 50)

# 顯示玩家的分數
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)

# 增加玩家得分以獲勝遊戲
datastores.increment(orderedDataStore, scope, entryNames[0], 100)
# 增加所有玩家的分數以參加遊戲
for x in range(len(entryNames)):
    datastores.increment(orderedDataStore, scope, entryNames[x], 10)

# 顯示排行榜
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)

設定
{
  "universe_id": "",
  "api_key_url": "https://apis.roblox.com/datastores/點擊量/，
  "api_key": ""
}

要測試，設定 API_KEY 環境變量，並且執行 leaderboard 檔案：


export API_KEY=... \
python leaderboard

完成測試後，您可以將排行榜發布或埋入 Roblox 外的網站，以取得更多 reach。