Modelli

Questa pagina tratta i modelli comuni con le API Open Cloud, in particolare attorno alla creazione di richieste e alla gestione delle risposte.

Percorsi

Per fare una richiesta alle API Open Cloud, devi prima formare un URL.Questo URL è una combinazione del URL di base ( https://apis.roblox.com/cloud/v2 ), del percorso Open Cloud API (ad esempio, /universes/{universe_id}/places/{place_id}/user-restrictions ), e di qualsiasi parametro di query (ad esempio, ?maxPageSize=25 ).Un URL di richiesta completo potrebbe sembrare questo:


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Molti percorsi, incluso l'esempio sopra, hanno parametri di percorso , designati da parentesi curly nella riferenza dell'API.I parametri del percorso sono solo variabili che inserisci prima di fare la richiesta e sono quasi sempre ID: ID utente, ID gruppo, ID luogo, ecc.Gli ID sono spesso numerici, ma non necessariamente; ad esempio, gli ID del deposito di dati e del deposito di memoria supportano un Impostaredi caratteri più ampio.

Alcune risorse hanno più modelli di percorso visibili sotto l'intestazione Percorsi risorsa nella riferenza API.Ad esempio, l'URL per List User Restrictions 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

Probabilmente puoi 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 l'aggiunta piccola al percorso e al parametro percorso 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 qualche secondo per soddisfare una Richiesta, spesso restituisce un'operazione invece della risorsa o della risposta stessa.

Lunghezza e inserisci / scrividel 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 headers.La maggior parte dei client HTTP aggiunge questi headers automaticamente.

Paginazione

Se specifici maxPageSize nella tua Richiesta, alcuni metodi restituiscono risultati paginati - essenzialmente risposte parziali:


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

Se una risposta include un valore per nextPageToken , usa quel valore nel parametro pageToken della richiesta successiva per recuperare la pagina successiva.Quando nextPageToken è vuoto o viene omesso del tutto, hai raggiunto la fine dei tuoi risultati:


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

A parte il pageToken, devi usare la stessa query per la paginazione per funzionare correttamente. Modificare qualsiasi parametro del filtro comporta un errore 400.

Operazioni di lunga esecuzione

Alcuni metodi restituiscono un oggetto Operation che rappresenta una richiesta in esecuzione a lungo termine che restituisce una risposta asincrona in seguito.L'oggetto contiene i seguenti campi:

percorso - Il percorso finale per chiamare il completamento della Richiesta. Aggiungi il percorso alla URL originale del metodo della 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.

Esempio oggetto 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 è utilizzare il ritiro 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 sulla prima Controllare /Verificare
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Riprova la logica per i controlli successivi
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Ritiro esponenziale
            retryPollingDelay *= retryPollingMultiplier
        # Verifica i risultati e restituisci se esistono
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Altrimenti, aumenta il conteggio di riprova
        else:
           currentRetries += 1

Per un esempio di codice più completo che utilizza un intervallo di riprova fisso piuttosto che un ritiro esponenziale, vedi Poll per i risultati.

Filtraggio

Alcuni metodi ti consentono di filtrare la risposta includendo un parametro filter nella Richiesta.Le seguenti sezioni descrivono la sintassi dei filtri e le linee guida per i punti finali specificati.

Elenca le adesioni al gruppo

Il carattere jolly - può essere utilizzato invece dell'ID del gruppo per elencare le adesioni in tutti i gruppi: groups/-/memberships .

Il filtraggio rispetta il Common Expression Language (CEL). Sono supportati solo due operatori:

==
in [...]

Se specifici un ID gruppo nel percorso risorse, puoi filtrare le membership in base a utente o ruolo nei seguenti formati:

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 membership dell'utente (fino a 50) nel seguente formato:

Filtro utente : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

Elenca gli oggetti dell'inventario

Puoi filtrare per stato di Stato, inserisci / scrividi oggetto inventario e ID oggetto inventario.Se non fornisci un Filtro, viene restituito l'intero inventario dell'utente.

Il formato del filtro è una lista separata da virgola:

filter={field}={value};{field}={value},{value},...;{field}=...

{field} può essere uno qualsiasi dei campi di tipo predefinito o ID nei seguenti tabelle.
{value} può essere una Stringa, booleano o enum.A seconda del inserisci / scrividi campo, questo può essere un singolo valore (campi booleani) o più valori (campi di lista).

Non puoi combinare i campi di tipo e ID nello stesso Filtro.

Campi di tipo

| Filtro | Tipo | Descrizione - | :------------------------ | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- - | | badges | boolean | Includi badge nella risposta.Il predefinito è falso. | | gamePasses | booleano | Includi pass di gioco nella risposta.Il predefinito è falso. | | inventoryItemAssetTypes | Vedi dettagli delle risorse per l'intera lista di tipi di risorse.| Lista separata per commi dei tipi di risorsa da includere.Il predefinito è nessuno.Specifica * per tutti i tipi di risorsa.Deve avere la scala di lettura dell'inventario per filtrare per posti acquistati. | | onlyCollectibles | boolean | Includi solo oggetti da collezione nella risposta.Il predefinito è falso.Questo campo deve essere utilizzato con il campo inventoryItemAssetTypes per restituire oggetti e restituisce solo oggetti limitati non UGC.| | privateServers | booleano | Includi server privati nella risposta.Il predefinito è falso.Deve avere una scala di lettura dell'inventario per filtrare da questo campo. |

Campi ID

Esempi

Restituisce tutti gli oggetti collezionabili che l'utente possiede:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Restituisce tutti gli elementi di tipo specificato:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Restituisce tutti gli elementi dei tipi elencati o di qualsiasi pass di gioco.Esclude i badge dai risultati (lo stesso comportamento 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

Su questa pagina