Guida all'uso per i depositi di dati

*Questo contenuto è tradotto usando AI (Beta) e potrebbe contenere errori. Per visualizzare questa pagina in inglese, clicca qui.

Oltre a accedere a archivi di dati utilizzando Lua DataStoreService in Studio o nei server live, puoi utilizzare le API Open Cloud per accedere e utilizzare archivi di dati standard e 1>archivi di dati ordinati1> da script e strumenti con accesso granulare e controllo di sicurezza.

Uso

Puoi migliorare diverse aree del tuo flusso di lavoro accedendo ai tuoi dati con queste API, come:

  • Portale di supporto per i clienti : I magazzini di dati sono utili per archiviare risorse utente persistenti, come oggetti negli inventari utente o punti abilità. A volte è necessario aggiornare queste risorse per il Assistenzadel cliente. Invece di utilizzare Studio o unirsi a un'esperienza ogni volta manualmente, puoi creare un'applicazione web per consentire ai tuoi agent di servizio clienti di gestire direttamente le richieste di supporto del cliente, come

  • Dashboard di LiveOps : Puoi costruire una dashboard di LiveOps utilizzando le API per migliorare l'efficienza delle operazioni dal vivo, come la programmazione degli eventi in-experience. Puoi codificare un evento in anticipo, nascere sotto una bandiera di funzione come parte dei dati di configurazione in un data Negozioe impostare un tempo per翻旗 per pubblicare l'evento. I tuoi server di esperienza possono rilevare questo cambiamento leggendo la bandiera

  • Leaderboard esterna : Per promuovere le tue esperienze al di fuori di Roblox, puoi estrarre le informazioni sulla tua esperienza, come la classifica di una gara, in tempo reale e visualizzarle su un sito Web esterno. Puoi concedere l'accesso di lettura ai tuoi dati ordinati per il sito Web per richiedere periodically il più recente dati attraverso HTTP e aggiornare la pagina web.

  • Automatizzazione della migrazione dei dati : I dati possono cambiare o aggiornare mentre la tua esperienza si evolve, come l'aggiornamento dei schemi di dati per accogliere nuove funzionalità. Per evitare di perdere i dati dell'utente esistenti, a volte è necessario migrare i tuoi dati memorizzati dallo schema vecchio a uno nuovo. Puoi scrivere uno script esterno che legge ogni riga dai

Differenze con l'API Lua

Anche se le API Open Cloud sono simili alle Lua DataStoreService , ci sono alcuni requisiti diversi di cui essere consapevoli:

  • ID e nome del magazzino dei dati dell'universo : a differenza della API Lua, le API Open Cloud sono stateless e possono provenire da qualsiasi luogo, quindi devi sempre fornire il ID dell'universo , l'identificatore unico della tua esperienza, e il nome del magazzino nome quando invii le richieste. Per ulteriori informazioni su come ottenere un ID dell'universo, vedi

  • Permessi separati per la creazione e l'aggiornamento : La API Lua crea nuovi record se non esistono quando chiami DataStore:SetAsync() , ma i metodi Open Cloud per la creazione e l'aggiornamento dei record sono separati. I permessi separati possono essere più sicuri e flessibili in alcune situazioni. Ad esempio, puoi creare uno strumento di supporto per i client che può modific

  • serializzazione dei dati : Tutti i punti di interfaccia cloud aperti richiedono che tu serIALizzi tutti i dati prima del trasporto di rete. La serializzazione significa convertire un oggetto in quella Stringa, e la deserializzazione è la sua operazione inversa (converti una stringa in un oggetto). La API Lua serializza e deserializza automaticamente il contenuto dell'ingresso, ma per Open Cloud devi generare o elaborare i tuoi dati di ingresso con JSON da Proprio.

Permessi di sicurezza

I negozi di dati di solito memorizzano informazioni sensibili, come profili utente e Monetavirtuale. Per mantenere la sicurezza, ogni API Open Cloud ha i permessi richiesti che devi aggiungere alla tua chiave API, come il permesso List Keys per l'API di elenco. Se non aggiungi i permessi richiesti, il tuo chiamata API restituisce un errore

