Verwaltung von API-Anfragen für Datenspeicher

Bevor du Anfragen an Open Cloud-APIs für Standard-Datenspeicher und bestellte Datenspeicher sendest, musst du verstehen, wie du sie richtig handhaben kannst.Für Informationen über die Verwendung der API siehe den Verwendungsleitfaden.

Autorisierung

Wie alle Open Cloud-APIs erfordern Datenlagerendpunkte alle Anfragen, die den x-api-key enthalten, der einen API-Schlüssel mit ausreichenden Berechtigungen für die Anfrage enthält.Dafür musst du den Schlüssel auf das Erlebnis und den Storeanwenden, und die Endpunktoperation ist erlaubt.Wenn der Schlüssel ungültig ist, wird 403 Unauthorized zurückgegeben.Für weitere Informationen zu API-Schlüsseln siehe API-Schlüssel verwalten.

Drosseln

Alle Endpunkte haben zwei Arten von Universumsebene-Drosselung: Anforderungs-pro-Minute-Drosselung und Durchlauf-Drosselung .Mit jedem Erlebnis ermöglicht Request-per-Minute-Drosselung , eine bestimmte Anzahl von Anfragen pro Minute zu senden, und Bandbreitendrosselung ermöglicht es Ihnen, eine bestimmte Menge an Daten pro Minute zu senden, unabhängig von der Anzahl der API-Schlüssel.

Im Gegensatz zur Luau-API werden diese Limits derzeit nicht basierend auf der Anzahl der Benutzer skaliert. Das Überschreiten dieser Limits verursacht, dass der Endpunkt 429 Too Many Requests zurückkehrt.

Standard-Datenspeicher drosseln Einschränkungen

Bestellte Datenlagern Drosselgrenzen angeordnet

Eingabe-Validierung

Bevor du deine Anfrage sendest, stelle sicher, die Endpunkt参数 auf Formatierungsanforderungen und Einschränkungen gemäß der folgenden Tabelle zu überprüfen.Einzelne Endpunkte können zusätzliche Anforderungen darüber hinaus haben.Wenn ein Parameter die folgenden Einschränkungen nicht erfüllt, gibt die Endpunkt eine 400 Bad Request zurück.

Universitäts-ID

Die Universum-ID ist die eindeutige Kennung des Erlebnisses, in dem du auf deine Datenbanken zugreifen möchtest.Der Wert der Universitäts-ID eines Erlebnisses ist der Wert seiner DataModel.GameId, nicht , gleich wie die Startplatz-ID , die den Startplatz eines Erlebnisses identifiziert, anstatt die gesamte Erfahrung.

Du kannst die Universum-ID eines Erlebnisses mit den folgenden Schritten erhalten:

1. Navigiere zum Creator-Dashboard.

2. Finde das Erlebnis mit Datenlagern, auf die du Zugriffmöchtest.

3. Bewegen Sie den Mauszeiger über die Miniaturansicht des Erlebnisses, klicken Sie auf die Schaltfläche ⋯ und wählen Sie Universum-ID kopieren .

   

Umgebungen

Du kannst deine Datenlagern organisieren, indem du eine eindeutige Zeichenfolge als Scope festlegst, die einen Unterordner für den Eintrag angibt.Sobald du ein Scope festgelegt hast, wird es automatisch vor allen Schlüsseln in allen Operationen angehängt, die auf dem Storedurchgeführt werden. области sind optional und standardmäßig als global für Standard-Datenspeicher, aber für bestellte Datenspeicher erforderlich.

Der Bereich kategorisiert deine Daten mit einer Zeichenkette und einem Trennzeichen mit "/", wie z. B.:

Alle Datenlagereingabemethoden haben einen Scope -Parameter, wenn Sie auf die in einem nicht standardmäßigen Scope gespeicherten Einträge zugreifen müssen.Zum Beispiel könnten Sie einen 1234 Schlüssel unter dem Standard-global Umfang und denselben Schlüssel unter dem special Umfang haben.Du kannst auf das ehemalige zugreifen, ohne den Scope-Parameter zu verwenden, aber um auf das letztere zuzugreifen, musst du den Scope-Parameter als special in Get Entry oder Increment Entry API-Aufrufen spezifizieren.

Zusätzlich, wenn du alle Schlüssel auflisten möchtest, die in einem Datenlagerspeicher mit einer oder mehreren nicht standardmäßigen Bereichen gespeichert sind, kannst du den -Parameter in der -Methode auf festlegen, in dem Fall ruft die Anfrage eine Tuplizität mit Schlüsselstring und Scope zurück.Im vorherigen Beispiel würde die List Entries beide zurückgeben ( 1234 , global ), und ( 1234 , special ) in der Antwort.

