Guide d'utilisation pour les magasins de données

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

En plus d'accéder à stores de données à l'aide de Lua DataStoreService dans Studio ou les serveurs en direct, vous pouvez utiliser les API Open Cloud pour accéder et utiliser les données standard et 1>les magasins de données commandés1> depuis les scripts et les outils externes avec un contrôle d'accès et de sécurité granulaire.

Utilisation

Vous pouvez améliorer plusieurs zones de votre flux de travail en accédant à vos données avec ces API, telles que :

  • Portail de support client : Les magasins de données sont utiles pour stocker les ressources utilisateur persistantes, telles que les articles dans les inventaires des utilisateurs ou les points de compétence. Parfois, vous devez mettre à jour ces ressources pour le Service client. Au lieu d'utiliser Studio ou de rejoindre une expérience manuellement, vous pouvez construire une application Web pour permettre à vos agents de service client directement de gérer les demandes de support client, telles que la visualisation et la modification des inventaires utilisateurs et l'ém

  • Tableau de bord LiveOps : Vous pouvez construire un tableau de bord LiveOps en utilisant les API pour améliorer l'efficacité des opérations en direct, telles que la planification d'événements en expérience. Vous pouvez codez un événement à l'avance, cacher-le sous un drapeau de fonctionnalité en tant que partie des données de configuration dans un data boutique, et définir un temps pour retourner le drapeau pour publier l'événement. Vos serveurs d'exp

  • Classement d'affichage external : Pour promouvoir vos expériences en dehors de Roblox, vous pouvez extraire les informations de votre expérience, telles que le classement d'une course, en temps réel et les afficher sur un site Web externe. Vous pouvez accorder l'accès seulement aux magasins de données commandés pour que le site Web demande périodiquement les derniers données via HTTP et mette à jour la page Web.

  • Automatisation de la migration des données : Les données peuvent changer ou se mettre à jour à mesure que votre expérience évolue, telles que la mise à niveau des schémas de données pour prendre en charge de nouvelles fonctionnalités. Pour éviter de perdre les données de l'utilisateur existantes, vous devez parfois migrer vos magasins de données de l'ancien schéma à un nouveau schéma. Vous pouvez écrire un script externe

Différences avec l'API Lua

Bien que les API Open Cloud ressemblent à la classe Lua DataStoreService, il y a quelques exigences différentes à prendre en compte :

  • ID de l'univers et nom du stock de données : contrairement à l'API Lua, les API Open Cloud sont stateless et peuvent venir de n'importe où, vous devez donc toujours fournir le identifiant de l'univers , l'identifiant unique de votre expérience, et le nom du stock nom lors de l'envoi des demandes. Pour plus d'informations sur la façon d'obtenir un ID d'univers, voir 0>

  • Permissions séparées pour la création et la mise à jour : La API Lua crée de nouvelles entrées si elles n'existent pas lorsque vous appelez DataStore:SetAsync() , mais les méthodes Open Cloud pour la création et la mise à jour des entrées sont séparées. Les permissions séparées peuvent être plus sûres et plus flexibles dans certaines situations. Par exemple, vous pouvez créer un outil de support client qui peut modifier le

  • Normalisation des données série : Tous les points d'extrémité du cloud ouvert nécessitent que vous normalisiez tous les données avant le transport réseau. La normalisation signifie de convertir un objet en cette chaîne, et la dé serialisation est son inversion (converser un chaîne en un objet). La normisation Lua normalise et dé serialise automatiquement le contenu de l'entrée, mais pour le cloud ouvert, vous devez générer ou analyser vos données d'entrée avec JSON par posséder.

Permissions de sécurité

Les magasins de données stockent généralement des informations sensibles, telles que les profils d'utilisateur et la monnaie virtuelle. Pour maintenir la sécurité, chaque magasin de données Open Cloud a des autorisations correspondantes que vous devez ajouter à votre clé API, telles que la permission List Keys pour le magasin de données de liste. Si vous n'ajoutez pas les autorisations correspondantes, votre appel

Lorsque vous configurez vos clés d'API, vous pouvez définir des permissions granulaires, telles que la lu, l'écriture et la liste d'entrée, pour chaque magasin de données dans une expérience spécifique, ou vous pouvez donner une clé pour lire ou écrire tous les magasins de données dans une expérience. Vous pouvez également limiter l'accès à un sous-ensemble de magasins de données nécessaires pour votre outil au lieu d'ex

