Verwendungsanleitung für Datenspeicher

*Dieser Inhalt wurde mit KI (Beta) übersetzt und kann Fehler enthalten. Um diese Seite auf Englisch zu sehen, klicke hier.

Neben dem Zugriff auf Datenspeicher mit der Engine-API () in Studio oder Live-Servern kannst du die Open Cloud-APIs verwenden, um auf standardmäßige und bestellte Datenstores von externen Skripten und Werkzeugen mit granulärer Zugriffskontrolle und Sicherheit zuzugreifen und zu nutzen.

Verwendung

Sie können mehrere Bereiche Ihres Workflows verbessern, indem Sie auf diese APIs zugreifen, um Ihre Daten zu erhalten, wie:

  • Kundenunterstützungsportal : Datenspeicher sind nützlich zur Aufbewahrung dauerhafter Benutzerressourcen, wie Artikel in Benutzer-Inventaren oder Fähigkeitspunkten.Manchmal musst du diese Ressourcen für die Supportaktualisieren.Anstatt Studio zu verwenden oder einem Erlebnis manuell beizutreten, kannst du eine Web-Anwendung erstellen, um deinen Kundenserviceagenten zu ermöglichen, Kundenunterstützungsanfragen direkt zu bearbeiten, z. B. Inventare von Benutzern anzuzeigen und zu modifizieren und Rückerstattungen auszustellen.

  • LiveOps-Dashboard : Du kannst ein LiveOps-Dashboard mit den APIs erstellen, um die Effizienz von Live-Operationen zu verbessern.Zum Beispiel könnten Sie ein Ereignis im Voraus planen, es unter einer Funktionsflagge als Teil der Konfigurationsdaten in einem Storeverbergen und eine Zeit festlegen, um die Flagge für die Veröffentlichung des Ereignisses umzuschalten.Deine Erfahrungsserver können diese Änderung erkennen, indem sie die Flagge lesen, um das Ereignis zu starten.

  • Externe Rangliste : Um deine Erfahrungen außerhalb von Roblox zu fördern, kannst du die Informationen deiner Erlebnis, wie die Rangliste eines Rennens, in Echtzeit abrufen und auf einer externen Website anzeigen.Du kannst deinen bestellten Datenlagern Zugriff nur lesen gewähren, damit die Website die neuesten Daten periodisch über HTTP anfordert und die Webseite aktualisiert.

  • Datenmigration-Automatisierung : Daten können sich ändern oder aktualisieren, wenn deine Erfahrung weiterentwickelt wird, z. B. indem die Datenstrukturen aktualisiert werden, um neue Funktionen zu unterstützen.Um das Verlieren von bestehenden Benutzerdaten zu vermeiden, musst du manchmal deine Datenspeicher vom alten Schema auf ein neues migrieren.Du kannst ein externes Skript schreiben, das jeden Eintrag aus aktuellen Datenlagern liest, die Daten auf das neue Schema macht und den Eintrag dann in einen neuen Datenlagern zurückschreibt, um die Datenmigration zu automatisieren.

Unterschiede mit der Engine-API

Obwohl Open Cloud-APIs ähnlich sind wie DataStoreService, gibt es ein paar wichtige Unterschiede:

  • Universitäts-ID und Name des Datenlagers : Im Gegensatz zur Engine-APIsind Open Cloud APIs statischlos und können von überall kommen, sodass Sie immer die Universitäts-ID , den eindeutigen Identifikator Ihrer Erlebnis, und den Datenlagernamen name senden müssen, wenn Sie die Anfragen senden.Für weitere Informationen darüber, wie du eine Universum-ID erhältst, siehe Universum-ID.

  • Getrennte Berechtigungen für das Erstellen und Aktualisieren : Die Engine-API erstellt neue Einträge, wenn sie nicht vorhanden sind, wenn Sie DataStore:SetAsync() aufrufen, aber Open Cloud-Methoden zum Erstellen und Aktualisieren von Einträgen sind getrennt.Separate Berechtigungen können in bestimmten Situationen sicherer und flexibler sein.Zum Beispiel können Sie ein Kundensupport-Tool erstellen, das das Profil eines bestehenden Benutzers bearbeiten kann, aber kein neues Benutzerprofil erstellen kann.

  • Datenserialisierung : Alle Open Cloud-Endpunkte erfordern, dass Sie alle Daten vor dem Netzwerktransport serialisieren.Serialisierung bedeutet, ein Objekt in eine Stringumzuwandeln.Die Deserialisierung ist das Gegenteil (Eine Zeichenkette in ein Objekt umwandeln).Die Engine serialisiert und deserialisiert den Inhalt des Eintrags automatisch, aber für Open Cloud musst du deine Eintragsdaten mit JSON besitzengenerieren oder parsen.

