Wzory

Ta strona obejmuje powszechne wzory z interfejsami API chmury otwartej, w szczególności wokół wysyłania żądań i przetwarzania odpowiedzi.

Ścieżki

Aby złożyć wniosek do otwartych API chmury, musisz najpierw utworzyć URL.Ta URL to kombinacja podstawowego URL (), ścieżki Open Cloud API (na przykład, 》) i dowolnych parametrów zapytania (na przykład, 》).Pełny URL żądania może wyglądać tak:


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

Wiele ścieżek, w tym przykład powyżej, ma parametry ścieżki , oznaczone kropkami w nawiasach w odniesieniu do API.Parametry ścieżki są tylko zmiennymi, które wpisujesz przed złożeniem żądania i są prawie zawsze identyfikatorami: ID użytkownika, ID grupy, ID miejsca itp.ID są często liczbowe, ale niekoniecznie; na przykład, ID przechowywania danych i przechowywania pamięci wspierają szerszy ustawiać.

Niektóre zasoby mają wiele wzorców ścieżki widocznych pod nagłówkiem Ścieżki zasobów w referencji API.Na przykład URL dla Ograniczeń użytkownika listy może być jednym z obserwuje:

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

Prawdopodobnie możesz wywnioskować różnicę między tymi dwoma: niektóre ograniczenia użytkownika dotyczą całego wszechświata (doświadczenia), podczas gdy inne dotyczą konkretnych miejsc w wszechświecie.Oprócz małego dodatku do ścieżki i dodatkowego parametru ścieżki wezwania są identyczne.

Wiele interfejsów powrotnych zwraca ścieżkę jako część swojej odpowiedzi, którą możesz użyć do składania kolejnych żądań.Jeśli API potrzebuje więcej niż kilku sekund na wypełnienie prośba, często zwraca operację operację zamiast zasobu lub samej odpowiedzi.

Długość i wpisywaćtreści

Wiele wezwań API, w szczególności te, które tworzą lub aktualizują zasoby, wymaga ciała żądania JSON.Jeśli twoja prośba ma ciało, upewnij się, że zawiera nagłówki Content-Length i Content-Type.Większość klientów HTTP dodaje te nagłówki automatycznie.

Paginacja

Jeśli określisz maxPageSize w swojej prośba, niektóre metody zwracają wyniki paginowane - zasadniczo częściowe odpowiedzi:


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

Jeśli odpowiedź zawiera wartość dla nextPageToken, użyj tej wartości w parametrze pageToken następnej prośby, aby odzyskać następną stronę.Gdy nextPageToken jest puste lub całkowicie pominięte, dotarłeś do końca wyników:


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

Oprócz pageToken, musisz używać tej samej zapytania do prawidłowego działania pagerowania. Zmiana dowolnego parametru filtra powoduje błąd 400.

Długie operacje wykonawcze

Niektóre metody zwracają obiekt Operation, który reprezentuje długo biegnącą prośbę, która zwraca synchroniczną odpowiedź później.Obiekt zawiera następujące pola:

ścieżka - Ścieżka końcowa do wezwania, aby zapytać o zakończenie prośba. Dodaj ścieżkę do oryginalnej URL bazowej metody zasobu.
gotowe - wartość binarna, która reprezentuje, czy operacja została zakończona, czy nie.
odpowiedź - Obiekt odpowiedzi. To pole jest puste, dopóki pole done nie będzie miało wartości true.
metadata - Własne metadane specyficzne dla żądania, które jest wysyłane.

Przykładowy obiekt operacji
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Użyj ścieżki obiektu Operation, aby zapytać, kiedy zasób będzie gotowy.Dobrą strategią jest wykorzystanie wykładniczego odwrotu.Na przykład możesz zapytać bezpośrednio, a następnie po jednej sekundzie, dwie sekundy, cztery sekundy itd.


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Brak opóźnienia przy pierwszej sprawdzać
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Spróbuj ponownie logiki dla kolejnych kontroli
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Eksponencjalny backoff
            retryPollingDelay *= retryPollingMultiplier
        # Sprawdź wyniki i wróć, jeśli istnieją
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # W przeciwnym razie zwiększ liczbę prób ponownego wykonania
        else:
           currentRetries += 1

