Oprócz dostępu do magazynów danych za pomocą API Engine ( DataStoreService ) w Studio lub na żywych serwerach możesz użyć otwartych chmurowych API, aby uzyskać dostęp i wykorzystać standardowe i zamówione magazyny danych z zewnętrznymi skryptami i narzędziami z granularnym dostępem i kontrolą bezpieczeństwa.
Otwórz API chmury dla zamówionych magazynów danych są API beta, które mogą być przedmiotem zmian w przyszłych wersjach.
Użycie
Możesz poprawić kilka obszarów swojego przepływu pracy, uzyskując dostęp do swoich danych za pomocą tych interfejsów programistycznych, takich jak:
Portal wsparcia klienta : Magazyny danych są przydatne do przechowywania trwałych zasobów użytkownika, takich jak przedmioty w ekwipunku użytkownika lub punkty umiejętności.Czasami musisz aktualizować te zasoby dla dział wsparcia klientów.Zamiast używać Studio lub dołączać do doświadczenia ręcznie, możesz zbudować aplikację internetową, aby umożliwić agentom obsługi klienta bezpośrednie radzenie sobie z wnioskami o wsparcie klienta, takimi jak oglądanie i modyfikowanie zapasów użytkowników oraz wydawanie zwrotów.
Panel główny LiveOps : Możesz budować panel główny LiveOps za pomocą API, aby poprawić wydajność działań na żywo.Na przykład możesz zaplanować wydarzenie z wyprzedzeniem, ukryć je pod flagą funkcji jako część danych konfiguracyjnych w sklepdanych i ustawić czas, aby odwrócić flagę do publikacji wydarzenia.Serwery doświadczeń mogą wykryć tę zmianę, odczytując flagę, aby uruchomić wydarzenie.
Zewnętrzna tabela wyników : Aby promować swoje doświadczenia poza Robloxem, możesz pobrać informacje o swoim doświadczeniu, takie jak tabela wyników wyścigu, w czasie rzeczywistym i wyświetlić ją na zewnętrznej stronie internetowej.Możesz przyznać dostęp tylko do odczytu do przechowywanych zamówionych plików danych dla witryny, aby okresowo żądała najnowszych danych za pośrednictwem HTTP i aktualizowała stronę internetową.
Automatyzacja migracji danych : Dane mogą się zmienić lub zaktualizować wraz z rozwojem twojego doświadczenia, tak jak ulepszanie schematów danych, aby uwzględnić nowe funkcje.Aby uniknąć utraty istniejących danych użytkownika, czasami musisz przenieść swoje magazyny danych ze starej schematy do nowej.Możesz napisać zewnętrzny skrypt, który odczytuje każdą pozycję z obecnych magazynów danych, mapuje dane do nowego schematu i zapisuje pozycję z powrotem do nowego magazynu danych, aby zautomatyzować migrację danych.
Różnice z API silnika
Chociaż otwarte API chmury są podobne do DataStoreService, istnieją kilka kluczowych różnic:
ID uniwersum i nazwa przechowywania danych : W przeciwieństwie do API silnika, otwarte API chmury są bezpaństwowe i mogą pochodzić z dowolnego miejsca, więc zawsze musisz podawać identyfikator uniwersum , unikalny identyfikator twojego doświadczenia, oraz nazwę przechowywania danych nazwa podczas wysyłania żądań.Aby uzyskać więcej informacji o tym, jak uzyskać ID wszechświata, zobacz ID wszechświata.
Odrębne uprawnienia do tworzenia i aktualizowania : API silnika tworzy nowe wpisy, jeśli nie istnieją, gdy wzywasz DataStore:SetAsync(), ale metody Open Cloud do tworzenia i aktualizowania wpisów są odrębne.Odrębne uprawnienia mogą być bezpieczniejsze i bardziej elastyczne w niektórych sytuacjach.Na przykład możesz stworzyć narzędzie wsparcia klienta, które może edytować profil istniejącego użytkownika, ale nie może tworzyć nowego profilu użytkownika.
Serjalizacja danych : Wszystkie otwarte punkty końcowe chmury wymagają od ciebie serjalizacji wszystkich danych przed przesłaniem ich przez sieć.Serjalizacja oznacza przekształcenie obiektu w ciąg.Deserializacja jest odwrotnością (przekształcanie ciągu w obiekt).API silnika automatycznie serializuje i dezserializuje zawartość wejścia, ale w przypadku Open Cloud musisz generować lub parować swoje dane wejściowe za pomocą JSON na posiadać.
Uprawnienia bezpieczeństwa
Magazyny danych często przechowują wrażliwe informacje, takie jak profile użytkowników i wirtualna waluta.Aby zachować bezpieczeństwo, każdy otwarty API chmury ma odpowiednie wymagane uprawnienia, które musisz dodać do klucza API, takie jak uprawnienie List Keys do API listowania.Jeśli nie dodasz wymaganych uprawnień, wezwanie API zwraca błąd.Dla konkretnych uprawnień, które są wymagane dla każdej operacji, zobacz odniesienie API do standardowego i uporządkowanych magazynów danych.
Gdy konfigurujesz klucze API, możesz ustawić granularne uprawnienia, takie jak czytanie, przeczytanei wpisywanie danych, dla każdego magazynu danych w określonym doświadczeniu, lub możesz dać klucz do odczytu lub pisania wszystkich magazynów danych w doświadczeniu.Możesz również ograniczyć dostęp do podzbioru przechowywanych danych potrzebnych do twojego narzędzia zamiast ujawniać wszystkie przechowywane dane.Zmniejsza to wpływ w przypadku wycieku klucza.
Narzędzia budowania
Możesz używać języka swojego wyboru, aby budować narzędzia z Otwarte API chmury dla magazynów danych, aby spełnić swoje potrzeby operacyjne.Poniższe przykłady przechodzą przez procesy budowania portalu wsparcia dla inwentarza użytkownika w Pythonie za pomocą standardowych magazynów danych i zewnętrznej trwałej tabeli liderów za pomocą przechowywanych danych w kolejności.
Portal wsparcia dla ekwipunku użytkownika
Ta sekcja dostarcza konkretny przykład budowy portalu wsparcia dla ekwipunku użytkownika w Pythonie, w którym możesz wymienić i przeczytać podzbiór zapasów wyposażenie, wprowadzić zmiany, a następnie zaktualizować powrót do sklepdanych doświadczenia.
W tym przykładzie załóż obserwuje:
Nazwa magazynu danych, który przechowuje ekwipunek użytkownika, to Inventory .
Schemat danych dla każdej pozycji danych jest "userId": {"currency": number, "weapon": string, "level": number}. Klucz jest tylko userId.
Skrypt Python wymienia podzbiór ekwipunków użytkownika na podstawie prefiksów, zwiększając ich wirtualną walutę o 10 na promocjai aktualizując dane.
Z wysokiego poziomu możesz budować swoją aplikację Python, dodając uprawnienia klucza API, a następnie dodając skrypty.
Dodaj uprawnienia klucza API dla przechowywania danych
Gdy tworzysz klucz API dla tego przykładu, upewnij się, że wykonasz następujące ustawienia:
Z menu Wybierz system API w sekcji uprawnień dostępu wybierz przechowywanie danych wszechświata .
(Opcjonalnie) W sekcji Magazyny danych wybierz operacje API dla konkretnych magazynów danych.
- Włącz przełącznik Specyficzne operacje przechowywania danych .Domyślnie pięć magazynów danych automatycznie się wczytywać, ale możesz dodać dodatkowe magazyny danych za pomocą przycisku + Dodaj magazyn danych do listy .
- Wybierz strzał rozwijany obok nazwy sklepdanych, a następnie wybierz operacje API, do których chcesz, aby przechowywanie danych miało dostęp.
Wybierz operacje API dla całego doświadczenia.
- Kliknij Wybierz doświadczenie, aby dodać menu rozwijane i wybierz doświadczenie.
- W operacjach doświadczenia kliknij strzał rozwijany i wybierz operacje, które chcesz dodać do swojego API .Ten przykład wybiera Przeczytaj wpis , Zaktualizuj wpis i Klucze listy wpisów dla całego doświadczenia.
Nie potrzebujesz uprawnień klucza API create entries, ponieważ aplikacja nie tworzy nowych inventarzy użytkowników.
W sekcji Bezpieczeństwo , wyraźnie ustaw nawiązanie dostępu IP do klucza za pomocą notacji CIDR i ustaw wyraźną datę wygaśnięcia, aby klucz automatycznie przestał działać po tej dacie.W tym przykładzie, jeśli planujesz najpierw przeprowadzić lokalne testy, możesz usunąć ograniczenie IP, ustawiając je na 0.0.0.0/0 i pozwolić mu wygasnąć za 30 dni .
Dodaj skrypty dla portalu wsparcia dla ewidencji użytkowników
Po utworzeniu klucza API z wymaganymi uprawnieniami dla przykładowej aplikacjamusisz dodać kod JavaScript, aby wykonać funkcjonalności aplikacji.Plik pokazuje, jak określić , oraz metody.Plik update_inventory.js używa zdefiniowanych metod, aby wymienić podzbiór ekwipunków użytkownika, zwiększyć wirtualną walutę dla każdego użytkownika i aktualizować dane.
dataStoresMethods.js
const fetch = require('node-fetch');
class DataStores {
constructor() {
this._baseUrl =
'https://apis.roblox.com/datastores/v1/universes/{universeId}';
this._apiKey = process.env.API_KEY;
this._universeId = 'UNIVERSE_ID';
this.ATTR_HDR = 'Roblox-entry-Attributes';
this.USER_ID_HDR = 'Roblox-entry-UserIds';
this._objectsUrl = `${this._baseUrl}${this._universeId}/standard-datastores/datastore/entries/entry`;
this._incrementUrl = `${this._objectsUrl}/increment`;
this._listObjectsUrl = `${this._baseUrl}${this._universeId}/standard-datastores/datastore/entries`;
}
async _getHeaders() {
return { 'x-api-key': this._apiKey };
}
async getEntry(datastore, objectKey, scope = null) {
const url = `${
this._objectsUrl
}?datastoreName=${datastore}&entryKey=${objectKey}&scope=${scope || ''}`;
const response = await fetch(url, { headers: await this._getHeaders() });
const data = await response.json();
return data;
}
async listEntries(datastore, scope = null, prefix = '', limit = 100) {
const url = `${this._listObjectsUrl}?datastoreName=${datastore}&scope=${scope}&prefix=${prefix}&limit=${limit}`;
const response = await fetch(url, { headers: await this._getHeaders() });
const data = await response.json();
return data;
}
async incrementEntry(datastore, objectKey, incrementBy, scope = null) {
const url = `${
this._incrementUrl
}?datastoreName=${datastore}&entryKey=${objectKey}&incrementBy=${incrementBy}&scope=${
scope || ''
}`;
const response = await fetch(url, {
method: 'POST',
headers: await this._getHeaders(),
});
const data = await response.json();
return data;
}
}
module.exports = DataStores;
updateInventory.js
const DataStores = require('./dataStoresMethods');
const dataStoresApi = new DataStores();
// Set up
const datastoreName = 'Inventory';
// List keys for a subset of users
dataStoresApi.listEntries(datastoreName).then((keys) => {
console.log(keys);
});
// Read inventory for each user
for (let x = 0; x < 5; x++) {
const updatedObjectKey = `User_${x + 1}`;
dataStoresApi.getEntry(datastoreName, updatedObjectKey).then((value) => {
console.log(
`${updatedObjectKey} has ${value.gems} gems in their inventory`
);
});
}
// Update the currency of each user by 10
for (let x = 0; x < 5; x++) {
const updatedObjectKey = `User_${x + 1}`;
dataStoresApi
.incrementEntry(datastoreName, updatedObjectKey, 10)
.then((value) => {
console.log(
`${updatedObjectKey} now has ${value.robux} robux in their inventory`
);
});
}
Aby przetestować, ustaw zmienną środowiska API_KEY i uruchom plik JavaScript:
Zewnętrzna trwała tabela ranking
Ta sekcja przechodzi przez konkretny przykład tworzenia zewnętrznego trwałego rankingu w Pythonie, w którym możesz wymienić i przeczytać informacje o użytkownikach przechowywane w uporządkowanych magazynach danych, wprowadzić zmiany i następnie opublikować na zewnętrznej stronie internetowej do promocja.
W tym przykładzie załóż obserwuje:
Próbka kodu tworzy wstępną listę nazw użytkowników do celów demonstracyjnych.Dla własnej aplikacji powinieneś użyć listy rzeczywistych użytkowników w swoim doświadczeniu.
Próbka kodu dodaje 50 punktów każdemu użytkownikowi, który dołącza do doświadczenia w celu demonstracji.Dla własnej aplikacji powinieneś określić zasadę w oparciu o projekt swojego doświadczenia.
Z wysokiego poziomu możesz budować swoją aplikację Python, dodając uprawnienia klucza API, a następnie dodając skrypty.
Dodaj uprawnienia klucza API dla zamówionych magazynów danych
Aplikacja przykładowa wymaga czterech metod, aby osiągnąć swoje funkcjonalności: List , Create , Update i Increment , więc musisz dodać następujące uprawnienia klucza API:
- Przeczytaj dla metody list.
- Napisz dla Create , Update i Increment metod.
Gdy tworzysz klucz API dla tego przykładu, upewnij się, że wykonasz następujące operacje:
Z menu Wybierz system API w sekcji Uprawnienia dostępu wybierz Sklepy danych uporządkowane .
Dodaj uprawnienia operacji API do odczytu i zapisu uporządkowanych magazynów danych w docelowym doświadczeniu.
- Kliknij Wybierz doświadczenie, aby dodać menu rozwijane i wybierz docelowe doświadczenie.
- W operacjach doświadczenia , rozszerz menu rozwijanego, aby wybrać operacje Przeczytaj i Napisz .
W sekcji Bezpieczeństwo , wyraźnie ustaw nawiązanie dostępu IP do klucza za pomocą notacji CIDR i ustaw wyraźną datę wygaśnięcia, aby klucz automatycznie przestał działać po tej dacie.W tym przykładzie, jeśli planujesz najpierw przeprowadzić lokalne testy, możesz usunąć ograniczenie IP, ustawiając je na 0.0.0.0/0 i pozwolić mu wygasnąć za 30 dni .
Dodaj skrypty dla tabeli ranking
Po utworzeniu klucza API z wymaganymi uprawnieniami dla przykładowej aplikacjamusisz dodać kod JavaScript, aby wykonać funkcjonalności aplikacji.
Plik ordered_data_stores.js pokazuje, jak określić List , Create , Update , i Increment metody.Plik leaderboard.js używa zdefiniowanych metod, aby tworzyć wpisy użytkowników w uporządkowanych rankingdanych, wyświetlać wyniki, zwiększać wyniki wygrywających użytkowników i aktualizować tabelę wyników.Plik leaderboard.js importuje również plik config.json do konfiguracji ID wszechświata, domeny API i klucza API.
ordered_data_stores.js
const axios = require('axios');
const fs = require('fs');
class DataStores {
constructor(configFile) {
this._config = JSON.parse(fs.readFileSync(configFile, 'utf-8'));
}
_H() {
return {
'x-api-key': this._config.api_key,
'Content-Type': 'application/json',
};
}
async list(
datastore,
scope,
pageSize = 10,
orderBy = '',
filter = '',
exclusiveStartKey = ''
) {
const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries`;
const response = await axios.get(url, {
headers: this._H(),
params: {
max_page_size: pageSize,
order_by: orderBy,
filter: filter,
page_token: exclusiveStartKey,
},
});
return response.data;
}
async create(datastore, scope, entry, data) {
const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries`;
const payload = JSON.stringify({ value: 11 });
const response = await axios.post(url, payload, {
headers: this._H(),
params: { id: entry },
});
return response.data;
}
async increment(datastore, scope, entry, incrementBy) {
const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries/${entry}:increment`;
const payload = JSON.stringify({ amount: incrementBy });
const response = await axios.post(url, payload, { headers: this._H() });
return response.data;
}
}
leaderboard.js
const leaderboardEndpoints = require('./ordered_data_stores');
const datastores = new leaderboardEndpoints.DataStores('config.json');
// Variables
const orderedDataStore = 'PlayerScores';
const scope = 'global';
const entryNames = ['Ragdoll', 'Balinese', 'Tabby', 'Siamese'];
// Create an entry and give each new player 50 points for joining the game
entryNames.forEach(async (name) => {
await datastores.create(orderedDataStore, scope, name, 50);
});
// Display the players' scores
datastores.list(orderedDataStore, scope).then((playerScores) => {
console.log(playerScores);
});
// Increment the first player's score for winning the game
datastores.increment(orderedDataStore, scope, entryNames[0], 100);
// Increment all the players' scores for participating in the game
entryNames.forEach(async (name) => {
await datastores.increment(orderedDataStore, scope, name, 10);
});
// Display the updated leaderboard
datastores.list(orderedDataStore, scope).then((updatedPlayerScores) => {
console.log(updatedPlayerScores);
});
konfiguracja
{
"universe_id": "",
"api_key_url": "https://apis.roblox.com/datastores/ordered-v1/",
"api_key": ""
}
Aby przetestować, ustaw zmienną środowiska API_KEY i uruchom plik leaderboard.js:
Po zakończeniu testów możesz opublikować lub osadzić tabelę liderów na stronach internetowych poza Robloxem, aby uzyskać większy zasięg.