Kode error dan batas 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 error, 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, kondisi penulisan terakhir mungkin tidak diketahui oleh pemanggil sampai diverifikasi dengan pembacaan tindak lanjut tanpa cache.

Referensi kode kesalahan

Kode kesalahan server

Batas

Model data memiliki batas. Jika sebuah pengalaman melebihi batas ini, layanan secara otomatis membatasi penggunaan penyimpanan data pengalaman tersebut dan menyebabkan permintaan selanjutnya dimasukkan dalam salah satu antrean berikut:

• Set
• Set terurut
• Ambil
• Ambil terurut

Permintaan dalam antrean diproses dalam urutan mereka diterima. Fungsi yang dipanggil terus memblokir selama permintaannya masih dalam antrean. Jika kunci penyimpanan data itu sendiri dibatasi, permintaan ditempatkan dalam antrean tetapi sementara diabaikan.

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

Batas akses

Penyimpanan data tunduk pada baik batas tingkat pengalaman dan server. Batas tingkat pengalaman meningkat seiring dengan jumlah pengguna yang bersamaan di seluruh pengalaman, sementara batas tingkat server dapat dikonfigurasi dan dimaksudkan untuk digunakan sebagai alat oleh pencipta.

Batas Pengalaman

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

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

Penyimpanan data standar

Penyimpanan data terurut

Kontrol batas laju

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

Server game

Server individu memiliki batas internal, seperti yang dijelaskan di atas. Gunakan kombinasi SetRateLimitForRequestType() dan GetRequestBudgetForRequestType() untuk menjaga kontrol yang lebih tepat atas kontribusi server individu terhadap anggaran total.

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 terus menerus. Atur waktu tunggu ini sama dengan 60 / (penggunaan anggaran yang diinginkan per menit) detik, sebagai batas atas. Perhatikan bahwa pendekatan ini tidak memungkinkan permintaan untuk dikirim dalam lonjakan.
• (Kuat) Implementasikan pembatas laju lokal menggunakan strategi ember bocor.

Kode contoh Node.js berikut mencakup implementasi referensi.

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

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;

// Spacing 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, lalu menunggu interval operasi ini sendiri sebelum mengembalikan.
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 berisi 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);
    }
})();

Batas server

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

Batas ini dapat dikonfigurasi oleh pencipta menggunakan API SetRateLimitForRequestType(). Menggunakan API ini, seorang pencipta dapat mengonfigurasi batas tarif penyimpanannya sendiri untuk setiap jenis permintaan.

Batas laju default berikut diterapkan jika API tidak dipanggil:

Penyimpanan data standar

Penyimpanan data terurut

Batas data

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

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

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

Batas metadata

Batas untuk jumlah karakter dalam metadata yang ditentukan pengguna.

Batas throughput

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

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

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

Batas penyimpanan

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

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

Batas 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 sebelumnya. Prabanding menambah overhead CPU yang tidak perlu dan dapat mengurangi efektivitas kompresi yang terbangun di dalam penyimpanan data. Dengan menyimpan data yang tidak terkompresi, Anda secara otomatis mendapatkan manfaat dari peningkatan 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.