Patmuster

Diese Seite deckt häufige Muster mit den Open Cloud-APIs ab, insbesondere rund um das Stellen von Anfragen und das Bearbeiten von Antworten.

Wege

Um eine Anfrage an die Open Cloud-APIs zu stellen, musst du zuerst eine URL bilden.Diese URL ist eine Kombination der Basis-URL ( https://apis.roblox.com/cloud/v2 ), des Open Cloud API-Weges (zum Beispiel, /universes/{universe_id}/places/{place_id}/user-restrictions ), und aller Suchparameter (zum Beispiel, ?maxPageSize=25 ).Eine vollständige Anforderungs-URL könnte wie folgt aussehen:


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

Viele Wege, einschließlich des Beispiels oben, haben Weg参数 , die durch kurvige Klammern in der API-Referenz benannt werden.Weg参数 sind nur Variablen, die Sie einfügen, bevor Sie die Anfrage stellen, und sind fast immer IDs: Benutzer-IDs, Gruppen-IDs, Platz-IDs usw.IDs sind oft numerisch, aber nicht unbedingt; zum Beispiel unterstützen Datenlagers- und Speicherlagers-IDs ein breiteres festlegen.

Einige Ressourcen haben mehrere Pfadmuster, die im Ressourcenpfad-Header der API-Referenz sichtbar sind.Zum Beispiel kann die URL für Listen-Benutzeinschränkungen 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 wahrscheinlich den Unterschied zwischen den beiden herausfinden: Einige Benutzeinschränkungen gelten für ein ganzes Universum (Erlebnis), während andere für bestimmte Orte innerhalb eines Universums gelten.Abgesehen von der kleinen Ergänzung des Weges und des zusätzlichen Weg parameters sind die Anrufe identisch.

Viele APIs geben einen Pfad als Teil ihrer Antwort zurück, den du verwenden kannst, um weitere Anfragen zu stellen.Wenn eine API mehr als ein paar Sekunden benötigt, um eine Anforderung zu erfüllen, gibt sie oft eine Operation zurück, anstatt die Ressource oder die Antwort selbst.

Länge und eingebendes Inhalts

Viele API-Aufrufe, insbesondere diejenigen, die Ressourcen erstellen oder aktualisieren, erfordern einen JSON-Anforderungskörper.Wenn deine Anfrage einen Körper hat, stelle sicher, die Content-Length- und Content-Type-Header einzuschließen.Die meisten HTTP-Clients fügen diese Header automatisch hinzu.

Paginierung

Wenn du maxPageSize in deiner Anfrage angibst, geben einige Methoden paginierte Ergebnisse zurück - im Wesentlichen teilweise 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, verwende diesen Wert im pageToken -Parameter der nachfolgenden Anfrage, um die nächste Seite abzurufen.Wenn nextPageToken leer oder vollständig übersprungen wird, hast du das Ende deiner 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 von der pageToken, musst du die gleiche Abfrage verwenden, damit die Paginierung ordnungsgemäß funktioniert. Ändern von irgendeinem Filterparameter führt zu einem 400-Fehler.

Lange laufende Operationen

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

Weg - Der Endpunkt-Weg, um zur Abfrage des Abschlusses der Anfrage zu rufen. Füge den Weg zur ursprünglichen Basis-URL der Ressourcenmethode hinzu.
fertig - Ein boolescher Wert, der darstellt, ob die Operation abgeschlossen ist oder nicht.
Antwort - Das Objekt. Dieses Feld ist leer, bis das Feld done einen Wert von true hat.
Metadaten - Benutzerdefinierte Metadaten, die spezifisch für die angeforderte Anfrage sind.

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

Verwende den Pfad des Operation Objekts, um abzustimmen, wann die Ressource bereit ist.Eine gute Strategie ist es, exponentielle Zurücknahme zu verwenden.Zum Beispiel könnten Sie sofort abstimmen, 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 erneut verwenden für nachfolgende Überprüfungen
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Exponentialer Rückgang
            retryPollingDelay *= retryPollingMultiplier
        # Ergebnisse prüfen und zurückgeben, wenn sie vorhanden sind
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Sonst erhöhe die Wiederholungsanzahl
        else:
           currentRetries += 1

Für ein vollständigeres Codebeispiel, das einen festen Wiederholungsintervall verwendet, anstatt exponentielle Rückkehr, siehe Umfrage für Ergebnisse.

Filterung

Einige Methoden lassen dich die Antwort filtern, indem du einen filter -Parameter in die Anfrage einfügst.Die folgenden Abschnitte beschreiben die Filter syntax und Richtlinien für die angegebenen Endpunkte.

Gruppenmitgliedschaften listen

Der Platzhaltercharakter - kann verwendet werden, um Mitgliedschaften in allen Gruppen aufzulisten: groups/-/memberships.

Die Filterung entspricht dem gemeinsamen Ausdruckssprache (CEL). Nur zwei Operatoren werden unterstützt:

==
in [...]

Wenn du eine Gruppen-ID im Ressourcenpfad spezifizierst, kannst du Mitgliedschaften nach Benutzer oder Rolle in den folgenden Formaten filtern:

Benutzerfilter : filter="user == 'users/9876543210'"
Rollenfilter : filter="role == 'groups/123/roles/7920705'"

Wenn du den Wildcard-Zeichen für die Gruppen-ID spezifizierst, musst du die Mitgliedschaften des Benutzers (bis zu 50) im folgenden Format filtern:

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

Inventarartikel listen

Du kannst nach Status, Inventarartikeltyp und Inventarartikel-ID filtern.Wenn du keinen Filter bereitstellst, wird das gesamte Inventar des Benutzers zurückgegeben.

Das Filterformat ist eine semikolon-separierte Liste:

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

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

Du kannst nicht Type- und ID-Felder im selben Filter kombinieren.

Feldarten eingeben

| Filter | Typ | Beschreibung | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolesches | Füge Abzeichen in die Antwort ein.Standard ist falsch. | | gamePasses | boolesisch | Füge Spielpässe in die Antwort ein.Standard ist falsch. | | inventoryItemAssetTypes | Siehe assetDetails für die volle Liste der Asset-Typen.| Kommaseperierte Liste der Asset-Typen, die enthalten sein sollen.Standard ist nichts.Geben Sie * für alle Asset-Typen an.Muss Inventarlesbarkeitsbereich haben, um nach gekauften Orten zu filtern. | | onlyCollectibles | boolean | Füge nur Sammlerstücke in die Antwort ein.Standard ist falsch.Dieses Feld muss mit dem Feld inventoryItemAssetTypes verwendet werden, um Artikel zurückzugeben und nur nicht-UGC-begrenzte Artikel zurückzugeben.| | privateServers | boolean | Private Server in die Antwort einbeziehen.Standard ist falsch.Muss Inventarlesbarkeitsbereich haben, um nach diesem Feld zu filtern. |

Identitätsfelder

Beispiele

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

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Gibt alle Elemente der angegebenen Arten zurück:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Gibt alle Artikel der aufgelisteten Arten oder alle Spielpässe zurück.Schließt Abzeichen aus den Ergebnissen aus (gleiches Verhalten wie wenn badges nicht im Filter enthalten war):

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

Auf dieser Seite