Kode kesalahan dan batasan penyimpanan data

Permintaan yang Anda buat ke penyimpanan data dapat gagal karena konektivitas yang buruk atau masalah lainnya. Untuk menangani kesalahan dan mengembalikan pesan dengan kode kesalahan, bungkus fungsi penyimpanan data dalam pcall().

Panggilan tulis yang gagal, seperti UpdateAsync(), berarti server game tidak menerima respons yang berhasil. Ini tidak selalu menjamin bahwa penulisan backend tidak terjadi. Dalam beberapa skenario kegagalan, status penulisan akhir mungkin tidak diketahui oleh pemanggil sampai diverifikasi dengan pembacaan lanjutan tanpa cache.

Referensi kode kesalahan

Kode kesalahan server

Batasan

Model data memiliki batasan. Jika sebuah pengalaman melebihi batasan ini, layanan secara otomatis membatasi penggunaan penyimpanan data pengalaman tersebut dan menyebabkan permintaan di masa depan ditempatkan dalam salah satu antrean berikut:

• Set
• Set terurut
• Ambil
• Ambil terurut

Permintaan dalam antrean ditangani sesuai urutan penerimaannya. Fungsi yang dipanggil terus menunggu selama permintaannya masih dalam antrean. Jika kunci penyimpanan data itu sendiri dibatasi, permintaan ditempatkan dalam antrean tetapi sementara dilewati.

Setiap antrean memiliki batas 30 permintaan. Ketika batas antrean tercapai, permintaan gagal dengan kode kesalahan dalam rentang 301-306, menunjukkan bahwa permintaan telah dibatalkan sepenuhnya.

Batasan akses

Penyimpanan data tunduk pada batasan tingkat pengalaman dan server. Batasan tingkat pengalaman skala dengan total pengguna bersamaan di seluruh pengalaman, sementara batasan tingkat server dapat dikonfigurasi dan dimaksudkan untuk digunakan sebagai alat oleh pencipta.

Batasan Pengalaman

Setiap pengalaman diizinkan sejumlah permintaan penyimpanan data tertentu berdasarkan jenis penyimpanan data, jenis permintaan, dan jumlah pengguna bersamaan. Untuk setiap jenis penyimpanan data dan jenis permintaan, batasan dibagi di antara semua fungsi yang terdaftar.

• UpdateAsync() mengkonsumsi dari anggaran permintaan baca dan tulis. Satu panggilan akan mengurangi kedua batasan.
• Server game dan Open Cloud berbagi anggaran; lalu lintas Open Cloud dapat dibatasi oleh penggunaan dalam pengalaman (dan sebaliknya). Lihat Kontrol batasan laju untuk panduan lebih lanjut.

Penyimpanan data standar

Penyimpanan data terurut

Kontrol batasan laju

Karena permintaan Open Cloud dan server game dibagikan, penting untuk mengontrol secara independen seberapa banyak masing-masing dapat mengkonsumsi dari anggaran.

Server game

Server individu memiliki batasan bawaan, seperti yang dijelaskan di atas. Gunakan kombinasi SetRateLimitForRequestType() dan GetRequestBudgetForRequestType() untuk mempertahankan kontrol yang lebih halus atas kontribusi server individu terhadap total anggaran.

Open Cloud

Permintaan Open Cloud memerlukan solusi pembatasan laju eksternal. Kami merekomendasikan salah satu pendekatan berikut:

• (Sederhana) Tambahkan waktu tunggu singkat setelah setiap permintaan, terutama jika memanggil API yang sama dalam loop berkelanjutan. Atur waktu tunggu ini sama dengan 60 / (konsumsi anggaran yang diinginkan per menit) detik, sebagai batas atas. Perhatikan bahwa pendekatan ini tidak memungkinkan permintaan dikirim dalam lonjakan.
• (Kuat) Implementasikan pembatas laju lokal menggunakan strategi ember bocor.

Contoh kode Node.js berikut mencakup implementasi referensi.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('Variabel lingkungan API_KEY tidak disetel.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Konfigurasi pembatasan laju per operasi (permintaan per menit) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Spasi batas atas per operasi: 60 / (permintaan per menit) detik.
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));

