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ı ele almak ve hata kodu ile birlikte mesajlar döndürmek için veri deposu işlevlerini pcall() içine sarın.

UpdateAsync() gibi bir yazma çağrısının başarısız olması, oyun sunucusunun başarılı bir yanıt almadığını gösterir. Ancak bu, arka uç yazımının gerçekleşmediğini garanti etmez. Bazı başarısızlık senaryolarında, nihai yazım durumu, takip eden bir okuma ile doğrulanana kadar arayan kişi için bilinmez olabilir.

Hata kodu referansı

Sunucu hata kodları

Sınırlamalar

Veri modellerinin sınırlamaları vardır. Eğer bir deneyim bu sınırlamaları aşarsa, hizmet otomatik olarak deneyimin veri deposu kullanımını sınırlandırır ve gelecek 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ırada işlenir. Çağrılan işlev, isteği hâlâ sırada kaldığı sürece beklemeye devam eder. Eğer veri deposu anahtarı kendisi sınırlıysa, istek bir kuyruğa yerleştirilir ancak 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 reddedildiğini gösterir.

Erişim limitleri

Veri depoları hem deneyim hem de sunucu seviyesinde sınırlamalara tabidir. Deneyim düzeyi sınırlamaları, tüm eşzamanlı kullanıcı sayısına göre ölçeklenirken, sunucu düzeyi sınırlamaları yapılandırılabilir ve içerik üreticisi tarafından bir araç olarak kullanılmak amacıyla oluşturulmuştur.

Deneyim Sınırlamaları

Her deneyim, veri deposu türüne, istek türüne ve eşzamanlı kullanıcı sayısına dayanarak 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çelerinden tüketir. Tek bir çağrı her iki limiti de azaltır.
• Oyun sunucusu ve Açık Bulut paylaşır bir bütçe; Açık Bulut trafiği, deneyim içi kullanım tarafından sınırlandırılabilir (ve tersi). Daha fazla bilgi için Kontrol oran limitleri kısmına bakın.

Standart veri depoları

Sıralı veri depoları

Kontrol oran limitleri

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

Oyun sunucusu

Bireysel sunucuların yukarıda açıklandığı gibi yerleşik limitleri vardır. SetRateLimitForRequestType() ve GetRequestBudgetForRequestType() kombinasyonunu kullanarak bireysel sunucuların toplam bütçeye katkılarını ayrıntılı bir şekilde kontrol edebilirsiniz.

Açık Bulut

Açık Bulut istekleri için harici bir oran sınırlama çözümü gerekir. Aşağıdaki yöntemlerden birini öneririz:

• (Basit) Her isteğin ardından kısa bir zaman aşımı ekleyin, özellikle de aynı API'yi sürekli bir döngüde çağırıyorsanız. Bu zaman aşımını 60 / (istek başına istenen bütçe tüketimi) saniye olarak ayarlayın ve üst sınır olarak belirleyin. Bu yaklaşım, isteklerin patlama halinde gönderilmesine izin vermez.
• (Sağlam) Sızıntılı bucket stratejisi 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: 60 / (istek sayısı/dakika) 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 dönüş yapmadan önce bu işlemin kendi aralığını 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İşleme alını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 dayanan her istek türü için yapılandırılabilir bir oran sınırı vardır. Sunucular ilk kez oluşturulduğunda, ek bir istek bütçesi için bir kezlik başlangıç patlaması alırlar. GetRequestBudgetForRequestType() kullanarak, mevcut sunucunun her zaman ne kadar veri deposu isteği yapabileceğini doğrulayabilirsiniz.

Bu limitler, içerik üreticisi tarafından yapılandırılabilir olup, SetRateLimitForRequestType() API'si aracılığıyla kullanılmaktadır. Bu API'yi kullanarak, bir içerik üreticisi 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ığı takdirde geçerlidir:

Standart veri depoları

Sıralı veri depoları

Veri limitleri

Veri depoları, her giriş başına ne kadar veri kullanılacağını sınırlamaktadır.

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

Veri (anahtar değeri) aynı zamanda başlangıçta ne olursa olsun bir dize olarak saklanır. Verinin boyutunu, Luau verilerini seri hale getirilmiş bir JSON tablosuna dönüştüren JSONEncode() fonksiyonu ile kontrol edebilirsiniz.

Meta veri limitleri

Kullanıcı tanımlı meta verilerdeki karakter sayısı kısıtlamaları.

Üretim limitleri

Anahtar başına üretim limitleri, Roblox sunucularında performansın optimum olmasını sağlar. Her limit, belirli bir deneyim süresince tüm sunuculardaki her bir anahtara uygulanır ve zamanla yenilenir.

Roblox, son 60 saniye boyunca anahtarla ilişkili kota kullanımını inceler. Eğer kullanım, mevcut isteği de içerecek şekilde, üretim limiti içinde ise, istek onaylanır. Eğer kullanım limiti aşarsa, istek reddedilir.

Yukarıdaki üretim limitlerinin yanı sıra, Roblox verileri, içsel bir şemaya dayanarak partitionlara ayırır. Bu nedenle, arka uç sunucusu aynı veri deposuna yüksek hacimli istekler aldığında, daha fazla sınırlandırma ile sonuçlanabilir. Bunun nedeni ne olursa olsun, sınırlama, ya DatastoreThrottled ya da KeyThrottled hataları olarak ortaya çıkar, bu da üretim limitinin ya tek bir veri deposu ya da bir anahtar için aşıldığını gösterir. Bu hata mesajları, hem sıralı hem de standart veri deposuna uygulanır.

Depolama limitleri

Depolamanın istikrarlı ve ölçeklenebilir olmasını sağlamak için veri depoları, sizin depolama kullanımızda bir oyun düzeyi limiti kullanır.

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

Depolama limiti aşağıdaki formülle 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 kendinizin önceden sıkıştırmaktan kaçınmalısınız. Ön sıkıştırma, gereksiz CPU yükü ekler ve veri depolarının yerleşik sıkıştırmasının etkisini azaltabilir. Sıkıştırılmamış verileri saklayarak, Roblox'un sıkıştırma algoritmalarındaki iyileşmelerden ve gelecekteki şemaya dayalı optimizasyonlardan otomatik olarak faydalanırsınız.

Her anahtarın yalnızca en son sürümü depolama kullanımızı sayılır. Silinen anahtarlar ve kapsamlı sürümler, hala tutma süresi boyunca sürüm API'leri aracılığıyla erişilebilir olsa da, depolama kullanımınıza dahil edilmez. Ancak, Açık Bulut üzerinden silinen veri depoları, DeleteDataStore yöntemi ile 30 günlük silme işlem süresi boyunca depolama kullanımızı saymaya devam eder.