開放雲端資料儲存 | 文件 - Roblox 創作者中心

除了從Studio或實時遊戲的引擎API（DataStoreService）存取資料儲存外，您還可以使用開放雲端API從外部腳本和其他工具存取標準和有序資料儲存。

開放雲端對您的資料儲存的存取解鎖了許多潛在的使用案例，包括：

支援客戶服務的入口網站，讓您的團隊能直接處理支援請求，例如修改用戶的物品清單或發放退款
可以在外部網站上顯示的全球排行榜
使用腳本更新架構，這些腳本從當前資料儲存讀取條目，映射到新架構，然後將條目寫回新的資料儲存

本頁的範例展示如何使用Node.js和Python構建用戶物品清單支援入口網站和外部排行榜，但您可以使用自己喜歡的任何語言；開放雲端API支援任何可以發送HTTP請求的程式語言。

與引擎API的不同之處

儘管開放雲端API訪問相同的基礎資料儲存並且在使用上與DataStoreService相似，但仍然存在一些關鍵差異：

宇宙ID：與引擎API不同，開放雲端API是無狀態的，可以來自任何地方，因此您必須始終提供宇宙ID，即您的遊戲的唯一標識符。
創建和更新的權限分開：如果條目不存在，則引擎API會在調用DataStore:SetAsync()時創建新的條目，但開放雲端用於創建和更新條目的方法是分開的。在某些情況下，單獨的權限可能更安全和靈活。例如，您可能希望您的客戶服務工具只能編輯現有用戶的資料，而不能創建新的資料。
資料序列化：所有開放雲端端點都要求您在發送之前序列化數據。序列化是將對象轉換為字符串。反序列化則相反，是將字符串轉換為對象。引擎API自動序列化和反序列化條目內容，但對於開放雲端，您必須自己生成或解析您的條目至JSON格式。

權限

資料儲存通常儲存敏感資訊，例如用戶檔案和虛擬貨幣。為了保持安全性，每個開放雲端方法都具有對應的權限，稱為範疇，您必須將其添加到您的API密鑰中，例如universe-datastores.control:list範疇，用於列出資料儲存方法。如果您未添加所需的權限，則API呼叫將返回錯誤。請參閱參考文檔以獲取每個端點所需的範疇。

有關管理權限的更多信息，請參閱管理API密鑰。

用戶物品清單支援入口網站

此範例使用名為Inventory的資料儲存和每個條目的結構為"userId": {"currency": number, "weapon": string, "level": number}。鍵是userId。

所需範疇

在創建API密鑰時，為此範例添加以下範疇到您的密鑰：

universe-datastores.objects:list
universe-datastores.objects:read
universe-datastores.objects:update

您可以選擇性地為僅Inventory資料儲存添加權限，設置IP地址限制，並設置到期日期。

為用戶物品清單支援入口網站添加腳本

在創建具有範例應用所需權限的API密鑰後，您可以創建一個腳本來向端點發送請求。這些腳本獲取資料儲存中的前10個條目，將每個條目的currency值增加10，然後更新每個條目。對於較大的資料儲存，您需要處理分頁，使用maxPageSize和pageToken查詢參數。

incrementCurrency.js
const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('API_KEY環境變量未設置。');
}

const apiHeaderKey = 'x-api-key';

const universeId = '';
const dataStoreId = 'Inventory';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

async function listEntries(universe, dataStore) {
    const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
    const url = baseUrl + listPath;
    const response = await fetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    });
    return response.json();
}

async function getEntry(path) {
    const url = baseUrl + path;
    const response = await fetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    });
    return response.json();
}

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await fetch(url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // 必須是字符串
    });
    return response;
}

(async () => {
    try {
        const entries = await listEntries(universeId, dataStoreId);

        for (const entry of entries.dataStoreEntries) {
            const path = entry.path;
            console.log(`\n正在處理條目: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`狀態: ${updateResponse.status}`);
            console.log(`回應: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('執行期間發生錯誤:', error);
    }
})();

要測試，設置API_KEY環境變量，安裝依賴，然後運行腳本：


export API_KEY=<your_key>
node incrementCurrency.js

外部持久排行榜

此範例為演示目的創建了一個預定義的用戶列表，但要在實際遊戲中有用，您需要一個實際的用戶資料儲存。

所需範疇

在創建API密鑰時，為此範例添加以下範疇到您的密鑰：

universe.ordered-data-store.scope.entry:read
universe.ordered-data-store.scope.entry:write

為排行榜添加腳本

在創建具有範例應用所需權限的API密鑰後，您可以創建一個腳本來向端點發送請求。這些腳本將一些隨機數字作為樣本條目添加到有序資料儲存中，然後按值從高到低檢索它們。對於較大的資料儲存，您需要處理分頁，使用maxPageSize和pageToken查詢參數。

leaderboard.js
const apiKey = process.env.API_KEY;
const apiHeaderKey = 'x-api-key';

const universeId = '';
const orderedDataStoreId = 'PlayerScores';
const scopeId = 'global';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

async function createOrderedEntry(universe, orderedDataStore, entryId, payload) {
  const createPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;

  const url = new URL(baseUrl + createPath);
  url.searchParams.append('id', entryId);

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      [apiHeaderKey]: apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`API 錯誤 (${response.status}): ${errorText}`);
  }

  return response.text();
}

async function listOrderedEntries(universe, orderedDataStore) {
  const listPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;

  const url = new URL(baseUrl + listPath);
  url.searchParams.append('orderBy', 'value desc');

  return fetch(url, {
    headers: {
      [apiHeaderKey]: apiKey,
    },
  });
}

async function main() {
  if (!apiKey) {
    console.error('錯誤: API_KEY環境變量未設置。');
    process.exit(1);
  }

  const entryNames = ['Ragdoll', 'Balinese', 'Tabby', 'Siamese'];

  console.log('正在創建樣本數據...');
  for (const name of entryNames) {
    try {
      const randomValue = Math.floor(Math.random() * 50) + 1;
      const payload = { value: randomValue };
      const responseText = await createOrderedEntry(universeId, orderedDataStoreId, name, payload);
      console.log(responseText);
    } catch (error) {
      console.error(`創建條目 "${name}" 失敗: ${error.message}`);
    }
  }

  console.log('\n獲取已排序條目列表...');
  try {
    const playerScoresResponse = await listOrderedEntries(universeId, orderedDataStoreId);

    console.log(playerScoresResponse.status);
    const responseText = await playerScoresResponse.text();
    console.log(responseText);
  } catch (error) {
    console.error(`列出條目失敗: ${error.message}`);
  }
}

main();

要測試，設置API_KEY環境變量，安裝依賴，並運行腳本：


export API_KEY=<your_key>
node leaderboard.js