Outils de construction

Vous pouvez utiliser la langue de votre choix pour construire des outils avec Ouvrir des API du cloud pour les magasins de données pour remplir vos besoins d'opération. Les exemples suivants montrent les processus de construction d'un portail d'inventaire de l'utilisateur dans le Python avec des magasins de données standard et un Externe persistante leaderboard en utilisant des magasins de données ordonnés.

Portail de support de l'inventaire de l'utilisateur

Cette section fournit un exemple concret de construction d'un portail d'assistance de l'inventaire d'un utilisateur en Python, dans lequel vous pouvez listner et lire un sous-ensemble de l'inventaire de vos utilisateurs, faire des modifications et puis mettre à jour dans la boutique de données d'une expérience.

Pour cet exemple, supposons suivre:

  • Le nom du magasin de données qui stocke l'inventaire de l'utilisateur est Inventory .

  • Le schéma de données pour chaque entrée de données est "userId": {"currency": number, "weapon": string, "level": number} . La clé est simplement userId .

  • Le script Python liste un sous-ensemble d'inventaires d'utilisateurs basé sur les préfixes, augmente leur monnaie virtuelle de 10 pour une promotion, et met à jour les données.

À partir d'un niveau élevé, vous pouvez construire votre application Python en ajoutant des autorisations clé API et en ajoutant ensuite des scripts.

Ajouter des autorisations d'API pour les magasins de données

Lors de la création d'une clé d'API pour cet exemple, assurez-vous de faire les paramètres suivants :

  1. Dans le menu sélectionner le système d'API dans la section accès aux permissions , sélectionnez stores d'univers .

  2. (Facultatif) Dans la section Stockages de données , sélectionnez les opérations API pour les données spécifiques.

    1. Activer les opérations de données spécifiques activer/désactiver. Par défaut, cinq magasins de données chargerautomatiquement, mais vous pouvez ajouter des magasins de données supplémentaires via le bouton Ajouter un magasin de données à la liste.
    2. Sélectionnez la flèche déroulante à côté du nom d'un boutiquede données, puis sélectionnez les opérations API que vous souhaitez que le magasin de données ait accès.
  3. Sélectionnez les opérations API pour l'ensemble de l'expérience.

    1. Cliquez sur le sélectionner l'expérience à ajouter menu déroulant et sélectionnez une expérience.
    2. Dans l' expérience d'opérations, cliquez sur la flèche déroulante et sélectionnez les opérations que vous souhaitez ajouter à votre API. Ce exemple sélectionne Lire l'entrée, Mettre à jour l'entrée et 2> Lister les entrées clés2> pour l'ensemble de l'expérience.
  4. Dans la section Sécurité, définissez explicitement l'accès IP à la clé en utilisant la norme CIDR, et définissez une date d'expiration explicite afin que votre clé arrête automatiquement de fonctionner après cette date. Pour cet exemple, si vous prévoyez d'effectuer un test local d'abord, vous pouvez supprimer la restreinte IP en la définissant sur

Ajouter des scripts pour le portail d'assistance de l'inventaire de l'utilisateur

Après avoir créé la clé API avec les permissions requises pour l'exemple d'application, vous devez ajouter des scripts Python pour exécuter les fonctionnalités de l'application. Le fichier data_stores_methods.py montre comment

data_stores_méthodes.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 clé API est enregistrée dans une variable d'environnement appelée « 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}, got {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_inventory

import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
# Configurer
datastoreName = "Inventory"
# Listez les clés d'un sous-ensemble d'utilisateurs (vous pourriez avoir besoin d'utiliser le nextPageCursor pour afficher d'autres entrées)
keys = DatastoresApi.list_entries(datastoreName)
print(keys.content)
# Lire l'inventaire pour chaque utilisateur
for x in range(5):
updatedObjectKey = "User_"+str(x+1)
value = DatastoresApi.get_entry(datastoreName, updatedObjectKey)
# modifier le type de réponse pour une chaîne
updatedValue = value.json()
print(updatedObjectKey + " has "+str(updatedValue)+" gems in their inventory")
# Mettez à jour la monnaie de chaque utilisateur de 10
for x in range(5):
updatedObjectKey = "User_"+str(x+1)
value = DatastoresApi.increment_entry(datastoreName, updatedObjectKey, 10)
# modifier le type de réponse pour une chaîne
updatedValue = value.json()
print(updatedObjectKey + " now has "+str(updatedValue)+" robux in their inventory")

