En plus d'accéder à des magasins de données en utilisant l'API du moteur ( DataStoreService ) dans Studio ou sur des serveurs en direct, vous pouvez utiliser les API du cloud ouvertes pour accéder et utiliser des magasins de données standard et commandés à partir d' scripts et d'outils externes avec un accès et une sécurité de contrôle granulaire.
Les API du cloud ouvertes pour les magasins de données commandés sont des API bêta qui pourraient faire l'objet de modifications pour les futures versions.
Utilisation
Vous pouvez améliorer plusieurs domaines de votre flux de travail en accédant à vos données avec ces API, comme :
Portail de support client : les magasins de données sont utiles pour stocker des ressources utilisateur persistantes, telles que des articles dans les inventaires des utilisateurs ou des points de compétence.Parfois, vous devez mettre à jour ces ressources pour le Service client.Plutôt que d'utiliser Studio ou de rejoindre une expérience manuellement, vous pouvez construire une application Web pour permettre à vos agents de service client de gérer directement les demandes de support client, telles que la visualisation et la modification des inventaires d'utilisateurs et l'émission de remboursements.
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.Par exemple, vous pouvez programmer un événement à l'avance, le cacher sous un drapeau de fonctionnalité comme partie des données de configuration dans un boutiquede données, et définir une heure pour faire basculer le drapeau pour publier l'événement.Vos serveurs d'expérience peuvent détecter ce changement en lisant le drapeau pour lancer l'événement.
Classement externe : Pour promouvoir vos expériences en dehors de Roblox, vous pouvez récupérer 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 un accès en lecture seule à vos magasins de données commandés pour que le site Web demande périodiquement les dernières données via HTTP et mette à jour la page Web.
Automatisation de la migration des données : les données peuvent changer ou être mises à jour au fur et à mesure que votre expérience évolue, comme la mise à niveau des schémas de données pour prendre en charge de nouvelles fonctionnalités.Pour éviter de perdre les données utilisateur existantes, vous devez parfois migrer vos magasins de données du schéma ancien vers un nouveau.Vous pouvez écrire un script externe qui lit chaque entrée à partir des magasins de données actuels, mappe les données au nouveau schéma et écrit l'entrée de retour dans un nouveau magasin de données pour automatiser la migration des données.
Différences avec l'API du moteur
Bien que les API du cloud ouvertes soient similaires à DataStoreService, il y a quelques différences clés :
ID de l'univers et nom du magasin de données : Contrairement à l'API du moteur, les API du cloud ouvertes sont sans état et peuvent provenir de n'importe où, vous devez donc toujours fournir l'ID de l'univers , l'identifiant unique de votre expérience, et le nom du magasin de données lors de l'envoi des demandes.Pour plus d'informations sur la façon d'obtenir un ID d'univers, voir ID d'univers.
Permissions séparées pour la création et la mise à jour : l'API du moteur crée de nouvelles entrées si elles n'existent pas lorsque vous appelez DataStore:SetAsync() , mais les méthodes d'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 profil d'un utilisateur existant, mais ne peut pas créer le profil d'un nouvel utilisateur.
Sérialisation des données : Tous les points d'extrémité du cloud ouvert vous obligent à sérialiser toutes les données avant le transport réseau.La sérialisation signifie convertir un objet en chaîne.La déserialisation est l'inverse ( convertir une chaîne en objet ).L'API du moteur sérialise et déserialize le contenu d'entrée automatiquement, mais pour Open Cloud, vous devez générer ou parser vos données d'entrée avec JSON posséder.
Permissions de sécurité
Les magasins de données stockent souvent des informations sensibles, telles que les profils d'utilisateur et la monnaie virtuelle.Pour maintenir la sécurité, chaque Open Cloud API a les permissions correspondantes que vous devez ajouter à votre clé API, telles que l'autorisation List Keys pour l'API de listage.Si vous n'ajoutez pas les permissions requises, votre appel d'API renvoie une erreur.Pour les permissions spécifiques requises pour chaque opération, voir la référence de l'API de standard et magasins de données commandés.
Lorsque vous configurez vos clés API , vous pouvez définir des permissions granulaires, telles que la lu, l'écriture et l'ajout d'une 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'exposer tous les magasins de données.Cela atténue l'impact en cas de fuite de votre clé.
Outils de construction
Vous pouvez utiliser la langue de votre choix pour construire des outils avec les API ouvertes du cloud pour les magasins de données pour répondre à vos besoins d'opération.Les exemples suivants traversent les processus de construction d'un portail de soutien à l'inventaire des utilisateurs en Python avec des magasins de données standard et un leaderboard persistant externes en utilisant des magasins de données ordonnés.
Portail de support de l'inventaire des utilisateurs
Cette section fournit un exemple concret de construction d'un portail de support de l'inventaire des utilisateurs en Python, dans lequel vous pouvez lister et lire un sous-ensemble de l'inventaire de vos utilisateurs, faire des modifications, puis mettre à jour le boutiquede données d'une expérience.
Pour cet exemple, supposez ce qui 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 des préfixes, augmente leur monnaie virtuelle de 10 pour une promotion et met à jour les données.
D'un niveau élevé, vous pouvez construire votre application Python en ajoutant des permissions de clé API et en ajoutant ensuite des scripts.
Ajouter des permissions de clé API pour les magasins de données
Lors de la création d'une clé API pour cet exemple, assurez-vous d'effectuer les paramètres suivants :
Dans le menu Sélection du système d'API de la section Accès aux données universelles , sélectionnez magasins de données universels .
(Facultatif) Dans la section magasins de données , sélectionnez les opérations API pour des magasins de données spécifiques.
- Activez l'option opérations de stockage de données spécifiques .Par défaut, cinq magasins de données se chargerautomatiquement, mais vous pouvez ajouter des magasins de données supplémentaires via le bouton + Ajouter magasin de données à la liste .
- Sélectionnez la flèche déroulante à côté du nom d'un boutiquede données, puis sélectionnez les opérations API auxquelles le magasin de données doit avoir accès.
Sélectionnez les opérations API pour l'ensemble de l'expérience.
- Cliquez sur le sélectionnez l'expérience à ajouter menu déroulant et sélectionnez une expérience.
- Dans les opérations d'expérience , cliquez sur la flèche déroulante et sélectionnez les opérations que vous souhaitez ajouter à votre API.Cet exemple sélectionne Lire l'entrée , mettre à jour l'entrée , et clés d'entrée de liste pour toute l'expérience.
Vous n'avez pas besoin de l'autorisation de clé API create entries puisque l'application ne crée pas d'inventaires d'utilisateurs nouveaux.
Dans la section sécurité , définissez explicitement l'accès IP à la clé en utilisant la notation CIDR, et définissez une date d'expiration explicite afin que votre clé cesse de fonctionner après cette date.Pour cet exemple, si vous prévoyez de faire des tests locaux en premier, vous pouvez supprimer la restriction IP en la réglant sur 0.0.0.0/0 et la laisser expirer dans 30 jours .
Ajouter des scripts pour le portail de support de l'inventaire de l'utilisateur
Après avoir créé la clé API avec les permissions requises pour l'application d'exemple, vous devez ajouter du code JavaScript pour exécuter les fonctionnalités de l'application.Le fichier data_stores_methods.js montre comment définir List Entries , Get Entry , et Increment Entry méthodes.Le fichier update_inventory.js utilise les méthodes définies pour lister un sous-ensemble des inventaires d'utilisateurs, augmenter la devise virtuelle pour chaque utilisateur et mettre à jour les données.
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`
);
});
}
Pour tester, définissez la variable d'environnement API_KEY et exécutez le fichier JavaScript :
classementspersistant externe
Cette section traverse un exemple concret de création d'un leaderboard persistant externe en Python, dans lequel vous pouvez lister et lire les informations de vos utilisateurs stockées dans des magasins de données ordonnés, faire des modifications, puis publier sur un site Web externe pour la promotion.
Pour cet exemple, supposez ce qui suivre:
L'échantillon de code crée une liste prédéfinie des noms d'utilisateur pour le but de la démonstration.Pour votre propre application, vous devez utiliser la liste des utilisateurs réels dans votre expérience.
L'échantillon de code ajoute 50 points à chaque utilisateur rejoignant 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.
D'un niveau élevé, vous pouvez construire votre application Python en ajoutant des permissions de clé API et en ajoutant ensuite des scripts.
Ajouter des permissions de clé API pour les magasins de données commandés
L'application d'exemple nécessite quatre méthodes pour obtenir ses fonctionnalités : List , Create , Update et Increment , vous devez donc ajouter les permissions de clé API suivantes :
- Lire pour la méthode list.
- Écrire pour Create, Update et Increment méthodes.
Lors de la création d'une clé API pour cet exemple, assurez-vous d'effectuer les opérations suivantes :
Dans le menu Sélection du système d'API dans la section Accès aux données commandées , sélectionnez magasins de données ordonnés .
Ajouter des permissions d'opérations d'API pour lire et écrire des magasins de données ordonnés dans l'expérience cible.
- Cliquez sur le sélectionnez l'expérience à ajouter menu déroulant et sélectionnez l'expérience cible.
- Dans les opérations d'expérience , étendez le menu déroulant pour sélectionner les opérations lire et écrire .
Dans la section sécurité , définissez explicitement l'accès IP à la clé en utilisant la notation CIDR, et définissez une date d'expiration explicite afin que votre clé cesse de fonctionner après cette date.Pour cet exemple, si vous prévoyez de faire des tests locaux en premier, vous pouvez supprimer la restriction IP en la réglant sur 0.0.0.0/0 et la laisser expirer dans 30 jours .
Ajouter des scripts pour le classements
Après avoir créé la clé API avec les permissions requises pour l'application d'exemple, vous devez ajouter du code JavaScript pour exécuter les fonctionnalités de l'application.
Le fichier ordered_data_stores.js montre comment définir List , Create , Update , et Increment méthodes.Le fichier leaderboard.js utilise les méthodes définies pour créer des entrées d'utilisateurs dans des magasins de données ordonnés, afficher des scores, augmenter les scores des utilisateurs gagnants et mettre à jour le classements.Le fichier leaderboard.js importe également un fichier config.json pour configurer l'ID de l'univers, le domaine de l'API et votre clé 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/ordonné-v1/",
"api_key": ""
}
Pour tester, définissez la variable d'environnement API_KEY et exécutez le fichier leaderboard.js :
Après avoir terminé les tests, vous pouvez publier ou intégrer le classement à des sites Web en dehors de Roblox pour plus de portée.