Oltre a accedere a depositi di dati utilizzando l'API del motore ( DataStoreService ) in Studio o su server live, puoi utilizzare le API Open Cloud per accedere e utilizzare dati standard e ordinati da script e strumenti esterni con accesso granulare e controllo della sicurezza.
Le API cloud aperte per i data store ordinati sono API beta che potrebbero essere soggette a modifiche per le future versioni.
Uso
Puoi migliorare diverse aree del tuo flusso di lavoro accedendo ai tuoi dati con queste API, come:
Portale di supporto cliente : I depositi di dati sono utili per archiviare risorse utente persistenti, come oggetti negli inventari degli utenti o punti di abilità.A volte è necessario aggiornare queste risorse per il Servizio Cliente.Piuttosto che utilizzare Studio o unirsi a un'esperienza manualmente, puoi costruire un'applicazione web per consentire ai tuoi agenti di servizio clienti di gestire direttamente le richieste di supporto cliente, come la visualizzazione e la modifica degli inventari degli utenti e l'emissione di rimborsi.
Dashboard di LiveOps : puoi costruire una dashboard di LiveOps utilizzando le API per migliorare l'efficienza delle operazioni dal vivo.Ad esempio, puoi programmare un evento in anticipo, nasconderlo sotto una bandiera di funzionalità come parte dei dati di configurazione in un Negoziodati e impostare un tempo per ribaltare la bandiera per la pubblicazione dell'evento.I server di esperienza possono rilevare questo cambiamento leggendo la bandiera per avviare l'evento.
Classifica esterna : Per promuovere le tue esperienze al di fuori di Roblox, puoi recuperare le informazioni della tua esperienza, come la classifica di una gara, in tempo reale e visualizzarle su un sito web esterno.Puoi concedere l'accesso solo in lettura ai tuoi negozi di dati ordinati per il sito Web per richiedere periodicamente i dati più recenti tramite HTTP e aggiornare la pagina web.
Automazione della migrazione dei dati : i dati possono cambiare o aggiornarsi mentre evolve la tua esperienza, come l'aggiornamento degli schemi di dati per accogliere nuove funzionalità.Per evitare di perdere i dati utente esistenti, a volte è necessario migrare i tuoi depositi di dati dallo schema vecchio a uno nuovo.Puoi scrivere uno script esterno che legge ciascuna entry dai data store attuali, mappa i dati al nuovo schema e scrive l'entry di nuovo in un nuovo data store per automatizzare la migrazione dei dati.
Differenze con l'API del motore
Sebbene le API Open Cloud siano simili a DataStoreService, ci sono alcune differenze chiave:
ID dell'universo e nome del deposito di dati : A differenza dell'API del motore, le API Open Cloud sono stateless e possono provenire da qualsiasi luogo, quindi devi sempre fornire l' ID dell'universo , l'identificatore univoco della tua esperienza, e il nome del deposito di dati nome quando invii le richieste.Per ulteriori informazioni su come ottenere un ID dell'universo, vedi ID dell'universo.
Permessi separati per la creazione e l'aggiornamento : l'API del motore crea nuove entrate se non esistono quando chiami DataStore:SetAsync() , ma i metodi Open Cloud per la creazione e l'aggiornamento delle entrate sono separati.Le autorizzazioni separate possono essere più sicure e più flessibili in alcune situazioni.Ad esempio, puoi creare uno strumento di supporto cliente che possa modificare il Profilodi un utente esistente, ma non può creare il Profilodi un nuovo utente.
Serializzazione dei dati : tutti i punti finali Open Cloud richiedono che tu serializzi tutti i dati prima del trasporto in rete.La serializzazione significa convertire un oggetto in una Stringa.La deserializzazione è l'opposto (trasformare una stringa in un oggetto).L'API del motore serializza e deserializza automaticamente il contenuto dell'entrata, ma per Open Cloud devi generare o parsare i tuoi dati di ingresso con JSON da Proprio.
Permessi di sicurezza
I depositi di dati spesso memorizzano informazioni sensibili, come profili utente e Monetavirtuale.Per mantenere la sicurezza, ogni Open Cloud API ha le corrispondenti autorizzazioni richieste che devi aggiungere alla tua chiave API, come l'autorizzazione List Keys per l'API di elenco.Se non aggiungi le autorizzazioni richieste, la chiamata API restituisce un errore.Per i permessi specifici richiesti per ciascuna operazione, vedi il riferimento API di standard e negozi di dati ordinati.
Quando configuri le tue chiavi API, puoi impostare permessi granulari, come lettura, scrittura e inserimento di record, per ciascun deposito di dati all'interno di un'esperienza specifica, o puoi dare una chiave per leggere o scrivere tutti i depositi di dati all'interno di un'esperienza.Puoi anche limitare l'accesso a un sottinsieme di archivi di dati necessari per il tuo strumento invece di esporre tutti gli archivi di dati.Questo mitiga l'impatto nel caso in cui la tua chiave venga divulgata.
Strumenti di build
Puoi usare la lingua di tua scelta per costruire strumenti con Open Cloud API per archivi di dati per soddisfare le tue esigenze di operazione.I seguenti esempi attraversano i processi di costruzione di un portale di supporto dell'inventario utente in Python con depositi di dati standard e un leaderboard persistente esterno utilizzando depositi di dati ordinati.
Portale di supporto dell'inventario utente
Questa sezione fornisce un esempio concreto di costruzione di un portale di supporto dell'inventario utente in Python, in cui puoi elencare e leggere un sottinsieme dell'inventario dei tuoi utenti, apportare modifiche e quindi aggiornare al data Negoziodi un'esperienza.
Per questo esempio, supponiamo quanto Seguendo:
Il nome del data store che memorizza l'inventario dell'utente è Inventory .
Lo schema di dati per ogni voce di dati è "userId": {"currency": number, "weapon": string, "level": number} . La chiave è solo userId .
Lo script Python elenca un sottinsieme degli inventari utente in base ai prefissi, aumenta la loro valuta virtuale di 10 per una Promozionee aggiorna i dati.
A Livelloalto, puoi costruire la tua app Python aggiungendo i permessi della chiave API e poi aggiungendo gli script.
Aggiungi le autorizzazioni della chiave API per i depositi di dati
Quando crei una chiave API per questo esempio, assicurati di eseguire le seguenti impostazioni:
Dal menu Seleziona sistema API nella sezione Permessi di accesso , seleziona uni-datastores dell'universo .
(Opzionale) Nella sezione Magazzini di dati , seleziona le operazioni API per magazzini di dati specifici.
- Abilita l'operazione attivare/disattivare Specific Data Store Operations .Per impostazione predefinita, cinque depositi di dati si Caricareautomaticamente, ma puoi aggiungere depositi di dati aggiuntivi attraverso il pulsante + Aggiungi deposito di dati alla lista .
- Seleziona la freccia a discesa accanto al nome di un Negoziodati, quindi seleziona le operazioni API a cui vuoi che l'archivio dati abbia accesso.
Seleziona le operazioni API per l'intera esperienza.
- Fai clic sul menu a discesa Seleziona esperienza da aggiungere e seleziona un'esperienza.
- Nelle Operazioni di esperienza , clicca la freccia a discesa e seleziona le operazioni che vuoi aggiungere alla tua API.Questo esempio seleziona Leggi entrata , Aggiorna entrata e Chiavi di entrata di lista per l'intera esperienza.
Non hai bisogno dell'autorizzazione della chiave API create entries poiché l'app non crea inventari utente nuovi.
Nella sezione Sicurezza , imposta esplicitamente l'accesso IP alla chiave utilizzando notazione CIDR, e imposta una data di scadenza esplicita in modo che la tua chiave smetta di funzionare dopo quella data.Per questo esempio, se hai intenzione di eseguire prima un test locale, puoi rimuovere la restrizione IP impostandola su 0.0.0.0/0 e lasciarla scadere in 30 giorni .
Aggiungi script per il portale di supporto dell'inventario utente
Dopo aver creato la chiave API con le autorizzazioni richieste per l'applicazionedi esempio, devi aggiungere il codice JavaScript per eseguire le funzionalità dell'app.Il file mostra come definire , e metodi.Il file update_inventory.js utilizza i metodi definiti per elencare un sottinsieme degli inventari degli utenti, aumentare la valuta virtuale per ogni utente e aggiornare i dati.
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`
);
});
}
Per testare, imposta la variabile ambientale API_KEY e esegui il file JavaScript:
Classifica persistente esterna
Questa sezione percorre un esempio concreto di creazione di una classifica persistente esterna in Python, in cui puoi elencare e leggere le informazioni degli utenti memorizzate negli store di dati ordinati, apportare modifiche e quindi pubblicare su un sito web esterno per la Promozione.
Per questo esempio, supponiamo quanto Seguendo:
L'esempio di codice crea un elenco predefinito di nomi utente per lo scopo della demo.Per la tua applicazione, dovresti utilizzare l'elenco degli utenti reali nella tua esperienza.
L'esempio di codice aggiunge 50 punti a ciascun utente che si unisce all'esperienza per lo scopo della demo.Per la tua applicazione, dovresti definire la regola in base al design della tua esperienza.
A Livelloalto, puoi costruire la tua app Python aggiungendo i permessi della chiave API e poi aggiungendo gli script.
Aggiungi le autorizzazioni della chiave API per i data store ordinati
L'app di esempio richiede quattro metodi per ottenere le sue funzionalità: List , Create , Update e Increment , quindi devi aggiungere i seguenti permessi API chiave:
- Leggi per il metodo list.
- Scrivi per Create , Update e Increment metodi.
Quando crei una chiave API per questo esempio, assicurati di eseguire le seguenti operazioni:
Dal menu Seleziona sistema API nella sezione Permessi di accesso ordinati , seleziona Magazzini di dati ordinati .
Aggiungi le autorizzazioni delle operazioni API per leggere e scrivere i data store ordinati nell'esperienza target.
- Fai clic sul menu a discesa Seleziona esperienza da aggiungere e seleziona l'esperienza target.
- Nelle Operazioni di esperienza , espandi il menu a discesa per selezionare Leggi e Scrivi operazioni.
Nella sezione Sicurezza , imposta esplicitamente l'accesso IP alla chiave utilizzando notazione CIDR, e imposta una data di scadenza esplicita in modo che la tua chiave smetta di funzionare dopo quella data.Per questo esempio, se hai intenzione di eseguire prima un test locale, puoi rimuovere la restrizione IP impostandola su 0.0.0.0/0 e lasciarla scadere in 30 giorni .
Aggiungi script per la Classifica
Dopo aver creato la chiave API con le autorizzazioni richieste per l'applicazionedi esempio, devi aggiungere il codice JavaScript per eseguire le funzionalità dell'app.
Il file ordered_data_stores.js mostra come definire List , Create , Update , e Increment metodi.Il file leaderboard.js utilizza i metodi definiti per creare le entrate degli utenti negli store di dati ordinati, visualizzare i punteggi, aumentare i punteggi dei vincitori e aggiornare la Classifica.Il file leaderboard.js importa anche un file config.json per configurare l'ID dell'universo, il dominio API e la chiave 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);
});
config
{
"universe_id": "",
"api_key_url": "https://apis.roblox.com/datastores/ordered-v1/",
"api_key": ""
}
Per testare, imposta la variabile ambientale API_KEY e esegui il file leaderboard.js:
Dopo aver completato i test, puoi pubblicare o incorporare la classifica ai siti web al di fuori di Roblox per una maggiore portata.