Modelli

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

Percorsi

Per effettuare una richiesta alle API di Open Cloud, devi prima formare un URL. Questo URL è una combinazione dell'URL di base (ad esempio, https://apis.roblox.com), il percorso API di Open Cloud (ad esempio, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), e eventuali parametri di query (ad esempio, ?maxPageSize=25). Un URL completo per la richiesta potrebbe apparire così:

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 graffe nella documentazione dell'API. I parametri di percorso sono semplicemente variabili che inserisci prima di effettuare 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 dei data store e dei memory store supportano un set di caratteri più ampio.

Dimensione e tipo del contenuto

Molti chiamate API, in particolare quelle che creano o aggiornano, richiedono un corpo di richiesta JSON. Se la tua richiesta ha un corpo, assicurati di includere gli header Content-Length e Content-Type. La maggior parte dei client HTTP aggiunge automaticamente questi header.

Paginazione

Se specifichi 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, utilizza quel valore nel parametro pageToken della richiesta successiva per recuperare la pagina successiva. Quando nextPageToken è vuoto o omesso completamente, 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": [
    ...
  ]
}

Oltre al pageToken, devi utilizzare la stessa query affinché la paginazione funzioni correttamente. Alterare qualsiasi parametro di filtro comporta un errore 400.

Open Cloud v2

Percorsi multipli

Alcune risorse hanno più modelli di percorso, visibili sotto l'intestazione Percorsi delle risorse nella documentazione dell'API. Ad esempio, l'URL per Elenca restrizioni utente può essere uno dei seguenti:

• 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 dedurre la differenza tra i due: alcune restrizioni utente si applicano a un'intera università (gioco), mentre altre si applicano a luoghi specifici all'interno di un'università. A parte la piccola aggiunta al percorso e l'ulteriore parametro di percorso, le chiamate sono identiche.

Molti endpoint restituiscono un percorso come parte della loro risposta, che puoi utilizzare per effettuare ulteriori richieste. Se un'API richiede più di qualche secondo per soddisfare una richiesta, spesso restituisce un operazione piuttosto che la risorsa o la risposta stessa.

Operazioni a lungo termine

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

• path - Il percorso dell'endpoint da chiamare per controllare il completamento della richiesta. Aggiungi il percorso all'URL di base originale del metodo della risorsa.
• done - Un valore booleano che rappresenta se l'operazione è completata o meno.
• response - L'oggetto di risposta. Questo campo è vuoto finché il campo done non ha un valore di true.
• metadata - Metadata personalizzati specifici per la richiesta effettuata.

Esempio di oggetto Operation
{
  "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 controllare quando la risorsa è pronta. Una buona strategia è utilizzare il backoff esponenziale. Ad esempio, potresti controllare immediatamente, poi 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 controllo
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logica di ripetizione per controlli successivi
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Backoff esponenziale
            retryPollingDelay *= retryPollingMultiplier
        # Controlla per i risultati e restituisci se esistono
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Altrimenti, incrementa il conteggio dei tentativi
        else:
           currentRetries += 1

Per un esempio di codice più completo che utilizza un intervallo di ripetizione fisso invece del backoff esponenziale, vedi Controlla i risultati.

Filtraggio

Alcuni metodi ti consentono di filtrare la risposta includendo un parametro filter nella richiesta. Le seguenti sezioni descrivono la sintassi del filtro e le linee guida per gli endpoint specificati.

Elenca le appartenenze ai gruppi

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

Il filtraggio è conforme al Common Expression Language (CEL). Solo due operatori sono supportati:

• ==
• in [...]

Se specifichi un ID gruppo nel percorso della risorsa, puoi filtrare le appartenenze per utente o ruolo nei seguenti formati:

• Filtro utente: filter=user == 'users/9876543210'
• Filtro ruolo: filter=role == 'groups/123/roles/7920705'

Se specifichi il carattere jolly per l'ID del gruppo, devi filtrare le appartenenze per utente (fino a 50) nel seguente formato:

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

Elenca gli oggetti inventari

Puoi filtrare per stato collezionabile, tipo di oggetto inventario e ID oggetto inventario. Se non fornisci un filtro, viene restituita l'intera collezione dell'utente.

Il formato del filtro è un elenco separato da punto e virgola:

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

• {field} può essere uno qualsiasi dei campi di tipo predefiniti o dei campi ID nelle seguenti tabelle.
• {value} può essere una stringa, un booleano o un enum. A seconda del tipo di campo, questo può essere un singolo valore (campi booleani) o più valori (campi elenco).

Campi di tipo

Campi ID

Esempi

• Restituisce tutti gli oggetti collezionabili di cui l'utente è proprietario:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Restituisce tutti gli oggetti dei tipi specificati:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Restituisce tutti gli oggetti dei tipi elencati o di qualsiasi pass di gioco. Esclude i distintivi dai risultati (il comportamento è lo stesso di 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, distintivi, 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