Du kannst nicht Scope und AllScopes Parameter auf derselben Anfrage übergeben, sonst gibt die Anruf eine Fehler zurück.Durch die Nutzung der Hilfsfunktionen der Open Cloud APIs für das Modul Datenbank zeigt der folgende Code, wie Sie jeden Schlüssel in einer Datenbank mit einem benutzerdefinierten Umfang lesen können:

Listen von Schlüsseln für verschiedene Bereiche
# Einrichten
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Listen von Schlüsseln für den globalen Umfang
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Listen von Schlüsseln für spezielle Reichweite
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Listen von Schlüsseln für allScope auf wahr gesetzt
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Schlüssel mit dem entsprechenden Umfang werden in der Antwort zurückgegeben:

Beispielfertige Antworten für verschiedene Bereiche
// Antwort für globalen Umfang
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Antwort für spezielles Umfang
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Antwort für AllScopes
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

Inhalt-MD5

Content-MD5 ist die basis-64 verschlüsselte MD5-Prüfsumme des Inhalts.Es ist ein optioneller Anforderungskopf für den Set Entry-Endpunkt, der die Datenintegrität überprüft und mögliche Probleme erkennt.

Du kannst die Sprache deiner Wahl verwenden, um den Wert des content-md5-Header zu berechnen.Das folgende Beispiel verwendet Python.Die hashlib.md5()- und base64.b64encode()-Funktionen sind in Python-Standardbibliotheken verfügbar (2.7, 3+).

Inhalte generieren-MD5
# Mit Prompts
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# Nur stdin und stdout verwenden
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Wenn Sie Probleme beim Generieren eines gültigen content-md5-Werts auftreten, müssen Sie möglicherweise Ihren Anfragekörper in UTF-8-Binär umcodieren, bevor Sie die Prüfsumme berechnen.

Mäuse

Endpunkte, die Listen von Daten zurückgeben, können auch einen nextPageCursor String zurückgeben.Dies zeigt an, dass es mehr Daten im angeforderten festlegengibt.Um es zu erhalten, gib diesen String im cursor Anfrage参数 auf einer nachfolgenden Anfrage ein.Wenn der Cursor-Parameter bereitgestellt, aber ungültig ist, gibt die Endpunkt 400 Bad Request zurück.

Das Format der Mauszeichenketten ist nicht definiert . Du solltest sie nicht interpretieren oder analysieren, da sie sich jederzeit ändern können.

Filter

Wenn du Anfragen an die List -Methode für bestellte Datenbanken sendest, kannst du einen optionalen filter Anfrage-Parameter hinzufügen, um Einträge mit Werten in einem bestimmten Bereich zurückzugeben.

Der filter -Parameter unterstützt einen Logikoperator, && , und zwei Vergleichsoperatoren, <= , um den maximalen Wert festzulegen, und >= , um den minimalen Wert festzulegen.Wenn du eine Reichweite mit einem maximalen und minimalen Wert festlegen möchtest, füge && zwischen den beiden Sequenzen hinzu.

Zum Beispiel, um Einträge mit Werten, die weniger als oder gleich 10 sind, zurückzugeben, musst du entry <= 10 als Wert filter eingeben.Um Elemente mit Werten zwischen 10 und 50 zurückzugeben, geben Sie entry <= 50 && entry >= 10 ein.

Die folgenden Beispiele sind falsche filter Werte, die deine Anfragen fehlschlagen können:

• entry <= 10 - kein leerzeichen zwischen jedem teil der sequenz.
• 10 <= entry - entry und der vergleichswert sind auf der falschen seite.
• entry <= 10 && entry <= 50 - && kann nur verwendet werden, um einen bereich mit beiden vergleichsoperatoren für den minimal- und maximalwert zu spezifizieren.

Fehlende Flags zulassen

Wenn du Anfragen an die Update Methode sendest, um einen vorhandenen bestellten Datenlagereintrag zu aktualisieren, kannst du eine optionale allow_missing Flagge hinzufügen, um die Erstellung eines Eintrags zu ermöglichen, auch wenn der Eintrag nicht existiert.

Wenn du die Flagge allow_missing auf True festlegst:

• Wenn der Eintrag nicht existiert, gibt die Antwort einen neuen Eintrag zurück.

• Wenn der Eintrag existiert, aber der Inhalt dem bestehenden Wert des Eintrags entspricht, bleibt der bestehende Eintrag unverändert.

• Wenn der Eintrag existiert und der Inhalt dem bestehenden Wert des Eintrags nicht entspricht, gibt die Antwort den Eintrag mit dem aktualisierten neuen Inhaltswert zurück.