Pour tester, définissez la variable d'environnement API_KEY et exécutez le fichier update_inventory :


export API_KEY=... \
python update_inventory

Classement persistant externe

Cette section traite d'un exemple concret de création d'une liste de leaders persistants externes dans Python, dans laquelle vous pouvez listner et lire les informations de vos utilisateurs stockées dans des magasins de données ordonnés, faire des modifications et puis publier sur un site Web externe pour la promotion.

Pour cet exemple, supposons suivre:

  • L'exemple de code crée une liste de noms d'utilisateur prédéfinie pour le but de la démonstration. Pour votre propre application, vous devriez utiliser la liste des utilisateurs actuels dans votre expérience.

  • L'exemple de code ajoute 50 points à chaque utilisateur qui rejoint l'expérience à des fins de démonstration. Pour votre propre application, vous devez définir la règle en fonction du design de votre expérience.

À partir d'un niveau élevé, vous pouvez construire votre application Python en ajoutant des autorisations clé API et en ajoutant ensuite des scripts.

Ajouter des autorisations d'API pour les magasins de données commandés

L'application d'exemple nécessite quatre méthodes pour atteindre ses fonctionnalités : List Create 0> Update0> 1> 2> Increment2> et 5> 5> Increment5>, vous devez donc ajouter les permissions de clé d'API suivantes :

  • Lire pour la méthode list.
  • Écrivez pour Create , Update et 0> Increment0> méthodes.

Lors de la création d'une clé d'API pour cet exemple, assurez-vous de effectuer les opérations suivantes :

  1. Dans le Menu sélectionner le système d'API dans la section Accès aux permissions , sélectionnez Stockage de données commandé .

  2. Ajoutez des permissions aux opérations de l'API pour lire et écrire des magasins de données ordonnés dans l'expérience cible.

    1. Cliquez sur le sélectionner l'expérience à ajouter menu déroulant et sélectionnez l'expérience cible.
    2. Dans l' Expérience Opérations, élargissez le menu déroulant pour sélectionner Lire et Écrire opérations.
  3. Dans la section Sécurité, définissez explicitement l'accès IP à la clé en utilisant la norme CIDR, et définissez une date d'expiration explicite afin que votre clé arrête automatiquement de fonctionner après cette date. Pour cet exemple, si vous prévoyez d'effectuer un test local d'abord, vous pouvez supprimer la restreinte IP en la définissant sur

Ajouter des scripts pour le classement

Après avoir créé la clé API avec les permissions requises pour l'exemple d'application, vous devez ajouter des scripts Python pour exécuter les fonctionnalités de l'application.

Le classementsordered_data_stores.py montre comment

订购_数据_存储.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
classements.py

import leaderboardEndpoints
# saisir le fichier de configuration ici
datastores = leaderboardEndpoints.DataStores("config.json")
# Variables
orderedDataStore = "PlayerScores"
scope = "global"
entryNames = ["Ragdoll", "Balinese", "Tabby", "Siamese"]
# Créez une entrée et donnez à chaque nouveau joueur 50 points pour avoir rejoint le jeu
for x in range(len(entryNames)):
r = datastores.create(orderedDataStore, scope, entryNames[x], 50)
# Afficher les scores des joueurs
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)
# Augmenter le score des premiers joueurs pour gagner le jeu
datastores.increment(orderedDataStore, scope, entryNames[0], 100)
# Augmentez tous les scores des joueurs pour participer au jeu
for x in range(len(entryNames)):
datastores.increment(orderedDataStore, scope, entryNames[x], 10)
# Affichez le classement avec les scores mis à jour
playerScores = datastores.list(orderedDataStore, scope)
print(playerScores.content)
configurer

{
"universe_id": "",
"api_key_url": "https://apis.roblox.com/datastores/ipped-v1/",
"api_key": ""
}

Pour tester, définissez la variable d'environnement API_KEY et exécutez le fichier leaderboard :


export API_KEY=... \
python leaderboard

Après avoir terminé le test, vous pouvez publier ou intégrer le classement sur des sites Web en dehors de Roblox pour plus de portée.