Sicherheitsberechtigungen

Datenspeicher speichern oft sensible Informationen, wie Benutzerprofile und virtuelle Währung.Um die Sicherheit zu gewährleisten, hat jede Open Cloud API entsprechende erforderliche Berechtigungen, die Sie zu Ihrem API-Schlüssel hinzufügen müssen, wie die Berechtigung List Keys für die Listen-API.Wenn du die erforderlichen Berechtigungen nicht hinzufügst, gibt dein API-Aufruf einen Fehler zurück.Für die spezifischen Berechtigungen, die für jede Operation erforderlich sind, siehe die API-Referenz von standard und bestellten Datenlagern.

Wenn du deine API-Schlüssel konfigurierst, kannst du granulare Berechtigungen wie gelesen, Schreiben und Eintragsliste für jeden Datenstoff innerhalb einer bestimmten Erlebnisfestlegen, oder du kannst einen Schlüssel geben, um alle Datenstände innerhalb einer Erlebniszu lesen oder zu schreiben.Du kannst auch den Zugriff auf einen Unter集 von Datenlagern, die für dein Werkzeug erforderlich sind, begrenzen, anstatt alle Datenlagern zu enthüllen.Dies mindert den Einfluss, falls dein Schlüssel geleakt wird.

Bauwerkzeuge

Du kannst die Sprache deiner Wahl verwenden, um Werkzeuge mit Offenen Cloud-APIs für Datenbanken zu erstellen, um deine Betriebsbedürfnisse zu erfüllen.Die folgenden Beispiele durchlaufen die Prozesse zur Erstellung eines Benutzerinventar-Unterstützungsportals in Python mit Standard-Datenspeichern und einer externen dauerhaften Rangliste mit sortierten Datenlagern.

Benutzerinventar-Unterstützungsportal

Dieser Abschnitt gibt ein konkretes Beispiel für das Erstellen eines Benutzerinventar-Unterstützungsportals in Python, in dem du einen Teil deines Inventarlisten und lesen, Änderungen vornehmen und dann zum Storeeines Erlebnisses zurückaktualisieren kannst.

Für dieses Beispiel gehen Sie davon aus, gefolgte Profile:

  • Der Name des Datenspeichers, der das Benutzerinventar speichert, ist Inventory .

  • Das Datenmodell für jeden Dateneintrag ist "userId": {"currency": number, "weapon": string, "level": number}. Der Schlüssel ist nur userId.

  • Das Python-Skript listet einen Unterbereich der Benutzerinventare basierend auf Präfixen auf und erhöht ihre virtuelle Währung um 10 für eine Aktionund aktualisiert die Daten.

Auf einer hohen Stufekannst du deine Python-App erstellen, indem du API-Schlüsselberechtigungen hinzufügst und dann Skripte hinzufügst.

Füge API-Schlüsselberechtigungen für Datenspeicher hinzu

Wenn du zum Beispiel für dieses Beispiel einen API-Schlüssel erstellst, stelle sicher, dass du die folgenden Einstellungen durchführst:

  1. Aus dem API-System auswählen Menü im Zugriffsberechtigungen Abschnitt wählen Sie Universum-Datenspeicher .

  2. (Optional) In der Datenspeicher Sektion wählen Sie API-Operationen für spezifische Datenspeicher aus.

    1. Aktivieren Sie die Spezifischen Datenlagers operations umschalten.Standardmäßig werden fünf Datenspeicher automatisch geladen, aber du kannst über die Schaltfläche + Datenspeicher zur Liste hinzufügen zusätzliche Datenspeicher hinzufügen.
    2. Wählen Sie den Dropdown-Pfeil neben dem Namen eines Storeaus, dann wählen Sie die API-Operationen aus, zu denen der Datenspeicher Zugriff haben soll.
  3. Wählen Sie API-Operationen für das gesamte Erlebnis aus.

    1. Klicken Sie auf die Auswahl-Erfahrung hinzufügen Dropdown und wählen Sie eine Erlebnisaus.
    2. In den Erfahrungsoperationen klicke auf den Dropdown-Pfeil und wähle die Operationen aus, die du zu deiner API hinzufügen möchtest.Dieses Beispiel wählt Lesen von Einträgen , Aktualisieren von Einträgen und Listen-Eintrags-Schlüssel für die gesamte Erlebnisaus.
  4. Im Sicherheits -Abschnitt wird explizit IP-Zugriff auf den Schlüssel mit der CIDR-Notation festgelegt und ein expliziter Verfallszeitpunkt festgelegt, so dass Ihr Schlüssel nach diesem Datum automatisch aufhört zu arbeiten.Für dieses Beispiel, wenn Sie planen, zuerst lokale Tests durchzuführen, können Sie die IP-Beschränkung entfernen, indem Sie sie auf 0.0.0.0/0 einstellen und sie in 30 Tagen ablaufen lassen.