Aby uzyskać bardziej kompletny przykład kodu, który wykorzystuje stały odcinek prób odnowienia zamiast wykładniczego odwrotu, zobacz Głosuj o wynikach.

Filtrowanie

Niektóre metody pozwalają filtrować odpowiedź poprzez dodanie parametru filter w prośba.Następujące sekcje opisują słownik słowa filtrowania i wytyczne dla określonych punktów końcowych.

Lista członkostw grupy

Znak dzikiej karty - może być użyty w miejsce identyfikatora grupy, aby wymienić członkostwa wśród wszystkich grup: groups/-/memberships .

Filtracja zgodna jest z Wspólnym językiem wyrażeń (CEL). Wspierane są tylko dwa operatorzy:

==
in [...]

Jeśli określisz identyfikator grupy w ścieżce zasobów, możesz filtrować członkostwa za pomocą użytkownika lub roli w następujących formatach:

Filtr użytkownika : filter="user == 'users/9876543210'"
Filtr roli : filter="role == 'groups/123/roles/7920705'"

Jeśli określisz znak dzikiej karty dla identyfikatora grupy, musisz filtrować członkostwa przez użytkownika (do 50) w następującym formacie:

Filtr użytkownika : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

Wyświetl przedmioty z ekwipunku

Możesz filtrować według statusu kolekcjonerskiego, wpisywaćprzedmiotu eksploatacyjnego i ID przedmiotu eksploatacyjnego.Jeśli nie dostarczysz filtra, cały zapas użytkownika zostanie zwrócony.

Format filtra to lista oddzielona przecinkami:

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

{field} może być dowolnym z predefiniowanych pól typu lub pól ID w następujących tabelach.
{value} może być ciągiem, prawdziwym lub wartością wymienną.W zależności od wpisywaćpola może to być pojedyncza wartość (pola booleanowe) lub wiele wartości (pola listy).

Nie możesz łączyć pól typu i ID w tym samym filtrze.

Pola typu

| Filtruj | Typ | Opis | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Dodaj odznaki do odpowiedzi.Domyślnie jest fałszywy. | | gamePasses | boolean | Dodaj game pasy do odpowiedzi.Domyślnie jest fałszywy. | | inventoryItemAssetTypes | Zobacz szczegóły aktywów dla pełnej listy rodzajów aktywów.| Rozdzielona przecinkami lista typów zasobów do uwzględnienia.Domyślny jest żaden.Określ * dla wszystkich typów zasobów.Musi mieć zakres odczytu zapasu, aby filtrować przez zakupione miejsca. | | onlyCollectibles | boolean | Dodaj tylko pamiątek w odpowiedzi.Domyślnie jest fałszywy.To pole musi być używane z polem inventoryItemAssetTypes w celu zwrotu przedmiotów i zwraca tylko ograniczone przedmioty nie-UGC.| | privateServers | boolean | Włącz prywatne serwery w odpowiedź.Domyślnie jest fałszywy.Musi mieć zakres odczytu zapasu, aby filtrować przez to pole. |

Pola identyczne

Przykłady

Zwraca wszystkie przedmioty kolekcjonerskie, które użytkownik posiada:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Zwraca wszystkie przedmioty określonych typów:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Zwraca wszystkie przedmioty z listy typów lub jakiekolwiek przepustki do gry.Wyklucza odznaki z wyników (takie same zachowanie, jak gdyby badges nie zostało uwzględnione w filtrze):

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Zwraca zasoby, które pasują do określonych ID:

filter=assetIds=1,2,3,4
Zwraca zasoby, odznaki, game pasy i prywatne serwery, które pasują do określonych identyfikatorów:

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

Na tej stronie