Además de acceder a almacenamientos de datos usando la API del motor ( ) en Studio o servidores en vivo, puedes usar las API de nube abierta para acceder y utilizar almacenamientos de datos estándar y ordenados desde scripts y herramientas externos con acceso y control de seguridad granulares.
Las API de nube abiertas para almacenes de datos solicitados son API beta que pueden estar sujetas a cambios para futuras versiones.
Uso
Puedes mejorar varias áreas de tu flujo de trabajo accediendo a tus datos con estas API, como:
Portal de soporte al cliente : Los almacenes de datos son útiles para almacenar recursos persistentes del usuario, como artículos en inventarios de usuarios o puntos de habilidad.A veces necesitas actualizar estos recursos para el Soporteal cliente.En lugar de usar Studio o unirse a una experiencia manualmente, puede crear una aplicación web para permitir que sus agentes de servicio al cliente manejen directamente las solicitudes de soporte al cliente, como ver y modificar inventarios de usuarios y emitir reembolsos.
Panel de LiveOps : Puedes construir un panel de LiveOps utilizando las API para mejorar la eficiencia de las operaciones en vivo.Por ejemplo, puedes programar un evento con antelación, ocultarlo bajo una bandera de características como parte de los datos de configuración en un tiendade datos y establecer un tiempo para cambiar la bandera para publicar el evento.Los servidores de experiencia pueden detectar este cambio leyendo la bandera para lanzar el evento.
Tabla de clasificación externa : Para promover tus experiencias fuera de Roblox, puedes recuperar la información de tu experiencia, como la tabla de clasificación de una carrera, en tiempo real y mostrarla en un sitio web externo.Puedes conceder acceso de solo lectura a tus almacenes de datos solicitados para que el sitio web solicite periódicamente los últimos datos a través de HTTP y actualice la página web.
Automatización de migración de datos : Los datos pueden cambiar o actualizarse a medida que evoluciona tu experiencia, como actualizar esquemas de datos para acomodar nuevas funciones.Para evitar perder los datos de usuario existentes, a veces necesitas migrar tus almacenes de datos desde el esquema antiguo a uno nuevo.Puedes escribir un script externo que lea cada entrada de los almacenes de datos actuales, mapee los datos al nuevo esquema y escriba la entrada de vuelta a un nuevo almacén de datos para automatizar la migración de datos.
Diferencias con la API del motor
Aunque las API de nube abierta son similares a DataStoreService, hay algunas diferencias clave:
ID del universo y nombre del almacén de datos : A diferencia de la API del motor, las API de nube abierta son estatales y pueden provenir de cualquier lugar, por lo que siempre debe proporcionar el ID del universo , el identificador único de su experiencia, y el nombre del almacén de datos cuando envíe las solicitudes.Para obtener más información sobre cómo obtener una ID de universo, vea ID de universo.
Permisos separados para crear y actualizar : La API de Motor crea nuevas entradas si no existen cuando llamas DataStore:SetAsync() , pero los métodos de nube abierta para crear y actualizar entradas son separados.Las autorizaciones separadas pueden ser más seguras y más flexibles en ciertas situaciones.Por ejemplo, puedes crear una herramienta de soporte al cliente que pueda editar el perfil de un usuario existente, pero no pueda crear el perfil de un nuevo usuario.
Serialización de datos : Todos los puntos finales de nube abierta requieren que serialices todos los datos antes del transporte de red.La serialización significa convertir un objeto en una cadena.La deserialización es lo opuesto (convertir una cadena en un objeto).La API del motor serializa y deserializa el contenido de la entrada automáticamente, pero para Open Cloud, necesitas generar o parsar tus datos de entrada con JSON por tu en posesión.
Permisos de seguridad
Los almacenes de datos a menudo almacenan información sensible, como perfiles de usuario y moneda virtual.Para mantener la seguridad, cada Open Cloud API tiene permisos correspondientes que debe agregar a su clave API, como el permiso List Keys para la API de listado.Si no agregas las permisos requeridos, tu llamada de API devuelve un error.Para los permisos específicos que se requieren para cada operación, consulte la referencia de la API de estándar y tiendas de datos ordenadas.
Cuando configures tus claves de API, puedes establecer permisos granulares, como leído, escritura y lista de entradas, para cada almacén de datos dentro de una experiencia específica, o puedes dar una clave para leer o escribir todos los almacenes de datos dentro de una experiencia.También puede limitar el acceso a un subconjunto de almacenes de datos necesarios para su herramienta en lugar de exponer todos los almacenes de datos.Esto mitiga el impacto en caso de que se filtre tu clave.
Herramientas de construcción
Puedes usar el idioma de tu elección para construir herramientas con API abiertas de nube para almacenamientos de datos para cumplir con tus necesidades de operación.Los siguientes ejemplos muestran los procesos de construcción de un portal de soporte de inventario de usuarios en Python con almacenes de datos estándar y una tabla de clasificación externa persistente usando almacenes de datos ordenados.
Portal de soporte de inventario de usuario
Esta sección proporciona un ejemplo concreto de cómo construir un portal de soporte de inventario de usuario en Python, en el que puedes enumerar y leer un subconjunto del inventario de tus usuarios, hacer ediciones y luego actualizar de vuelta a la tienda de datos de una experiencia.
Para este ejemplo, suponga lo siguiendo:
El nombre del almacén de datos que almacena el inventario del usuario es Inventory .
El esquema de datos para cada entrada de datos es "userId": {"currency": number, "weapon": string, "level": number} . La clave es solo userId .
El script de Python lista un subconjunto de inventarios de usuarios basados en prefijos, aumenta su moneda virtual en 10 para una promoción y actualiza los datos.
Desde un nivel alto, puedes construir tu aplicación de Python agregando permisos de clave de API y luego agregando scripts.
Añadir permisos de clave de API para almacenes de datos
Cuando creas una clave de API para este ejemplo, asegúrate de realizar las siguientes configuraciones:
Desde el menú Seleccionar sistema de API en la sección Permisos de acceso , seleccione universos de almacenamiento de datos .
(Opcional) En la sección Almacenes de datos , seleccione operaciones de API para almacenes de datos específicos.
- Habilita la opción Operaciones específicas del almacén de datos alternar/activar.Por defecto, cinco almacenes de datos se cargarautomáticamente, pero puedes agregar almacenes de datos adicionales a través del botón + Añadir almacén de datos a la lista .
- Seleccione la flecha desplegable junto al nombre de un tiendade datos, luego seleccione las operaciones de API a las que desea que tenga acceso el almacén de datos.
Seleccione operaciones de API para toda la experiencia.
- Haga clic en el Seleccionar experiencia para agregar cuadro desplegable y seleccione una experiencia.
- En las Operaciones de experiencia , haz clic en la flecha desplegable y selecciona las operaciones que quieres agregar a tu API.Este ejemplo selecciona Leer entrada , actualizar entrada , y claves de lista de entrada para toda la experiencia.
No necesitas el permiso de la clave de API create entries ya que la aplicación no crea inventarios de usuarios nuevos.
En la sección Seguridad , establezca explícitamente el acceso IP a la clave usando notación CIDR, y establezca una fecha de expiración explícita para que su clave deje de funcionar después de esa fecha.Para este ejemplo, si planeas hacer primero pruebas locales, puedes eliminar la restricción de IP estableciéndola en 0.0.0.0/0 y dejándola expirar en 30 días .
Añadir scripts para el portal de soporte de inventario de usuarios
Después de crear la clave de API con las autorizaciones requeridas para la aplicación (app)de ejemplo, debe agregar código JavaScript para realizar las funcionalidades de la aplicación.El archivo muestra cómo definir , y métodos.El archivo update_inventory.js usa los métodos definidos para enumerar un subconjunto de inventarios de usuarios, aumentar la moneda virtual para cada usuario y actualizar los datos.
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`
);
});
}
Para probar, establece la variable de entorno API_KEY y ejecuta el archivo de JavaScript:
Tabla de clasificación persistente externa
Esta sección recorre un ejemplo concreto de creación de una tabla de clasificación persistente externa en Python, en la que puedes enumerar y leer la información de tus usuarios almacenada en almacenes de datos ordenados, hacer ediciones y luego publicar en un sitio web externo para promoción.
Para este ejemplo, suponga lo siguiendo:
El ejemplo de código crea una lista predefinida de nombres de usuario para el propósito de demostración.Para tu propia aplicación, deberías usar la lista de usuarios reales en tu experiencia.
El ejemplo de código agrega 50 puntos a cada usuario que se una a la experiencia con fines de demostración.Para tu propia aplicación, deberías definir la regla basada en el diseño de tu experiencia.
Desde un nivel alto, puedes construir tu aplicación de Python agregando permisos de clave de API y luego agregando scripts.
Añadir permisos de clave de API para almacenes de datos ordenados
La aplicación de ejemplo requiere cuatro métodos para lograr sus funcionalidades: List , Create , Update y Increment , por lo que necesitas agregar las siguientes permisos de clave API:
- Leer para el método list.
- Escriba para Create , Update y Increment métodos.
Cuando creas una clave de API para este ejemplo, asegúrate de realizar las siguientes operaciones:
Desde el menú Seleccionar sistema de API en la sección Permisos de acceso , seleccione Almacenes de datos ordenados .
Añade permisos de operaciones de API para leer y escribir almacenes de datos ordenados en la experiencia objetivo.
- Haga clic en el Seleccionar experiencia para agregar cuadro desplegable y seleccione la experiencia objetivo.
- En las Operaciones de experiencia , expanda el desplegable para seleccionar las operaciones Leer y Escribir .
En la sección Seguridad , establezca explícitamente el acceso IP a la clave usando notación CIDR, y establezca una fecha de expiración explícita para que su clave deje de funcionar después de esa fecha.Para este ejemplo, si planeas hacer primero pruebas locales, puedes eliminar la restricción de IP estableciéndola en 0.0.0.0/0 y dejándola expirar en 30 días .
Añadir scripts para la tabla de clasificación
Después de crear la clave de API con las autorizaciones requeridas para la aplicación (app)de ejemplo, debe agregar código JavaScript para realizar las funcionalidades de la aplicación.
El archivo muestra cómo definir , , y métodos.El archivo leaderboard.js usa los métodos definidos para crear entradas de usuarios en almacenes de datos ordenados, mostrar puntuaciones, incrementar puntuaciones de usuarios ganadores y actualizar la tabla de clasificación.El archivo leaderboard.js también importa un archivo config.json para configurar la identificación del universo, el dominio de API y la clave de 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);
});
configuración
{
"universe_id": "",
"api_key_url": "https://apis.roblox.com/datastores/ordenados-v1/",
"api_key": ""
}
Para probar, establece la variable de entorno API_KEY y ejecuta el archivo leaderboard.js:
Una vez completada la prueba, puedes publicar o incrustar la tabla de clasificación en sitios web fuera de Roblox para obtener más alcance.