Ayrıca, Studio veya canlı oyunlarda (DataStoreService) veri depolarına erişmenin yanı sıra, dış betikler ve diğer araçlar aracılığıyla standart ve sıralı veri depoları erişmek için Açık Bulut API'lerini kullanabilirsiniz.
Açık Bulut erişimi, veri depolarınıza birçok potansiyel kullanım alanı açar, bunlar arasında:
- Kullanıcı envanterlerini değiştirme veya iade işlemleri gibi destek taleplerini ekip üyelerinizin doğrudan ele almasını sağlamak için bir müşteri destek portalı
- Dış bir web sitesinde görüntüleyebileceğiniz global liderlik tabloları
- Mevcut veri deposundan girişleri okuyan, bunları yeni bir şemaya eşleyen ve girişleri yeni bir veri deposuna yazan betiklerle şema güncellemeleri
Bu sayfadaki örnekler, Node.js ve Python ile bir kullanıcı envanteri destek portalı ve bir harici liderlik tablosu nasıl oluşturacağını gösterir, ancak tercih ettiğiniz herhangi bir dili kullanabilirsiniz; Açık Bulut API'leri, bir HTTP isteği gönderebilen herhangi bir programlama dilini destekler.
Engine API'den Farklılıklar
Açık Bulut API'leri aynı temel veri depolarına erişirken ve DataStoreService ile çalışmaya benzer görünse de, birkaç temel fark vardır:
Evrensel Kimlik: Engine API'nin aksine, Açık Bulut API'leri durum bilgisi tutmaz ve her yerden gelebilir, bu nedenle her zaman oyununuzun benzersiz tanımlayıcısı olan evrensel kimliği sağlamanız gerekir.
Oluşturma ve güncelleme için ayrı izinler: Engine API, DataStore:SetAsync() çağrısı yaptığınızda yeni girişler oluşturarak işlem yapar, ancak Açık Bulut yöntemleri için oluşturma ve güncelleme işlemleri ayrıdır. Ayrı izinler, belirli durumlarda daha güvenli ve esnek olabilir. Örneğin, müşteri destek aracınızın yalnızca mevcut bir kullanıcının profilini düzenlemesine, yeni bir tane oluşturmasına izin vermek istemeyebilirsiniz.
Veri serileştirme: Tüm Açık Bulut uç noktaları, verileri göndermeden önce serileştirmenizi gerektirir. Serileştirme, bir nesneyi bir dizeye dönüştürme işlemidir. Serileştirmeden çıkarma ise tersidir, bir diziyi bir nesneye dönüştürmektir. Engine API, giriş içeriğini otomatik olarak serileştirir ve serileştirirken açığa çıkarır, ancak Açık Bulut için girişinizi JSON'a kendiniz üretmeniz veya ayrıştırmanız gerekmektedir.
İzinler
Veri depoları genellikle kullanıcı profilleri ve sanal para gibi hassas bilgileri saklar. Güvenliği korumak için, her Açık Bulut yöntemi için gerekli izinler, API anahtarınıza eklemeniz gereken kapsamlar ile tanımlanmıştır, örneğin Veri Depolarını Listele yöntemi için universe-datastores.control:list kapsamı. Gerekli izinleri eklemezseniz, API çağrınız bir hata döndürür. Her uç nokta için gerekli kapsamlar hakkında daha fazla bilgi için referans belgelerine bakın.
İzinlerin yönetimi hakkında daha fazla bilgi için API anahtarlarını yönetin konusuna bakın.
Kullanıcı envanteri destek portalı
Bu örnek, her giriş için "userId": {"currency": number, "weapon": string, "level": number} şemasına sahip Inventory adlı bir veri deposu kullanır. Anahtar userId'dir.
Gerekli kapsamlar
Bu örnek için API Anahtarı oluştururken, anahtarınıza aşağıdaki kapsamları ekleyin:
- universe-datastores.objects:list
- universe-datastores.objects:read
- universe-datastores.objects:update
İsteğe bağlı olarak, yalnızca Inventory veri deposu için izin ekleyebilir, bir IP adresi sınırlaması belirleyebilir ve bir sonlandırma tarihi ayarlayabilirsiniz.
Kullanıcı envanteri destek portalı için betikler ekleyin
Gerekli izinlerle API anahtarını oluşturduktan sonra, uç noktalara istek yapmak için bir betik oluşturabilirsiniz. Bu betikler, veri deposundaki ilk 10 girişi alır, her birinin currency değerini 10 artırır ve ardından her girişi günceller. Daha büyük bir veri deposu için maxPageSize ve pageToken sorgu parametrelerini kullanarak sayfalandırma ile başa çıkmanız gerekecektir.
incrementCurrency.js
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/';
async function listEntries(universe, dataStore) {
const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
const url = baseUrl + listPath;
const response = await fetch(url, {
headers: { [apiHeaderKey]: apiKey }
});
return response.json();
}
async function getEntry(path) {
const url = baseUrl + path;
const response = await fetch(url, {
headers: { [apiHeaderKey]: apiKey }
});
return response.json();
}
async function updateEntry(path, payload) {
const url = baseUrl + path;
const response = await fetch(url, {
method: 'PATCH',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload) // Gövde bir dize olmalıdır
});
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('Çalışma sırasında bir hata oluştu:', error);
}
})();
Test etmek için API_KEY ortam değişkenini ayarlayın, bağımlılıkları yükleyin ve betiği çalıştırın:
Harici kalıcı liderlik tablosu
Bu örnek, demo amaçları için önceden tanımlanmış bir kullanıcı listesi oluşturur, ancak gerçek bir oyunda yararlı olabilmesi için gerçek bir kullanıcı veri deposuna ihtiyacınız olacaktır.
Gerekli kapsamlar
Bu örnek için API Anahtarı oluştururken anahtarınıza aşağıdaki kapsamları ekleyin:
- universe.ordered-data-store.scope.entry:read
- universe.ordered-data-store.scope.entry:write
Liderlik tablosu için betikler ekleyin
Gerekli izinlerle API anahtarını oluşturduktan sonra, uç noktalara istek yapmak için bir betik oluşturabilirsiniz. Bu betikler, sıralı veri deposuna rastgele rakamlarla bazı örnek girişler ekler ve ardından en yüksekten en düşüğe doğru bunları alır. Daha büyük bir veri deposu için maxPageSize ve pageToken sorgu parametrelerini kullanarak sayfalandırma ile başa çıkmanız gerekecektir.
leaderboard.js
const apiKey = process.env.API_KEY;
const apiHeaderKey = 'x-api-key';
const universeId = '';
const orderedDataStoreId = 'PlayerScores';
const scopeId = 'global';
const baseUrl = 'https://apis.roblox.com/cloud/v2/';
async function createOrderedEntry(universe, orderedDataStore, entryId, payload) {
const createPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;
const url = new URL(baseUrl + createPath);
url.searchParams.append('id', entryId);
const response = await fetch(url, {
method: 'POST',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(`API Hatası (${response.status}): ${errorText}`);
}
return response.text();
}
async function listOrderedEntries(universe, orderedDataStore) {
const listPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;
const url = new URL(baseUrl + listPath);
url.searchParams.append('orderBy', 'value desc');
return fetch(url, {
headers: {
[apiHeaderKey]: apiKey,
},
});
}
async function main() {
if (!apiKey) {
console.error('Hata: API_KEY ortam değişkeni ayarlanmamış.');
process.exit(1);
}
const entryNames = ['Ragdoll', 'Balinese', 'Tabby', 'Siamese'];
console.log('Örnek veriler oluşturuluyor...');
for (const name of entryNames) {
try {
const randomValue = Math.floor(Math.random() * 50) + 1;
const payload = { value: randomValue };
const responseText = await createOrderedEntry(universeId, orderedDataStoreId, name, payload);
console.log(responseText);
} catch (error) {
console.error(`"${name}" için giriş oluşturulamadı: ${error.message}`);
}
}
console.log('\nSıralı giriş listesini alınıyor...');
try {
const playerScoresResponse = await listOrderedEntries(universeId, orderedDataStoreId);
console.log(playerScoresResponse.status);
const responseText = await playerScoresResponse.text();
console.log(responseText);
} catch (error) {
console.error(`Girişler listelenirken hata oluştu: ${error.message}`);
}
}
main();
Test etmek için API_KEY ortam değişkenini ayarlayın, bağımlılıkları yükleyin ve betiği çalıştırın: