Muster

Diese Seite behandelt gängige Muster mit den Open Cloud APIs, insbesondere im Hinblick auf das Stellen von Anfragen und den Umgang mit Antworten.

Pfade

Um eine Anfrage an die Open Cloud APIs zu stellen, müssen Sie zuerst eine URL bilden. Diese URL ist eine Kombination aus der Basis-URL (z. B. https://apis.roblox.com), dem Open Cloud API-Pfad (zum Beispiel /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions) und allen Abfrageparametern (zum Beispiel ?maxPageSize=25). Eine vollständige Anfrage-URL könnte folgendermaßen aussehen:

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

Viele Pfade, einschließlich des obigen Beispiels, haben Pfadparameter, die in der API-Referenz durch geschweifte Klammern gekennzeichnet sind. Pfadparameter sind einfach Variablen, die Sie vor dem Stellen der Anfrage einsetzen, und sind fast immer IDs: Benutzer-IDs, Gruppen-IDs, Platz-IDs usw. IDs sind oft numerisch, aber nicht unbedingt; zum Beispiel unterstützen Datenstore- und Speicherstore-IDs einen breiteren Zeichensatz.

Inhaltlänge und -typ

Viele API-Aufrufe, insbesondere solche, die erstellen oder aktualisieren, erfordern einen JSON-Anforderungstext. Wenn Ihre Anfrage einen Text hat, stellen Sie sicher, dass Sie die Header Content-Length und Content-Type einfügen. Die meisten HTTP-Clients fügen diese Header automatisch hinzu.

Pagination

Wenn Sie maxPageSize in Ihrer Anfrage angeben, geben einige Methoden paginierte Ergebnisse zurück - im Grunde genommen partielle Antworten:

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"
}

Wenn eine Antwort einen Wert für nextPageToken enthält, verwenden Sie diesen Wert im pageToken-Parameter der nachfolgenden Anfrage, um die nächste Seite abzurufen. Wenn nextPageToken leer oder ganz weggelassen ist, haben Sie das Ende Ihrer Ergebnisse erreicht:

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": [
    ...
  ]
}

Abgesehen vom pageToken müssen Sie die gleiche Abfrage für die Seitenanpassung verwenden, damit sie richtig funktioniert. Änderungen an einem Filterparameter führen zu einem 400-Fehler.

Open Cloud v2

Mehrere Pfade

Einige Ressourcen haben mehrere Pfadmuster, die unter der Überschrift Resource Paths in der API-Referenz sichtbar sind. Zum Beispiel kann die URL für List User Restrictions einer der folgenden sein:

• 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

Sie können wahrscheinlich den Unterschied zwischen den beiden ableiten: Einige Benutzerbeschränkungen gelten für ein gesamtes Universum (Spiel), während andere für spezifische Orte innerhalb eines Universums gelten. Abgesehen von der kleinen Ergänzung zum Pfad und dem zusätzlichen Pfadparameter sind die Aufrufe identisch.

Viele Endpunkte geben einen Pfad als Teil ihrer Antwort zurück, den Sie zur Durchführung weiterer Anfragen nutzen können. Wenn eine API länger als ein paar Sekunden benötigt, um eine Anfrage zu erfüllen, gibt sie häufig eine Operation zurück, anstatt die Ressource oder die Antwort selbst.

Lang laufende Operationen

Einige Methoden geben ein Operation-Objekt zurück, das eine lang laufende Anfrage darstellt, die später eine asynchrone Antwort zurückgibt. Das Objekt enthält folgende Felder:

• path - Der Endpunktpfad, den Sie aufrufen müssen, um den Abschluss der Anfrage zu überprüfen. Fügen Sie den Pfad zur ursprünglichen Basis-URL der Ressourcenmethode hinzu.
• done - Ein boolescher Wert, der angibt, ob die Operation abgeschlossen ist oder nicht.
• response - Das Antwortobjekt. Dieses Feld ist leer, bis das Feld done den Wert true hat.
• metadata - Benutzerdefinierte Metadaten, die spezifisch für die ausgeführte Anfrage sind.

Beispiel Operation Object
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Verwenden Sie den Pfad des Operation-Objekts, um zu überprüfen, wann die Ressource bereit ist. Eine gute Strategie ist es, exponentielles Backoff zu verwenden. Zum Beispiel könnten Sie sofort prüfen, dann nach einer Sekunde, zwei Sekunden, vier Sekunden usw.

def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Keine Verzögerung beim ersten Check
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Wiederholungslogik für nachfolgende Checks
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Exponentielles Backoff
            retryPollingDelay *= retryPollingMultiplier
        # Überprüfen Sie die Ergebnisse und geben Sie sie zurück, wenn sie vorhanden sind
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Andernfalls erhöhen Sie die Wiederholungsanzahl
        else:
           currentRetries += 1

Für ein vollständigeres Codebeispiel, das ein festes Wiederholungsintervall anstelle von exponentiellem Backoff verwendet, siehe Poll for results.

Filtern

Einige Methoden ermöglichen es Ihnen, die Antwort zu filtern, indem Sie einen filter-Parameter in die Anfrage aufnehmen. Die folgenden Abschnitte beschreiben die Filter-Syntax und Richtlinien für die angegebenen Endpunkte.

List Group Memberships

Das Platzhaltersymbol - kann anstelle einer Gruppen-ID verwendet werden, um Mitgliedschaften in allen Gruppen aufzulisten: groups/-/memberships.

Filtern erfolgt gemäß der Common Expression Language (CEL). Nur zwei Operatoren werden unterstützt:

• ==
• in [...]

Wenn Sie eine Gruppen-ID im Ressourcenpfad angeben, können Sie Mitgliedschaften entweder nach Benutzer oder Rolle in den folgenden Formaten filtern:

• Benutzerfilter: filter=user == 'users/9876543210'
• Rollendfilter: filter=role == 'groups/123/roles/7920705'

Wenn Sie das Platzhaltersymbol für die Gruppen-ID angeben, müssen Sie Mitgliedschaften nach Benutzer (bis zu 50) im folgenden Format filtern:

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

List Inventory Items

Sie können nach dem Sammlungsstatus, dem Typ des Inventarobjekts und der ID des Inventarobjekts filtern. Wenn Sie keinen Filter bereitstellen, wird das gesamte Inventar des Benutzers zurückgegeben.

Das Filterformat ist eine durch Semikolons getrennte Liste:

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

• {field} kann eines der vordefinierten Typfelder oder ID-Felder in den folgenden Tabellen sein.
• {value} kann ein Zeichenfolge, boolesch oder Enum sein. Abhängig vom Typ des Feldes kann dies ein einzelner Wert (boolesche Felder) oder mehrere Werte (Listenfelder) sein.

Typfelder

ID-Felder

Beispiele

• Gibt alle Sammlerstücke zurück, die der Benutzer besitzt:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Gibt alle Artikel der angegebenen Typen zurück:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Gibt alle Artikel der aufgeführten Typen oder beliebige Spielpässe zurück. Schließt Abzeichen aus den Ergebnissen aus (das gleiche Verhalten, als ob badges nicht im Filter enthalten wäre):

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Gibt Assets zurück, die den angegebenen IDs entsprechen:

  filter=assetIds=1,2,3,4

• Gibt Assets, Abzeichen, Spielpässe und private Server zurück, die den angegebenen IDs entsprechen:

  filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4