Quando configurare le tue chiavi API , puoi impostare autorizzazioni granulari, come la lettura, la scrittura e la lista di entrata, per ciascun data store all'interno di un'esperienza specifica, o puoi dare una chiave per leggere o scrivere tutti i data store all'interno di un'esperienza. Puoi anche limitare l'accesso a uno script di dati necessario per il tuo strumento in caso di perdita delle chiavi. Questo mitiga

Strumenti di costruzione

Puoi usare la lingua di tua scelta per creare strumenti con Apri Cloud API per il datastore per soddisfare le tue esigenze di operazione. I seguenti esempi mostrano i processi di costruzione di un portal dell'inventario utente in Python con archiviazione standard e un Externo Persistente Leaderboard usando i datastore ordinati.

Portale di supporto per l'inventario utente

Questa sezione fornisce un esempio concreto di costruzione di un portale di supporto per l'inventario utente in Python, in cui puoi elencare e leggere un sottoinsieme dell'Inventario, reportorioutente, fare modifiche e quindi aggiornare al Negoziodi dati di un'esperienza.

Per questo esempio, supponi Seguendo:

  • Il nome del data store che memorizza l'inventario dell'utente è Inventory .

  • Lo schema dei dati per ciascuna voce di dati è "userId": {"currency": number, "weapon": string, "level": number} . La chiave è solo userId .

  • Lo script Python elenca un sottoinsieme di inventari utente basato sui premi, aumenta la loro valuta virtuale di 10 per una Promozionee aggiorna i dati.

Da un Livelloelevato, puoi creare la tua app Python aggiungendo autorizzazioni API e quindi aggiungendo script.

Aggiungere autorizzazioni chiave API per i magazzini di dati

Quando crei una chiave API per questo esempio, assicurati di eseguire le seguenti impostazioni:

  1. Dal menu Seleziona sistema API nella sezione Accesso ai permessi , seleziona archivio-datastores .

  2. (Facoltativo) In the Data Stores section, select API operations for specific data stores.

    1. Abilita il attivare/disattivare Specifiche Operazioni di Archiviazione Dati per abilitare le operazioni di archiviazione dei dati. Di default, cinque archivi di dati vengono Caricareautomaticamente, ma puoi aggiungere ulteriori archivi di dati attraverso il pulsante Aggiungi archivio di dati alla lista .
    2. Seleziona la freccia a discesa accanto al nome di un data Negozio, quindi seleziona le operazioni API che vuoi che il data store abbia accesso.
  3. Seleziona API operazioni per l'intera esperienza.

    1. Fai clic sul pulsante Seleziona Esperienza per Aggiungere dropdown e seleziona un'esperienza.
    2. Nelle Operazioni sull'Esperienza, fai clic sulla freccia a discesa e seleziona le operazioni che vuoi aggiungere alla tua API. Questo esempio seleziona Leggi l'articolo, Aggiorna l'articolo e 2> Elenca gli elementi chiave dell'esperienza2> per l'intera esperienza.
  4. Nella sezione Sicurezza, imposta esplicitamente l'accesso IP all'area utilizzando notazione CIDR , e imposta una data di scadenza esplicita in modo che la tua chiave smetti di funzionare dopo quel giorno. Per questo esempio, se vuoi prima eseguire un test locale, puoi rimuovere la restrizione IP impostandola su 0.0.0.0/

Aggiungere script per il portale di supporto per l'inventario utente

Dopo aver creato la chiave API con i permessi richiesti per l'esempio applicazione, devi aggiungere script Python per eseguire le funzionalità dell'app. Il file data_stores_methods.py mostra

data_stores_methods.py

