Richieste API di gestione per archivi di dati

Prima di inviare richieste alle API Open Cloud per depositi di dati standard e depositi di dati ordinati, devi capire come gestirle correttamente.Per informazioni sull'uso dell'API, vedi la Guida all'uso.

Autorizzazione

Come tutte le API Open Cloud, i punti di destinazione del deposito dati richiedono tutte le richieste di includere l'intestazione x-api-key, che contiene una chiave API con abbastanza permessi per la Richiesta.Questo richiede che tu applichi la chiave all'esperienza e al Negoziodi dati e l'operazione del punto finale è consentita.Se la chiave è non valida, 403 Unauthorized viene restituita.Per ulteriori informazioni sulle chiavi API, vedi Gestisci chiavi API.

Accelerazione

Tutti i punti finali hanno due tipi di riduzione del livello dell'universo: riduzione delle richieste per minuto e riduzione del throughput .Con ogni esperienza, il throttling delle richieste per minuto ti consente di inviare un certo numero di richieste per minuto e il throttling del throughput ti consente di inviare una certa quantità di dati per minuto, indipendentemente dal numero di chiavi API.

A differenza dell'API Luau, questi limiti attualmente non si adattano in base al numero di utenti. Superare questi limiti fa sì che l'endpoint restituisca 429 Too Many Requests .

Magazzini di dati standard che impongono limiti di throttling

inserisci / scrividi richiesta	Metodo	Limiti di accelerazione
Scrivi	Imposta l'ingresso Incrementa l'ingresso Elimina l'ingresso	10 MB/min/write throughput dell'universo 300 reqs/min/universo
Leggi	Lista negozi di dati Lista entrate Ottieni entrata Lista versioni di entrata Ottieni versione di entrata	20 MB/min/write throughput dell'universo 300 reqs/min/universo

Magazzini di dati ordinati limiti di throttling

inserisci / scrividi richiesta	Metodo	Limiti di accelerazione
Scrivi	Crea Incremento Aggiorna Elimina	300 reqs/min/universo
Leggi	Elenco Ottieni	300 reqs/min/universo

Validazione dell'input

Prima di inviare la tua Richiesta, assicurati di validare i parametri dell'endpoint sulla formattazione dei requisiti e delle restrizioni in base alla seguente tabella.Gli endpoint individuali possono avere requisiti aggiuntivi al di là di questi.Se un parametro non soddisfa le seguenti restrizioni, l'endpoint restituisce un 400 Bad Request .

Gli endpoint dei Data Store ordinati utilizzano Percent-Encoding per tutti i parametri di query e corpo.A meno che tu non abbia caratteri speciali nei tuoi valori di parametro che rompano gli URL, non devi occuparti dell'encoding.

Ingresso	Tipo	Notizie
universeId	numero	L'identificatore univoco della tua esperienza. Vedi ID Universo .
datastoreName	stringa	La lunghezza deve essere di 50 byte o meno. Non può essere nullo o vuoto.
scope	stringa	La portata di un Negoziodi dati. Vedi Portate . La lunghezza deve essere inferiore a 50 byte.
entryKey	stringa	La lunghezza deve essere di 50 byte o meno. Non può essere nullo o vuoto.
content-md5	stringa	La somma di controllo MD5 codificata in base-64 del contenuto. Vedi Contenuto-MD5 .
roblox-entry-attributes	stringa	Serializzato dall'oggetto JSON. La lunghezza deve essere inferiore a 300 byte.
roblox-entry-userids	Stringa	Serializzato da array JSON di 0-4 numeri. Non più di 4 ID utente.
cursor	stringa	Un indicatore di più dati disponibili nel Impostaredi risultati richiesto. Vedi Cursori .

ID dell'universo

L'ID Universo è l'identificatore univoco dell'esperienza in cui vuoi accedere ai tuoi depositi di dati.Il valore dell'ID Universo di un'esperienza è il valore del suo , non , dello stesso valore dell'ID del luogo di partenza di un'esperienza piuttosto che dell'intera esperienza.

Puoi ottenere l'ID Universo di un'esperienza con i seguenti passaggi:

Naviga alla Dashboard del Creatore.
Trova l'esperienza con i depositi di dati a cui vuoi Accesso.
Passa il mouse sulla miniatura dell'esperienza, fai clic sul pulsante ⋯ e seleziona Copia ID Universo .

Ambiti

Puoi organizzare i tuoi archivi di dati impostando una stringa unica come scopo che specifica una sottocartella per l'entrata.Una volta impostata una scala, viene automaticamente aggiunta a tutte le chiavi in tutte le operazioni eseguite sul data Negozio.Gli ambiti sono opzionali e per impostazione predefinita come global per i depositi di dati standard, ma richiesti per i depositi di dati ordinati.

Si consiglia vivamente di utilizzare il parametro invece di per ordinare e elencare standard depositi di dati.

La categoria di scopo classifica i tuoi dati con una stringa e un separatore con "/", come:

Chiave	Ambito
case/Utente_1	case
pet/Utente_1	animaletti
inventario/Utente_1	inventario, reportorio

