Mã lỗi và giới hạn của kho dữ liệu

Các yêu cầu bạn gửi đến kho dữ liệu có thể thất bại do kết nối kém hoặc các vấn đề khác. Để xử lý lỗi và trả về thông điệp với mã lỗi, hãy bọc các hàm kho dữ liệu trong pcall().

Một cuộc gọi ghi thất bại, chẳng hạn như UpdateAsync(), có nghĩa là máy chủ trò chơi không nhận được phản hồi thành công. Điều này không đảm bảo rằng việc ghi ở phía backend không xảy ra. Trong một số kịch bản thất bại, trạng thái ghi cuối cùng có thể không được biết đến bởi người gọi cho đến khi nó được xác minh bằng một lần đọc tiếp theo mà không có bộ nhớ đệm.

Tham chiếu mã lỗi

Mã lỗi máy chủ

Giới hạn

Các mô hình dữ liệu có giới hạn. Nếu một trải nghiệm vượt quá những giới hạn này, dịch vụ sẽ tự động giới hạn việc sử dụng kho dữ liệu của trải nghiệm và khiến các yêu cầu trong tương lai được đặt vào một trong các hàng đợi sau:

• Đặt
• Đặt có thứ tự
• Lấy
• Lấy có thứ tự

Các yêu cầu trong một hàng đợi được xử lý theo thứ tự mà chúng được nhận. Hàm được gọi tiếp tục chờ miễn là yêu cầu của nó vẫn đang trong hàng đợi. Nếu chính khóa kho dữ liệu bị giới hạn, yêu cầu sẽ được đặt vào hàng đợi nhưng sẽ tạm thời bị bỏ qua.

Mỗi hàng đợi có giới hạn 30 yêu cầu. Khi giới hạn của một hàng đợi được đạt, các yêu cầu sẽ thất bại với mã lỗi trong khoảng 301-306, cho thấy rằng các yêu cầu đã bị từ chối hoàn toàn.

Giới hạn truy cập

Các kho dữ liệu phải tuân theo cả giới hạn trải nghiệm và giới hạn máy chủ. Các giới hạn cấp trải nghiệm tăng theo tổng số người dùng đồng thời trên toàn trải nghiệm, trong khi các giới hạn cấp máy chủ có thể cấu hình và được sử dụng như một công cụ bởi người tạo.

Giới hạn trải nghiệm

Mỗi trải nghiệm được phép một số lượng yêu cầu kho dữ liệu nhất định dựa trên loại kho dữ liệu, loại yêu cầu và số lượng người dùng đồng thời. Đối với mỗi loại kho dữ liệu và loại yêu cầu, giới hạn được chia sẻ giữa tất cả các hàm được liệt kê.

• UpdateAsync() tiêu thụ từ cả ngân sách yêu cầu đọc và ghi. Một cuộc gọi đơn lẻ sẽ giảm cả hai giới hạn.
• Máy chủ trò chơi và Open Cloud chia sẻ một ngân sách; lưu lượng Open Cloud có thể bị giới hạn bởi việc sử dụng trong trải nghiệm (và ngược lại). Xem Kiểm soát giới hạn tỷ lệ để biết thêm hướng dẫn.

Các kho dữ liệu tiêu chuẩn

Các kho dữ liệu có thứ tự

Kiểm soát giới hạn tỷ lệ

Vì các yêu cầu Open Cloud và máy chủ trò chơi được chia sẻ, nên điều quan trọng là kiểm soát độc lập mức tiêu thụ của mỗi loại.

Máy chủ trò chơi

Các máy chủ riêng lẻ có giới hạn tích hợp, như đã mô tả ở trên. Sử dụng sự kết hợp của SetRateLimitForRequestType() và GetRequestBudgetForRequestType() để duy trì kiểm soát chi tiết về sự đóng góp của từng máy chủ vào ngân sách tổng.

Open Cloud

Các yêu cầu Open Cloud yêu cầu một giải pháp giới hạn tỷ lệ bên ngoài. Chúng tôi khuyên bạn nên sử dụng một trong các phương pháp sau:

• (Đơn giản) Thêm một thời gian chờ ngắn sau mỗi yêu cầu, đặc biệt nếu gọi cùng một API trong một vòng lặp liên tục. Đặt thời gian chờ này bằng 60 / (mức tiêu thụ ngân sách mong muốn mỗi phút) giây, như một giới hạn trên. Lưu ý rằng phương pháp này không cho phép gửi yêu cầu theo từng đợt.
• (Chắc chắn) Triển khai một bộ giới hạn tỷ lệ cục bộ sử dụng chiến lược thùng rò rỉ.