import hashlib
import requests
import json
import base64
class DataStores:
def __init__(self):
self._base_url = "https://apis.roblox.com/datastores/v1/universes/{universeId}"
# La chiave API viene salvata in una variabile ambientale chiamata 'API_KEY'
self._apiKey = str(os.environ['API_KEY'])
self._universeId = "UNIVERSE_ID"
self.ATTR_HDR = 'Roblox-entry-Attributes'
self.USER_ID_HDR = 'Roblox-entry-UserIds'
self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry'
self._increment_url = self._objects_url + '/increment'
self._version_url = self._objects_url + '/versions/version'
self._list_objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries'
def _H(self):
return { 'x-api-key' : self._apiKey }
def _get_url(self, path_format: str):
return f"{self._config['base_url']}/{path_format.format(self._config['universe_id'])}"
return r, attributes, user_ids
def get_entry(self, datastore, object_key, scope = None):
self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry'
headers = { 'x-api-key' : self._apiKey }
params={"datastoreName" : datastore, "entryKey" : object_key}
if scope:
params["scope"] = scope
r = requests.get(self._objects_url, headers=headers, params=params)
if 'Content-MD5' in r.headers:
expected_checksum = r.headers['Content-MD5']
checksum = base64.b64encode(hashlib.md5(r.content).digest())
#print(f'Expected {Expected_checksum}, ottenuto {checksum})
attributes = None
if self.ATTR_HDR in r.headers:
attributes = json.loads(r.headers[self.ATTR_HDR])
user_ids = []
if self.USER_ID_HDR in r.headers:
user_ids = json.loads(r.headers[self.USER_ID_HDR])
return r
def list_entries(self, datastore, scope = None, prefix="", limit=100, allScopes = False, exclusive_start_key=None):
self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries'
headers = { 'x-api-key' : self._apiKey }
r = requests.get(self._objects_url, headers=headers, params={"datastoreName" : datastore, "scope" : scope, "allScopes" : allScopes, "prefix" : prefix, "limit" : 100, "cursor" : exclusive_start_key})
return r
def increment_entry(self, datastore, object_key, incrementBy, scope = None, attributes=None, user_ids=None):
self._objects_url = self._base_url +self._universeId+'/standard-datastores/datastore/entries/entry/increment'
headers = { 'x-api-key' : self._apiKey, 'Content-Type': 'application/octet-stream' }
params={"datastoreName" : datastore, "entryKey" : object_key, "incrementBy" : incrementBy}
if scope:
params["scope"] = scope
r = requests.post(self._objects_url, headers=headers, params=params)
attributes = None
if self.ATTR_HDR in r.headers:
attributes = json.loads(r.headers[self.ATTR_HDR])
user_ids = []
if self.USER_ID_HDR in r.headers:
user_ids = json.loads(r.headers[self.USER_ID_HDR])
return r
update_inventario

import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
# Configurare
datastoreName = "Inventory"
# Elenca le chiavi per un sottoinsieme di utenti (potrebbe essere necessario utilizzare il prossimoPageCursor per visualizzare altre entradi)
keys = DatastoresApi.list_entries(datastoreName)
print(keys.content)
# Leggi l'inventario per ogni utente
for x in range(5):
updatedObjectKey = "User_"+str(x+1)
value = DatastoresApi.get_entry(datastoreName, updatedObjectKey)
# cambia il tipo di risposta a una stringa
updatedValue = value.json()
print(updatedObjectKey + " has "+str(updatedValue)+" gems in their inventory")
# Aggiorna la valuta di ciascun utente di 10
for x in range(5):
updatedObjectKey = "User_"+str(x+1)
value = DatastoresApi.increment_entry(datastoreName, updatedObjectKey, 10)
# cambia il tipo di risposta a una stringa
updatedValue = value.json()
print(updatedObjectKey + " now has "+str(updatedValue)+" robux in their inventory")

Per testare, imposta la variabile ambientale API_KEY e esegui il file update_inventory :


export API_KEY=... \
python update_inventory

Classifica persistente esterna

Questa sezione guida attraverso un esempio concreto di creazione di una leaderboard persistente esterna in Python, in cui puoi elencare e leggere le informazioni degli utenti memorizzate negli archivi di dati in ordine, fare modifiche e poi pubblicare su un sito Web esterno per la Promozione.

Per questo esempio, supponi Seguendo:

  • Il codice di esempio crea una lista predefinita di nomi utente per lo scopo della dimostrazione. Per la tua applicazione, dovresti usare la lista di utenti attuali nella tua esperienza.

  • Il codice di esempio aggiunge 50 punti a ciascun utente che si unisce all'esperienza per lo scopo della dimostrazione. Per la tua applicazione, dovresti definire la regola in base al design dell'esperienza.

Da un Livelloelevato, puoi creare la tua app Python aggiungendo autorizzazioni API e quindi aggiungendo script.

