Muster | Dokumentation - Roblox Creator Hub

Diese Seite behandelt häufige Muster mit den Open Cloud-APIs, insbesondere um Anfragen zu verarbeiten und Antworten zu verarbeiten.

Wege

Um eine Anfrage an die Open Cloud-API auszuführen, musst du zuerst eine URL erstellen. Diese URL ist eine Kombination aus der Basis-URL ( https://apis.roblox.com/cloud/v2 ) und dem Open Cloud-API-Weg (z. B. /universes/universe-id/places/place-id/user-restraints </


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

Viele Pfade, einschließlich der obigen Beispiel, haben Pfad參數 , die mit Klammern kurz in der API-Referenz gekennzeichnet sind. Pfad參數 sind einfach Variablen, die Sie vor dem Anfrage einfügen und fast immer IDs sind: Benutzer-IDs, Gruppen-IDs, Platz-IDs usw. IDs sind oft numerisch, aber nicht unbedingt; zum Beispiel unterstützen Daten- und Speicher-IDs ein breiteres festlegen.

Einige Ressourcen haben mehrere Pfade, sichtbar unter dem Ressourcen-Pfad-Header in der API-Referenz in der API-Referenz. Zum Beispiel kann die URL für List User Restrictions entweder eines der gefolgte Profilesein:

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

Du kannst den Unterschied zwischen den beiden wahrscheinlich ableiten: einige Benutzer Einschränkungen gelten für ein ganzes Universum (Erlebnis), während andere für bestimmte Orte innerhalb eines Universums gelten. Abgesehen von der kleinen Zugabe zum Pfad und dem zusätzlichen Pfad-Parameter sind die Aufrufe identisch.

Viele APIs geben einen Pfad als Teil ihrer Antwort zurück, den Sie verwenden können, um weitere Anfragen zu erstellen. Wenn eine API mehr als ein paar Sekunden braucht, um eine Anfrage zu erfüllen, kehrt sie oft eine Operation zurück, anstatt der Ressource oder der Antwort selbst.

Inhalt und Typ

Viele API-Aufrufe, insbesondere diejenigen, die Ressourcen erstellen oder aktualisieren, erfordern einen JSON-Anforderungskörper. Wenn Ihre Anfrage einen Körper hat, stellen Sie sicher, dass die Content-Length und Content-Type-Header enthalten sind. Die meisten HTTP-Clients fügen dieseHeader automatisch hinzu.

Pagination

Wenn Sie in Ihrer Anfrage maxPageSize angeben, zeigen einige Methoden paginated Ergebnisse zurück - im Grunde teilweise Antworten:


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

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

Wenn eine Antwort einen Wert für nextPageToken enthält, verwende diesen Wert in der pageToken -Parameter der nächsten Anfrage, um die nächste Seite abzurufen. Wenn nextPageToken leer ist, hast du das Ende deiner Ergebnisse erreicht:


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

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

Abgesehen von der pageToken , musst du die gleiche Anfrage für die Pagination verwenden, damit sie richtig funktioniert. Ändern Sie irgendeinen Filter-Parameter-Ergebnis in einem 400-Fehler.

Lange ausgeführte Operationen

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

path - Der Endpfad, um die Anforderung abzurufen. Fügen Sie den Pfad zur ursprünglichen Basis URL des Anfragehinzu.
done - EinBoolean-Wert, der angibt, ob die Operation abgeschlossen ist oder nicht.
Antwort - Die Antwort-Objekt. Dieses Feld ist leer, bis das Feld done eine Wert von true hat.
Metadaten: - Benutzerdefinierte Metadaten, spezifisch für die Anfrage, die gemacht wird.

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

Verwenden Sie den Pfad des Objekts Operation , um nach dem Bereitstellen des Ressourcen zu pollen, wenn die Ressource bereit ist. Eine gute Strategie ist es, exponentialen Backoff zu verwenden. Zum Beispiel können Sie sofort pollen, 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 überprüfen
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logik für spätere Prüfungen erneut versuchen
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Exponentialer Rückstoß
            retryPollingDelay *= retryPollingMultiplier
        # Ergebnisse prüfen und zurückgeben, wenn sie vorhanden sind
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Andernfalls erhöhen Sie die Anzahl der Wiederholungen
        else:
           currentRetries += 1

Für ein komplettes Beispiel für einen Code, der eine feste Wiederholungsintervall verwendet, anstatt exponenziell zurückzukehren, siehe Polling for Results.

Filtern

Einige Methoden ermöglichen es Ihnen, die Antwort zu filtern, indem ein filter -Parameter in der Anfrage enthalten ist. Die folgenden Abschnitte beschreiben die FilterSyntax und die Richtlinien für die angegebenen Endpunkte.

Listen Gruppenmitgliedschaften

Der Wildcard-Charakter - kann in der Gruppe ID verwendet werden, um Mitgliedschaften in allen Gruppen aufzulisten: groups/-/memberships.

Filterung entspricht Common Expressions Language (CEL). Nur zwei Operatoren werden unterstützt:

==
in [...]

Wenn Sie eine Gruppen-ID in den Ressourcen-pfad eingeben, können Sie Mitgliedschaften entweder nach Benutzer oder Rolle in der folgenden Form filtern:

Benutzerfilter : filter="user == 'users/9876543210'"
Rolle-Filter : filter="role == 'groups/123/roles/7920705'"

Wenn Sie den Wildcard-Charakter für die Gruppen-ID angeben, müssen Sie Mitglieder nach Benutzer (bis zu 50) im folgenden Format filtern:

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

Inventar-Items anzeigen

Du kannst nach Sammelbar-Status, eingebenund Inventar-Item-ID filtern. Wenn du keinen Filter bereitstellst, wird das gesamte Inventar des Benutzers zurückgegeben.

Das Filterformat ist eine semikolon-getrennte Liste:

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

{field} kann eine der vordefinierten Typ-Felder oder ID-Felder in den folgenden Tabellen sein.
{value} kann eine String, einenBoolean oder ein Enumer sein. Abhängig vom eingebenkann dies ein einzelnes Wert (Boolean-Felder) oder mehrere Werte (Liste-Felder) sein.

Du kannst keine Felder von Typ und ID in demselben Filter kombinieren.

Typen Felder

ID-Felder

| Filter | Ty

Beispiele

Kehre alle sammelbaren Elemente zurück, die der Benutzer besitzt:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Rückgibt alle Elemente der angegebenen Typen zurück:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Gibt alle Elemente der aufgelisteten Arten oder Spielpässe zurück. Exkludiert Abzeichen aus den Ergebnissen (das gleiche Verhalten wie wenn badges nicht in den Filtern enthalten war):

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Rückgibt Assets, die den angegebenen IDs entsprechen:

filter=assetIds=1,2,3,4
Rückgibt Assets, Abzeichen, Spielpässe und private Server, die die angegebenen IDs übereinstimmen:

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