Além de acessar bancos de dados usando a API do Motor ( DataStoreService ) no Studio ou em servidores ao vivo, você pode usar as APIs da Nuvem Aberta para acessar e utilizar bancos de dados padrão e bancos de dados solicitados de scripts e ferramentas externos com acesso e controle de segurança granulares.
As APIs de nuvem abertas para armazenamentos de dados solicitados são APIs beta que podem estar sujeitas a alterações para futuras versões.
Uso
Você pode melhorar várias áreas do seu fluxo de trabalho acessando seus dados com essas APIs, como:
Portal de Suporte ao Cliente : Armazenamentos de dados são úteis para armazenar recursos persistentes do usuário, como itens em inventários de usuários ou pontos de habilidade.Às vezes você precisa atualizar esses recursos para suporte ao cliente.Em vez de usar o Studio ou entrar em uma experiência manualmente, você pode construir um aplicativo da web para permitir que seus agentes de atendimento ao cliente lidem diretamente com solicitações de suporte ao cliente, como visualizar e modificar inventários de usuários e emitir reembolsos.
Painel de Operações ao Vivo : Você pode construir um painel de operações ao vivo usando as APIs para melhorar a eficiência das operações ao vivo.Por exemplo, você pode agendar um evento com antecedência, escondê-lo sob uma bandeira de recurso como parte dos dados de configuração em um armazenamento de dados e definir um tempo para virar a bandeira para publicar o evento.Os servidores de experiência podem detectar essa mudança lendo a bandeira para lançar o evento.
Tabela de classificação externa : Para promover suas experiências fora do Roblox, você pode obter as informações de sua experiência, como a tabela de classificação de uma corrida, em tempo real e exibi-la em um site externo.Você pode conceder acesso somente de leitura aos seus armazenamentos de dados solicitados para o site solicitar periodicamente os dados mais recentes através do HTTP e atualizar a página da web.
Automatização de migração de dados : Os dados podem mudar ou atualizar à medida que sua experiência evolui, como atualizar esquemas de dados para acomodar novos recursos.Para evitar perder dados de usuário existentes, às vezes você precisa migrar seus armazenamentos de dados do antigo esquema para um novo.Você pode escrever um script externo que leia cada entrada de armazenamentos de dados atuais, mapie os dados para o novo esquema e escreva a entrada de volta para um novo armazenamento de dados para automatizar a migração de dados.
Diferenças com a API (Interface de Programação para Aplicações)do Motor
Embora as APIs de Nuvem Aberta sejam semelhantes a DataStoreService, há algumas diferenças importantes:
ID do Universo e nome do armazenamento de dados : Ao contrário da API (Interface de Programação para Aplicações)do Motor, as APIs da Nuvem Aberta são sem estado e podem vir de qualquer lugar, então você deve sempre fornecer o ID do universo , o identificador exclusivo de sua experiência, e o nome do armazenamento de dados quando enviar as solicitações.Para mais informações sobre como obter um ID de universo, veja ID de Universo.
Permissões separadas para criação e atualização : A API do Motor cria novas entradas se elas não existirem quando você chamar DataStore:SetAsync() , mas os métodos da Nuvem Aberta para criação e atualização de entradas são separados.Permissões separadas podem ser mais seguras e mais flexíveis em certas situações.Por exemplo, você pode criar uma ferramenta de suporte ao cliente que possa editar o perfil de um usuário existente, mas não pode criar o perfil de um novo usuário.
Serialização de dados : Todos os pontos finais do Open Cloud exigem que você serialize todos os dados antes do transporte de rede.Serialização significa converter um objeto em uma string / cadeia / texto.A deserialização é o oposto ( converter uma string em um Objeto).A API do Motor serializa e deserializa o conteúdo da entrada automaticamente, mas para a Nuvem Aberta, você precisa gerar ou parsar seus dados de entrada com JSON por conta possuir.
Permissões de segurança
Armazenamentos de dados frequentemente armazenam informações sensíveis, como perfis de usuário e moeda virtual.Para manter a segurança, cada Open Cloud API tem permissões correspondentes necessárias que você deve adicionar à chave da API, como a permissão List Keys para a API (Interface de Programação para Aplicações)de listagem.Se você não adicionar as permissões necessárias, a chamada da API retorna um erro.Para as permissões específicas que são necessárias para cada operação, consulte a referência da API de padrão e lojas de dados ordenadas.
Ao configurar chaves de API, você pode definir permissões granulares, como leitura, escrita e listagem de entradas, para cada armazenamento de dados dentro de uma experiência específica, ou você pode dar uma chave para ler ou escrever todos os armazenamentos de dados dentro de uma experiência.Você também pode limitar o acesso a um subconjunto de armazenamentos de dados necessários para sua ferramenta, em vez de expor todos os armazenamentos de dados.Isso mitiga o impacto caso sua chave seja vazada.
Ferramentas de construção
Você pode usar o idioma de sua escolha para construir ferramentas com APIs de nuvem aberta para armazenamento de dados para atender às suas necessidades de operação.Os seguintes exemplos percorrem os processos de construção de um portal de suporte de inventário de usuário em Python com armazenamentos de dados padrão e um placar persistente externo usando armazenamentos de dados ordenados.
Portal de suporte ao inventário do usuário
Esta seção fornece um exemplo concreto de construir um portal de suporte ao inventário de usuários em Python, no qual você pode listar e ler um subconjunto do inventário de usuários, fazer edições e, em seguida, atualizar de volta para o armazenamento de dados de uma experiência.
Para este exemplo, assuma o seguindo:
O nome do armazenamento de dados que armazena o inventário do usuário é Inventory .
O esquema de dados para cada entrada de dados é "userId": {"currency": number, "weapon": string, "level": number} . A chave é apenas userId .
O script Python lista um subconjunto de inventários de usuários com base em prefixos, aumenta sua moeda virtual em 10 para uma promoção e atualiza os dados.
De um nível alto, você pode construir seu aplicativo Python adicionando permissões de chave da API e depois adicionando scripts.
Adicione permissões de chave da API para armazenamentos de dados
Ao criar uma Chave de API para este exemplo, certifique-se de executar as seguintes configurações:
Do menu Selecionar Sistema de API na seção Permissões de Acesso , selecione armazenamentos de dados universais .
(Opcional) Na seção Armazenamentos de Dados , selecione operações de API para armazenamentos de dados específicos.
- Ative a alternar Operações de armazenamento de dados específicos .Por padrão, cinco armazenamentos de dados carregarautomaticamente, mas você pode adicionar armazenamentos de dados adicionais através do botão + Adicionar Armazenamento de Dados à Lista .
- Selecione a seta suspensa ao lado do nome de um lojade dados, então selecione as operações de API a que o armazenamento de dados deve ter acesso.
Selecione operações de API para toda a experiência.
- Clique no Selecionar Experiência para Adicionar menu suspenso e selecione uma experiência.
- Nas Operações de Experiência , clique na seta suspensa e selecione as operações que você deseja adicionar à sua API (Interface de Programação para Aplicações).Este exemplo seleciona Leia Entrada , Atualize Entrada e Chaves de Lista de Entrada para toda a experiência.
Você não precisa da permissão da chave da API create entries pois o aplicativo não cria novos inventários de usuários.
Na seção Segurança , defina explicitamente o acesso IP à chave usando notação CIDR, e defina uma data de expiração explícita para que sua chave pare de funcionar após essa data.Para este exemplo, se você planeja fazer testes locais primeiro, você pode remover a restrição de IP definindo-a para 0.0.0.0/0 e deixando expirar em 30 dias .
Adicione scripts para o portal de suporte ao inventário do usuário
Depois de criar a chave da API com as permissões necessárias para o aplicativo de exemplo, você precisa adicionar código JavaScript para executar as funcionalidades do aplicativo.O arquivo mostra como definir , e métodos.O arquivo update_inventory.js usa os métodos definidos para listar um subconjunto de inventários de usuários, aumentar a moeda virtual para cada usuário e atualizar os dados.
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 testar, defina a variável de ambiente API_KEY e execute o arquivo JavaScript:
Tabela de classificação persistente externa
Esta seção percorre um exemplo concreto de criação de uma tabela de classificação persistente externa no Python, na qual você pode listar e ler as informações de seus usuários armazenadas em armazenamentos de dados organizados, fazer edições e, em seguida, publicar em um site externo para promoção.
Para este exemplo, assuma o seguindo:
O exemplo de código cria uma lista pré-definida de nomes de usuários para o propósito de demonstração.Para a sua própria aplicação, você deve usar a lista de usuários reais em sua experiência.
O exemplo de código adiciona 50 pontos a cada usuário que se junta à experiência para o propósito de demonstração.Para a sua própria aplicação, você deve definir a regra com base no design da sua experiência.
De um nível alto, você pode construir seu aplicativo Python adicionando permissões de chave da API e depois adicionando scripts.
Adicione permissões de chave da API para armazenamentos de dados encomendados
O exemplo de aplicativo requer quatro métodos para alcançar suas funcionalidades: List , Create , Update e Increment , então você precisa adicionar as seguintes permissões de chave da API:
- Leia para o método list.
- Escreva para Create , Update e Increment métodos.
Ao criar uma Chave de API para este exemplo, certifique-se de executar as seguintes operações:
Do menu Selecionar Sistema de API na seção Permissões de Acesso , selecione Armazenamentos de Dados Ordenados .
Adicione permissões de operações de API para ler e escrever armazenamentos de dados ordenados na experiência alvo.
- Clique no menu suspenso Selecionar Experiência para Adicionar e selecione a experiência alvo.
- Nas Operações de Experiência , expanda o menu suspenso para selecionar Ler e Escrever operações
Na seção Segurança , defina explicitamente o acesso IP à chave usando notação CIDR, e defina uma data de expiração explícita para que sua chave pare de funcionar após essa data.Para este exemplo, se você planeja fazer testes locais primeiro, você pode remover a restrição de IP definindo-a para 0.0.0.0/0 e deixando expirar em 30 dias .
Adicione scripts para a tabela de classificação
Depois de criar a chave da API com as permissões necessárias para o aplicativo de exemplo, você precisa adicionar código JavaScript para executar as funcionalidades do aplicativo.
O arquivo mostra como definir , , e métodos.O arquivo leaderboard.js usa os métodos definidos para criar entradas de usuários em armazenamentos de dados organizados, exibir pontuações, aumentar pontuações de usuários vencedores e atualizar a tabela de classificação.O arquivo leaderboard.js também importa um arquivo config.json para configurar o ID do Universo, o domínio da API e sua chave da 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);
});
configuração
{
"universe_id": "",
"api_key_url": "https://apis.roblox.com/datastores/ordered-v1/"
"api_key": ""
}
Para testar, defina a variável de ambiente API_KEY e execute o arquivo leaderboard.js:
Após concluir os testes, você pode publicar ou incorporar a tabela de classificação em sites fora do Roblox para mais alcance.