Aggiungere autorizzazioni API per i magazzini di dati ordinati

L'esempio app richiede quattro metodi per ottenere le sue funzionalità: List Create 0> Update0> 1> 2> Increment2> e 5> 6> Increment5> , quindi devi aggiungere le seguenti autorizzazioni API:

  • Leggi per il metodo list .
  • Scrivi per Create , Update , e 0> Increment0> metodi.

Quando creare una chiave API per questo esempio, assicurati di eseguire le seguenti operazioni:

  1. Dal menu Seleziona sistema API nella sezione Accesso ai permessi , seleziona Negozi di dati ordinati .

  2. Aggiungi autorizzazioni alle operazioni API per leggere e scrivere i magazzini di dati ordinati nell'esperienza target.

    1. Fai clic sulla Seleziona Esperienza per Aggiungere dropdown e seleziona l'esperienza target.
    2. Nelle Operazioni sull'Esperienza, espandi il menu a discesa per selezionare Leggi e Scrivi operazioni.
  3. Nella sezione Sicurezza, imposta esplicitamente l'accesso IP all'area utilizzando notazione CIDR , e imposta una data di scadenza esplicita in modo che la tua chiave smetti di funzionare dopo quel giorno. Per questo esempio, se vuoi prima eseguire un test locale, puoi rimuovere la restrizione IP impostandola su 0.0.0.0/

Aggiungere script per la classifica

Dopo aver creato la chiave API con i permessi richiesti per l'esempio applicazione, è necessario aggiungere script Python per eseguire le funzionalità dell'app.

Il file ordered_data_stores.py mostra come defin

ordinato_data_stores.py

import hashlib
import requests
import json
class DataStores:
def __init__(self, config_file):
with open(config_file) as f:
self._config = json.load(f)
def _H(self):
return { 'x-api-key' : self._config["api_key"], 'Content-Type': 'application/json'}
def _get_url(self, path_format: str):
return f"{self._config['base_url']}/{path_format.format(self._config['universe_id'])}"
def list(self, datastore, scope, pageSize = 10, orderBy = "", filter = "", exclusiveStartKey = ""):
self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries"
headers = { 'x-api-key' : self._config["api_key"] }
r = requests.get(self._objects_url, headers=headers, params={"max_page_size": pageSize, "order_by" : orderBy, "filter" : filter, "page_token" : ""})
return r
def create(self, datastore, scope, entry, data):
self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries"
headers = self._H()
payload = json.dumps({
"value": 11
})
return requests.post(self._objects_url, params = {"id": entry }, data=payload, headers=headers)
def increment(self, datastore, scope, entry, incrementBy):
self._objects_url = self._config['api_key_url']+"universes/"+self._config["universe_id"]+"/orderedDataStores/"+datastore+"/scopes/"+scope+"/entries/"+entry+":increment"
headers = { 'x-api-key' : self._config["api_key"] }
payload = json.dumps({
"amount": 1
})
r = requests.post(self._objects_url, headers=headers, data=payload)
return r
classifica.py

import leaderboardEndpoints
# inserisci file di configurazione qui
datastores = leaderboardEndpoints.DataStores("config.json")
# Variabili
orderedDataStore = "PlayerScores"
scope = "global"
entryNames = ["Ragdoll", "Balinese", "Tabby", "Siamese"]
# Crea un'area e assegnati 50 punti per ogni nuovo giocatore che si unisce al Gioco
for x in range(len(entryNames)):
r = datastores.create(orderedDataStore, scope, entryNames[x], 50)
# Mostra i punteggi dei giocatori
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)
# Aumenta il punteggio dei primi giocatori per vincere il Gioco
datastores.increment(orderedDataStore, scope, entryNames[0], 100)
# Aumenta tutti i punteggi dei giocatori per partecipare al Gioco
for x in range(len(entryNames)):
datastores.increment(orderedDataStore, scope, entryNames[x], 10)
# Mostra la classifica con le punteggi aggiornati
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)
configurazione

{
"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 :


export API_KEY=... \
python leaderboard

Dopo aver completato il test, puoi pubblicare o incollare la classifica sui siti Web al di fuori di Roblox per raggiungere più persone.