Các mẫu mã Node.js sau đây bao gồm các triển khai tham khảo.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('Biến môi trường API_KEY chưa được thiết lập.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Cấu hình giới hạn tỷ lệ theo từng thao tác (yêu cầu mỗi phút) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Khoảng cách tối đa cho mỗi thao tác: 60 / (yêu cầu mỗi phút) giây.
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Thực hiện yêu cầu, sau đó chờ khoảng thời gian của thao tác này trước khi trả về.
async function throttledFetch(url, options, intervalMs) {
    const response = await fetch(url, options);
    await sleep(intervalMs);
    return response;
}

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

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

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // Nội dung phải là một chuỗi
    }, UPDATE_INTERVAL_MS);
    return response;
}

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

        for (const entry of entries.dataStoreEntries) {
            const path = entry.path;
            console.log(`\nĐang xử lý mục: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Trạng thái: ${updateResponse.status}`);
            console.log(`Phản hồi: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Đã xảy ra lỗi trong quá trình thực hiện:', error);
    }
})();

Giới hạn máy chủ

Mỗi máy chủ có một giới hạn tỷ lệ có thể cấu hình cho mỗi loại yêu cầu, dựa trên số lượng người chơi trong máy chủ đó. Các máy chủ nhận được một đợt khởi động một lần với ngân sách yêu cầu bổ sung khi chúng được tạo lần đầu. Sử dụng GetRequestBudgetForRequestType() để xác nhận số lượng yêu cầu kho dữ liệu mà máy chủ hiện tại có thể thực hiện tại bất kỳ thời điểm nào.

Các giới hạn này có thể cấu hình bởi người tạo bằng cách sử dụng API SetRateLimitForRequestType(). Sử dụng API này, một người tạo có thể cấu hình giới hạn tỷ lệ kho dữ liệu của riêng họ cho mỗi loại yêu cầu.

Các giới hạn tỷ lệ mặc định sau đây áp dụng nếu API không được gọi:

Các kho dữ liệu tiêu chuẩn

Các kho dữ liệu có thứ tự

Giới hạn dữ liệu

Các kho dữ liệu giới hạn lượng dữ liệu có thể được sử dụng cho mỗi mục.

Tên kho dữ liệu, tên khóa và phạm vi phải đều dưới một độ dài ký tự nhất định. Sử dụng string.len() để kiểm tra độ dài của chúng.

Dữ liệu (giá trị khóa) cũng được lưu trữ dưới dạng chuỗi, bất kể kiểu ban đầu của nó. Bạn có thể kiểm tra kích thước của dữ liệu bằng cách sử dụng hàm JSONEncode(), hàm này chuyển đổi dữ liệu Luau thành một bảng JSON đã tuần tự hóa.

Giới hạn siêu dữ liệu

Giới hạn số ký tự trong siêu dữ liệu do người dùng định nghĩa.

Giới hạn thông lượng

Giới hạn thông lượng theo khóa đảm bảo rằng hiệu suất là tối ưu trên các máy chủ Roblox. Mỗi giới hạn áp dụng cho từng khóa duy nhất trên tất cả các máy chủ trong một trải nghiệm và được làm mới theo thời gian.

Roblox xem xét việc sử dụng hạn ngạch liên quan đến khóa trong 60 giây qua. Nếu việc sử dụng, bao gồm cả yêu cầu hiện tại, nằm trong giới hạn thông lượng, yêu cầu sẽ được chấp thuận. Nếu việc sử dụng vượt quá giới hạn, yêu cầu sẽ bị từ chối.

Ngoài các giới hạn thông lượng trên, Roblox tổ chức dữ liệu thành các phân vùng dựa trên một sơ đồ nội bộ. Do đó, khi máy chủ backend nhận được một khối lượng yêu cầu cao đến cùng một kho dữ liệu, điều này có thể dẫn đến việc giới hạn thêm. Bất kể nguyên nhân, việc giới hạn sẽ xuất hiện dưới dạng lỗi DatastoreThrottled hoặc KeyThrottled, tùy thuộc vào việc giới hạn thông lượng đã bị vượt quá cho một kho dữ liệu duy nhất hay một khóa. Các thông điệp lỗi này áp dụng cho cả kho dữ liệu có thứ tự và tiêu chuẩn.

Giới hạn lưu trữ

Để giữ cho lưu trữ ổn định và có thể mở rộng, các kho dữ liệu sử dụng một giới hạn cấp trò chơi cho việc sử dụng lưu trữ của bạn.

Giới hạn này bao gồm một phân bổ cơ bản cho mỗi trò chơi cộng với một phân bổ bổ sung dựa trên số lượng người dùng trọn đời. Một người dùng trọn đời là bất kỳ người dùng nào đã tham gia trò chơi của bạn ít nhất một lần.

Giới hạn lưu trữ được tính bằng công thức sau Giới hạn lưu trữ phiên bản mới nhất tổng = 500 MB + 1 MB × số lượng người dùng trọn đời.

Việc sử dụng lưu trữ được đo bằng kích thước nén của phiên bản mới nhất của mỗi khóa. Các kho dữ liệu tự động nén dữ liệu của bạn trước khi lưu trữ, vì vậy hãy tránh việc nén trước. Việc nén trước sẽ thêm tải CPU không cần thiết và có thể làm giảm hiệu quả của việc nén tích hợp của các kho dữ liệu. Bằng cách lưu trữ dữ liệu không nén, bạn tự động hưởng lợi từ những cải tiến trong các thuật toán nén của Roblox và các tối ưu hóa dựa trên sơ đồ trong tương lai.

Chỉ phiên bản mới nhất của mỗi khóa được tính vào việc sử dụng lưu trữ của bạn. Các khóa đã bị xóa và các phiên bản đã thay thế, trong khi vẫn có thể truy cập thông qua các API phiên bản trong thời gian giữ của chúng, không được tính vào việc sử dụng lưu trữ của bạn. Tuy nhiên, các kho dữ liệu bị xóa thông qua phương thức Open Cloud DeleteDataStore vẫn tiếp tục được tính vào việc sử dụng lưu trữ trong thời gian xử lý xóa 30 ngày của chúng, cho đến khi chúng được xóa vĩnh viễn.