Questa pagina tratta i modelli comuni con le API Open Cloud, in particolare intorno alla creazione di richieste e gestione delle risposte.
Percorsi
Per fare una richiesta alle API Open Cloud, devi prima formare un URL. Questo URL è una combinazione di base URL ( https://apis.roblox.com/cloud/v2 ) e la strada Open Cloud API (per esempio, /universes/{universe-id}/places/{place-id}/user-restrictions ) e tutti i parametri di rich
Molti percorsi, tra cui l'esempio sopra, hanno parametri di percorso , designati da curly brackets nella riferimento API. I parametri di percorso sono solo variabili che inserisci prima di fare la richiesta e sono quasi sempre ID: ID utente, gruppi, luoghi, ecc. ID sono spesso numerici, ma non necessariamente; ad esempio, i dati di archiviazione e il server di memoria supportano un più ampio Impostaredi caratteri.
Alcune risorse hanno più modelli di percorso, visibili sotto l'頭 del Percorsi risorse titolo nella riferimento API. Ad esempio, l'URL per Limitazioni di Lista può essere uno dei Seguendo:
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/user-restrictions
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/places/{place-id}/user-restrictions
Puoi probabilmente inferire la differenza tra i due: alcune restrizioni dell'utente si applicano a un intero universo (esperienza), mentre altre si applicano a luoghi specifici all'interno di un universo. A parte la piccola aggiunta al parametro del percorso e della strada extra, le chiamate sono identiche.
Molte API restituiscono un percorso come parte della loro risposta, che puoi utilizzare per fare ulteriori richieste. Se un'API ha bisogno di più di pochi secondi per soddisfare una Richiesta, di solito restituisce un operazione invece che la risorsa o la risposta stessa.
Lunghezza e tipo del contenuto
Molte chiamate API, in particolare quelle che creano o aggiornano risorse, richiedono un corpo di richiesta JSON. Se la tua richiesta ha un corpo, assicurati di includere i Content-Length e Content-Type header. La maggior parte dei client HTTP aggiunge automaticamente questi header.
Paginazione
Se specifici maxPageSize nella tua Richiesta, alcuni metodi restituiscono risposte pagate: essenzialmente risposte parziali:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25
{
"inventoryItems": [
...
],
"nextPageToken": "aaaBBB"
}
Se una risposta include un valore per nextPageToken , usa quel valore nel parametro pageToken della richiesta successiva per recuperare la prossima pagina. Quando nextPageToken è vuoto, hai raggiunto la fine dei tuoi risultati:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB
{
"inventoryItems": [
...
],
"nextPageToken": ""
}
Oltre alla pageToken , devi utilizzare la stessa query per la pagination per funzionare correttamente. L'alterazione di qualsiasi parametro di filtro risulta in un errore 400.
Operazioni a lungo eseguite
Alcuni metodi restituiscono un oggetto Operation che rappresenta una richiesta in esecuzione a lungo che restituisce una risposta asincrona più tardi. L'oggetto contiene i seguenti campi:
- path - La strada di destinazione per chiamare per la completazione della Richiesta. Aggiungi la strada all'URL di base originale del metodo risorsa.
- fatto - Un valore booleano che rappresenta se l'operazione è stata completata o meno.
- risposta - L'oggetto di risposta. Questo campo è vuoto fino a quando il campo done non ha un valore di true .
- metadata - Metadati personalizzati specifici per la richiesta in corso.
Objeto di esempio di operazione
{
"path": "v1/assets/12345/operation/xyz",
"done": true,
"response": {
"value1": "myValue",
"value2": 1234
},
"metadata": {
"metadata1": "string",
"metadata2": 5678
}
}
Usa il percorso dell'oggetto Operation per votare quando la risorsa è pronta. Una buona strategia è usare l'esuberanza esponenziale. Ad esempio, potresti votare immediatamente, quindi dopo un secondo, due secondi, quattro secondi, ecc.
def PollForResults(operationPath):
currentRetries = 0
maxRetries = 10
retryPollingDelay = 1
retryPollingMultiplier = 2
while (currentRetries < maxRetries):
# Nessun ritardo sul primo Controllare /Verificare
if (currentRetries == 0):
results = GetOperation(operationPath)
# Riprova la logica per i successivi controlli
else:
time.sleep(retryPollingDelay)
results = GetOperation(operationPath)
# Ritorno esponenziale
retryPollingDelay *= retryPollingMultiplier
# Controlla i risultati e restituisci se esistono
if (results.status_code != 200 or results.json()[doneJSONKey]):
return results
# Altrimenti, aumenta il numero di tentativi
else:
currentRetries += 1
Per un esempio di codice più completo che utilizza un intervallo di riprova fisso invece che l'esponenziale backoff, vedi Polling for Results .
Filtraggio
Alcuni metodi ti consentono di filtrare la risposta includendo un filter parametro nella Richiesta. Le seguenti sezioni descrivono la sintassi e le linee guida per i punti di fine specificati.
Elenca i membri del gruppo
Il carattere wildcard - può essere utilizzato invece dell'ID del gruppo per elencare le iscrizioni in tutti i gruppi: groups/-/memberships .
La filtro si conforma alla CommonExpressionLanguage (CEL). Sono supportati solo due operatori:
- ==
- in [...]
Se specifici un ID di gruppo nel percorso delle risorse, puoi filtrare le iscrizioni in base all'utente o al ruolo nel seguente formato:
- Filtro utente : filter="user == 'users/9876543210'"
- Filtro ruolo : filter="role == 'groups/123/roles/7920705'"
Se specifici il carattere wildcard per l'ID del gruppo, devi filtrare le iscrizioni degli utenti (fino a 50) nel seguente formato:
- Filtro utente : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"
Elenca oggetti inventario
Puoi filtrare in base allo stato di Stato, al inserisci / scrividi oggetto dell'inventario e all'ID dell'oggetto dell'inventario. Se non fornisci un Filtro, l'intero inventario dell'utente viene restituito.
Il formato del filtro è una lista separata da un semicollo:
filter={field}={value};{field}={value},{value},...;{field}=...
- {field} può essere qualsiasi campo di tipo predefinito o campo ID nelle seguenti tabelle.
- {value} può essere una Stringa, un booleano o un elenco. A seconda del inserisci / scrividi campo, questo può essere un singolo valore (Campi di tipo booleano) o più valori (Campi di tipo di elenco).
Non puoi combinare i campi di tipo e ID nella stessa Filtro.
Tipi di Campi
| Filter | Type | Description | | :---------------- | : | | : | | badges
Campi ID
| Filtro | Tipo | Descrizione | | :----------------- | :إلى | :
Esempi
Restituisce tutti gli oggetti collezionabili che l'utente possiede:
filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Restituisce tutti gli elementi dei tipi specificati:
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Restituisce tutti gli elementi dei tipi elencati o qualsiasi gamepass. Escludere i badge dai risultati (lo stesso comportamento come se badges non fosse incluso nel Filtro):
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Restituisce risorse che corrispondono agli ID specificati:
filter=assetIds=1,2,3,4
Restituisce risorse, badge, pass di gioco e server privati che corrispondono agli ID specificati:
filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4