Tutti i metodi di operazione di inserimento nel deposito dati hanno un parametro Scope per quando è necessario accedere alle voci memorizzate sotto uno scope non predefinito.Ad esempio, potresti avere una chiave 1234 sotto la scoperta predefinita global e la stessa chiave sotto la scoperta special.Puoi accedere all'uno senza utilizzare il parametro di scopo, ma per accedere all'altro, devi specificare il parametro di scopo come special in Get Entry o Increment Entry chiamate API.

Inoltre, se vuoi enumerare tutte le chiavi memorizzate in un deposito di dati che ha uno o più scopi non predefiniti, puoi impostare il parametro AllScopes in List Entries metodo a essere true , in cui caso la chiamata restituisce una tuple con la stringa di chiave e lo scopo.Nell'esempio precedente, il List Entries sarebbe restituito entrambi ( 1234 , global ), e ( 1234 , special ) nella risposta.

Non puoi passare Scope e AllScopes parametri sullo stesso Richiesta, altrimenti la chiamata restituisce un errore.Sfruttando le funzioni di aiuto delle API Open Cloud per il modulo storage dei dati, il seguente codice illustra come puoi leggere ogni chiave in un archivio dati con una scala personalizzata:

Elenca le chiavi per diversi ambiti
# Configurare
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Elenca le chiavi per la portata globale
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Elenca le chiavi per la scoperta speciale
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Lista le chiavi per tutti gliScope impostati su vero
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Le chiavi con la corrispondente scala vengono restituite nella risposta:

Esempi di risposte per diversi ambiti
// Risposta per la portata globale
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Risposta per scopo speciale
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Risposta per 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":""}

Contenuto-MD5

Content-MD5 è il checksum MD5 base-64 codificato del contenuto.È un'intestazione opzionale della richiesta per il endpoint Imposta entrata che controlla l'integrità dei dati e rileva potenziali problemi.

Se non includi l'intestazione content-md5 nella tua Richiesta, c'è la possibilità, sebbene con bassa probabilità, che potresti sperimentare la corruzione dei dati.

Puoi usare la lingua di tua scelta per calcolare il valore dell'intestazione content-md5.L'esempio seguente utilizza Python.Le funzioni hashlib.md5() e base64.b64encode() sono disponibili nelle librerie standard di Python (2.7, 3+).

Generazione del contenuto-MD5
# Con richieste
$ 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==
# Utilizzando solo stdin e stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Se ti imbatti in problemi nella generazione di un valore content-md5 valido, potresti dover codificare il corpo della richiesta in binario UTF-8 prima di calcolare il checksum.

Cursori

Gli endpoint che restituiscono elenchi di dati possono anche restituire una StringanextPageCursor .Questo indica che ci sono più dati disponibili nel Impostaredi risultati richiesto.Per riceverlo, fornisci questa stringa nel parametro della query cursor in una successiva Richiesta.Se il parametro cursore è fornito ma Non valido, l'endpoint restituisce 400 Bad Request .

Il formato delle stringhe del cursore non è definito . Non dovresti interpretarle o analizzarle poiché possono cambiare in qualsiasi momento.

Filtri

Quando si inviano richieste al metodo List per i data store ordinati, puoi aggiungere un parametro di query opzionale filter per restituire le voci con valori in un intervallo specificato.

Il parametro filter supporta un operatore logico, && , e due operatori di confronto, <= per impostare il valore massimo e >= per impostare il valore minimo.Se vuoi impostare un intervallo con un valore massimo e minimo, aggiungi && tra le due sequenze.

Ad esempio, per restituire le voci con valori inferiori o uguali a 10, devi inserire entry <= 10 come valore filter.Per restituire le voci con valori compresi tra 10 e 50, inserisci entry <= 50 && entry >= 10 .

Per inserire un valore filter valido, devi formattare tutte le filter stringhe con uno spazio tra ciascuna parte della sequenza.La parte sinistra di ogni sequenza deve iniziare con 'entry', e la parte destra deve avere un valore numerico.Filter

I seguenti esempi sono valori errati filter che possono fallire le tue richieste:

entry <= 10 - nessuno spazio vuoto tra ciascuna parte della sequenza.
10 <= entry - entry e il valore di confronto è sul lato sbagliato.
entry <= 10 && entry <= 50 - && può essere utilizzato solo per specificare un intervallo con entrambi gli operatori di confronto per il minimo e il massimo valore.

Consenti bandiere mancanti

Quando si inviano richieste al metodo Update per aggiornare un'esistente entrata di dati ordinata, puoi aggiungere un flag opzionale allow_missing per consentire la creazione di un'entrata anche se l'entrata non esiste.

Quando impostate il flag allow_missing a True:

Se l'entrata non esiste, la risposta restituisce una nuova entrata.
Se l'entrata esiste ma il contenuto corrisponde al valore esistente dell'entrata, l'entrata esistente rimane invariata.
Se l'entrata esiste e il contenuto non corrisponde al valore esistente dell'entrata, la risposta restituisce l'entrata con il nuovo valore aggiornato del contenuto.

Su questa pagina