Füge Skripte für das Benutzerinventar-Unterstützungsportal hinzu

Nach der Erstellung des API-Schlüssels mit den erforderlichen Berechtigungen für die Beispiel-App musst du JavaScript-Code hinzufügen, um App-Funktionen auszuführen.Die Datei zeigt, wie man , und Methoden definiert.Die update_inventory.js Datei verwendet die definierten Methoden, um einen Unterbereich der Benutzerinventare aufzulisten, die virtuelle Währung für jeden Benutzer zu erhöhen und die Daten zu aktualisieren.

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`
);
});
}

Um zu testen, setzen Sie die API_KEY Umgebungsvariable und führen Sie die JavaScript-Datei aus:


export API_KEY=... \
node updateInventory.js

Externe permanente Bestenliste

Dieser Abschnitt geht durch ein konkretes Beispiel für die Erstellung einer externen dauerhaften Rangliste in Python, in der du deine Benutzerinformationen listen und lesen kannst, die in aufgeräumten Datenlagern gespeichert sind, Änderungen vornehmen und dann auf einer externen Website für die Aktionveröffentlichen kannst.

Für dieses Beispiel gehen Sie davon aus, gefolgte Profile:

  • Das Codebeispiel erstellt eine vordefinierte Liste von Benutzernamen für den Demozweck.Für deine eigene Anwendung solltest du die Liste der tatsächlichen Benutzer in deiner Erlebnisverwenden.

  • Das Codebeispiel fügt jedem Benutzer, der sich dem Erlebnis für den Demozweck anschließt, 50 Punkte hinzu.Für deine eigene Anwendung solltest du die Regel basierend auf dem Design deiner Erfahrung definieren.

Auf einer hohen Stufekannst du deine Python-App erstellen, indem du API-Schlüsselberechtigungen hinzufügst und dann Skripte hinzufügst.

Füge API-Schlüsselberechtigungen für bestellte Datenstores hinzu

Die Beispiel-App benötigt vier Methoden, um ihre Funktionalitäten zu erreichen: List , Create , Update und Increment , so musst du die folgenden API-Schlüsselberechtigungen hinzufügen:

  • Lesen für die Methode list.
  • Schreiben für Create , Update und Increment Methoden.

Wenn du zum Beispiel einen API-Schlüssel erstellst für dieses Beispiel, stelle sicher, dass du die folgenden Operationen durchführst:

  1. Aus dem API-System auswählen Menü im Zugriffsberechtigungen Abschnitt wählen Sie Ordnungsgemäße Datenspeicher .

  2. Füge Berechtigungen für API-Operationen hinzu, um bestellte Datenstores in der Erlebniszu lesen und zu schreiben.

    1. Klicken Sie auf die Erfahrung auswählen, um hinzuzufügen Dropdown-Liste und wählen Sie die Erlebnisaus.
    2. In den Erfahrungsoperationen erweitern Sie das Dropdown, um die Lesen - und Schreiben -Operationen auszuwählen.
  3. Im Sicherheits -Abschnitt wird explizit IP-Zugriff auf den Schlüssel mit der CIDR-Notation festgelegt und ein expliziter Verfallszeitpunkt festgelegt, so dass Ihr Schlüssel nach diesem Datum automatisch aufhört zu arbeiten.Für dieses Beispiel, wenn Sie planen, zuerst lokale Tests durchzuführen, können Sie die IP-Beschränkung entfernen, indem Sie sie auf 0.0.0.0/0 einstellen und sie in 30 Tagen ablaufen lassen.

Füge Skripte für die Bestenlistehinzu

Nach der Erstellung des API-Schlüssels mit den erforderlichen Berechtigungen für die Beispiel-App musst du JavaScript-Code hinzufügen, um App-Funktionen auszuführen.

Die Datei zeigt, wie man , , und Methoden definiert.Die leaderboard.js Datei verwendet die definierten Methoden, um Einträge von Benutzern in geordneten Datenlagern zu erstellen, Ergebnisse anzuzeigen, die Punktzahl von gewinnenden Benutzern zu erhöhen und die Bestenlistezu aktualisieren.Die leaderboard.js Datei importiert auch eine config.json Datei für die Konfiguration der Universitäts-ID, der API-Domäne und Ihres API-Schlüssels.

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);
});
konfigurieren

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

Um zu testen, legen Sie die API_KEY Umgebungsvariable fest und führen Sie die leaderboard.js Datei aus:


export API_KEY=... \
node leaderboard.js

Nach Abschluss der Tests kannst du die Rangliste auf Websites außerhalb von Roblox veröffentlichen oder einbetten, um mehr Reichweite zu erzielen.