// Melakukan permintaan, kemudian menunggu interval operasi ini sendiri sebelum kembali.
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) // Badan harus berupa string
    }, 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(`\nMemproses entri: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Status: ${updateResponse.status}`);
            console.log(`Respons: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Terjadi kesalahan selama eksekusi:', error);
    }
})();

Batasan server

Setiap server memiliki batasan laju yang dapat dikonfigurasi untuk setiap jenis permintaan, berdasarkan jumlah pemain di server tersebut. Server menerima lonjakan anggaran permintaan tambahan satu kali saat pertama kali dibuat. Gunakan GetRequestBudgetForRequestType() untuk mengonfirmasi jumlah permintaan penyimpanan data yang dapat dilakukan server saat ini pada waktu tertentu.

Batasan ini dapat dikonfigurasi oleh pencipta menggunakan API SetRateLimitForRequestType(). Menggunakan API ini, seorang pencipta dapat mengonfigurasi batasan laju penyimpanan data mereka sendiri untuk setiap jenis permintaan.

Batasan default berikut berlaku jika API tidak dipanggil:

Penyimpanan data standar

Penyimpanan data terurut

Batasan data

Penyimpanan data membatasi seberapa banyak data yang dapat digunakan per entri.

Nama penyimpanan data, nama kunci, dan ruang lingkup semuanya harus berada di bawah panjang karakter tertentu. Gunakan string.len() untuk memeriksa panjangnya.

Data (nilai kunci) juga disimpan sebagai string, terlepas dari tipe awalnya. Anda dapat memeriksa ukuran data dengan fungsi JSONEncode(), yang mengonversi data Luau menjadi tabel JSON yang diserialisasi.

Batasan metadata

Batasan jumlah karakter dalam metadata yang ditentukan pengguna.

Batasan throughput

Batasan throughput per kunci memastikan bahwa kinerja optimal di server Roblox. Setiap batasan berlaku untuk setiap kunci tunggal di semua server dalam sebuah pengalaman dan menyegarkan seiring waktu.

Roblox memeriksa penggunaan kuota yang terkait dengan kunci selama 60 detik terakhir. Jika penggunaan, termasuk permintaan saat ini, berada dalam batas throughput, permintaan disetujui. Jika penggunaan melebihi batas, permintaan ditolak.

Selain batasan throughput di atas, Roblox mengorganisir data ke dalam partisi berdasarkan skema internal. Akibatnya, ketika server backend menerima volume permintaan yang tinggi untuk penyimpanan data yang sama, ini dapat mengakibatkan pembatasan lebih lanjut. Terlepas dari penyebabnya, pembatasan muncul sebagai kesalahan DatastoreThrottled atau KeyThrottled, tergantung pada apakah batas throughput terlampaui untuk satu penyimpanan data atau kunci. Pesan kesalahan ini berlaku untuk penyimpanan data terurut dan standar.

Batasan penyimpanan

Untuk menjaga penyimpanan tetap stabil dan dapat diskalakan, penyimpanan data menggunakan batasan tingkat permainan pada penggunaan penyimpanan Anda.

Batasan ini terdiri dari alokasi dasar untuk setiap permainan ditambah alokasi tambahan berdasarkan jumlah pengguna seumur hidup. Pengguna seumur hidup adalah pengguna yang telah bergabung dengan permainan Anda setidaknya sekali.

Batasan penyimpanan dihitung menggunakan rumus berikut Total batas penyimpanan versi terbaru = 500 MB + 1 MB × jumlah pengguna seumur hidup.

Penggunaan penyimpanan diukur menggunakan ukuran terkompresi dari versi terbaru setiap kunci. Penyimpanan data secara otomatis mengompres data Anda sebelum penyimpanan, jadi hindari mengompresnya sendiri. Pra-kompresi menambah overhead CPU yang tidak perlu dan dapat mengurangi efektivitas kompresi bawaan penyimpanan data. Dengan menyimpan data yang tidak terkompresi, Anda secara otomatis mendapatkan manfaat dari perbaikan algoritma kompresi Roblox dan optimasi berbasis skema di masa depan.

Hanya versi terbaru dari setiap kunci yang dihitung terhadap penggunaan penyimpanan Anda. Kunci yang dihapus dan versi yang digantikan, meskipun masih dapat diakses melalui API versi selama periode retensi mereka, tidak dihitung terhadap penggunaan penyimpanan Anda. Namun, penyimpanan data yang dihapus melalui metode Open Cloud DeleteDataStore terus dihitung terhadap penggunaan penyimpanan selama periode pemrosesan penghapusan 30 hari mereka, sampai mereka dihapus secara permanen.