Veri deposu hata kodları ve limitleri

Veri depolarına yaptığınız istekler, kötü bağlantı veya diğer sorunlar nedeniyle başarısız olabilir. Hataları yönetmek ve bir hata kodu ile birlikte mesaj döndürmek için veri deposu işlevlerini pcall() içine sarın.

UpdateAsync() gibi başarısız bir yazma çağrısı, oyun sunucusunun başarılı bir yanıt almadığı anlamına gelir. Bu, arka uç yazımının gerçekleşmediğini garanti etmez. Bazı hata senaryolarında, son yazım durumu, önbelleksiz bir takip okuması ile doğrulanana kadar çağrıcıya bilinmeyebilir.

Hata kodu referansı

Sunucu hata kodları

Limitler

Veri modellerinin limitleri vardır. Bir deneyim bu limitleri aşarsa, hizmet otomatik olarak deneyimin veri deposu kullanımını sınırlayarak gelecekteki isteklerin aşağıdaki kuyruklardan birine yerleştirilmesine neden olur:

• Ayarla
• Sıralı ayarla
• Al
• Sıralı al

Bir kuyruktaki istekler, alındıkları sıraya göre işlenir. Çağrılan işlev, isteği hala kuyrukta olduğu sürece beklemeye devam eder. Eğer veri deposu anahtarı kendisi sınırlıysa, istek bir kuyruğa yerleştirilir ama geçici olarak atlanır.

Her kuyruğun 30 isteklik bir limiti vardır. Bir kuyruğun limiti aşıldığında, istekler 301-306 aralığında bir hata kodu ile başarısız olur ve isteklerin tamamen bırakıldığını gösterir.

Erişim limitleri

Veri depoları, hem deneyim hem de sunucu düzeyi limitlerine tabidir. Deneyim düzeyi limitleri, deneyim boyunca toplam eşzamanlı kullanıcı sayısına göre ölçeklenirken, sunucu düzeyi limitleri yapılandırılabilir ve yaratıcı tarafından bir araç olarak kullanılmak üzere tasarlanmıştır.

Deneyim Limitleri

Her deneyim, veri deposu türüne, istek türüne ve eşzamanlı kullanıcı sayısına bağlı olarak belirli sayıda veri deposu isteğine izin verilir. Her veri deposu türü ve istek türü için limit, listelenen tüm işlevler arasında paylaşılır.

• UpdateAsync() hem okuma hem de yazma istek bütçesinden tüketir. Tek bir çağrı her iki limiti de azaltır.
• Oyun sunucusu ve Açık Bulut bütçeyi paylaşır; Açık Bulut trafiği, deneyim içindeki kullanıma göre sınırlanabilir (ve tersine). Daha fazla rehberlik için Oran limitlerini kontrol et bölümüne bakın.

Standart veri depoları

Sıralı veri depoları

Oran limitlerini kontrol et

Açık Bulut ve oyun sunucusu istekleri paylaşıldığı için, her birinin bütçeden ne kadar tüketebileceğini bağımsız olarak kontrol etmek önemlidir.

Oyun sunucusu

Bireysel sunucular, yukarıda açıklandığı gibi yerleşik limitlere sahiptir. Bireysel sunucuların toplam bütçeye katkısını ince ayar yapmak için SetRateLimitForRequestType() ve GetRequestBudgetForRequestType() kombinasyonunu kullanın.

Açık Bulut

Açık Bulut istekleri, harici bir oran sınırlama çözümü gerektirir. Aşağıdaki yaklaşımlardan birini öneriyoruz:

• (Basit) Her isteğin ardından kısa bir zaman aşımı ekleyin, özellikle aynı API'yi sürekli bir döngüde çağırıyorsanız. Bu zaman aşımını 60 / (istenen bütçe tüketimi dakikada) saniye olarak ayarlayın, üst sınır olarak. Bu yaklaşım, isteklerin patlama halinde gönderilmesine izin vermez.
• (Sağlam) Sızıntı kovası stratejisini kullanarak yerel bir oran sınırlayıcı uygulayın.

Aşağıdaki Node.js kod örnekleri referans uygulamaları içermektedir.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('API_KEY ortam değişkeni ayarlanmamış.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- İşlem başına oran sınırlama yapılandırması (dakikada istek) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Her işlem için üst sınır aralığı: 60 / (dakikada istek) saniye.
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));

// İsteği gerçekleştirir, ardından bu işlemin kendi aralığı kadar bekler.
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) // Gövde bir dize olmalıdır
    }, 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İşlem yapılıyor: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Durum: ${updateResponse.status}`);
            console.log(`Yanıt: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Yürütme sırasında bir hata oluştu:', error);
    }
})();

Sunucu limitleri

Her sunucunun, o sunucudaki oyuncu sayısına bağlı olarak her istek türü için yapılandırılabilir bir oran limiti vardır. Sunucular, ilk oluşturulduklarında bir kerelik ek istek bütçesi alırlar. Mevcut sunucunun herhangi bir zamanda yapabileceği veri deposu isteklerinin sayısını doğrulamak için GetRequestBudgetForRequestType() kullanın.

Bu limitler, yaratıcı tarafından yapılandırılabilir ve SetRateLimitForRequestType() API'si kullanılarak ayarlanabilir. Bu API'yi kullanarak, bir yaratıcı her istek türü için kendi veri deposu oran limitlerini yapılandırabilir.

Aşağıdaki varsayılan oran limitleri, API çağrılmadığında geçerlidir:

Standart veri depoları

Sıralı veri depoları

Veri limitleri

Veri depoları, her giriş başına ne kadar veri kullanılabileceğini sınırlar.

Veri deposu adı, anahtar adı ve kapsam belirli bir karakter uzunluğunun altında olmalıdır. Uzunluklarını kontrol etmek için string.len() kullanın.

Veri (anahtar değeri) başlangıç türünden bağımsız olarak bir dize olarak saklanır. Verinin boyutunu, Luau verisini serileştirilmiş bir JSON tablosuna dönüştüren JSONEncode() işlevi ile kontrol edebilirsiniz.

Meta veri limitleri

Kullanıcı tanımlı meta verilerdeki karakter sayısına sınırlamalar.

Verimlilik limitleri

Anahtar başına verimlilik limitleri, Roblox sunucularında performansın optimal olmasını sağlar. Her limit, bir deneyimdeki tüm sunuculardaki her bir anahtara uygulanır ve zamanla yenilenir.

Roblox, anahtara bağlı olan kotaların son 60 saniyedeki kullanımını inceler. Kullanım, mevcut isteği de içerecek şekilde verimlilik limitinin içindeyse, istek onaylanır. Kullanım limitin üzerinde ise, istek reddedilir.

Yukarıdaki verimlilik limitlerine ek olarak, Roblox verileri dahili bir şemaya dayalı olarak parçalara ayırır. Sonuç olarak, arka uç sunucusu aynı veri deposuna yüksek hacimli istekler aldığında, daha fazla sınırlama ile sonuçlanabilir. Neden ne olursa olsun, sınırlama ya DatastoreThrottled ya da KeyThrottled hataları olarak kendini gösterir; bu, verimlilik limitinin bir veri deposu veya bir anahtar için aşılıp aşılmadığına bağlıdır. Bu hata mesajları, hem sıralı hem de standart veri depoları için geçerlidir.

Depolama limitleri

Depolama kullanımını stabil ve ölçeklenebilir tutmak için, veri depoları depolama kullanımınıza bir oyun düzeyi limiti uygular.

Bu limit, her oyun için bir temel tahsisat ve ek olarak yaşam boyu kullanıcı sayısına dayalı bir ek tahsisat içerir. Bir yaşam boyu kullanıcı, oyununuza en az bir kez katılan herhangi bir kullanıcıdır.

Depolama limiti, aşağıdaki formül kullanılarak hesaplanır: Toplam en son sürüm depolama limiti = 500 MB + 1 MB × yaşam boyu kullanıcı sayısı.

Depolama kullanımı, her anahtarın en son sürümünün sıkıştırılmış boyutu kullanılarak ölçülür. Veri depoları, verilerinizi depolamadan önce otomatik olarak sıkıştırır, bu nedenle kendiniz önceden sıkıştırmaktan kaçının. Ön sıkıştırma, gereksiz CPU yükü ekler ve veri depolarının yerleşik sıkıştırmasının etkinliğini azaltabilir. Sıkıştırılmamış verileri saklayarak, Roblox'un sıkıştırma algoritmalarındaki iyileştirmelerden ve gelecekteki şemaya dayalı optimizasyonlardan otomatik olarak faydalanırsınız.

Her anahtarın yalnızca en son sürümü depolama kullanımınıza sayılır. Silinmiş anahtarlar ve geçersiz sürümler, saklama süresi boyunca sürüm API'leri aracılığıyla hala erişilebilir olsa da, depolama kullanımınıza sayılmaz. Ancak, Açık Bulut üzerinden silinen veri depoları DeleteDataStore yöntemi, kalıcı olarak kaldırılana kadar 30 günlük silme işleme süresi boyunca depolama kullanımınıza sayılmaya devam eder.