Ta strona pokrywa częste wzory z interfejsami Open Cloud, w szczególności wokół tworzenia wniosków i zarządzania odpowiedziami.
Ścieżki
Aby złożyć wniosek o dostęp do API Open Cloud, musisz najpierw utworzyć URL. Ten URL to kombinacja podstawowego URL ( https://apis.roblox.com/cloud/v2 ) i drogi Open Cloud API (na przykład, /uniwerses/universe-id/places/place-id/user-restraints
Wiele ścieżek, w tym przykład powyżej, ma parametry ścieżki , określone przez klamki w odniesieniu API. Parametry ścieżki są po prostu zmienne, które wpisujesz przed wysłaniem prośby i są prawie zawsze ID: ID użytkownika, grup ID, miejsce ID, itp. ID są często liczbowe, ale nie zawsze; na przykład, przechowywanie danych i pamięci przechowywania ID
Niektóre zasoby mają wiele wzorów ścieżki, widocznych pod 頭路 ścieżki zasobów w nagłówku API. Na przykład, URL dla Ograniczeń listy użytkownika 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żna zaryzykować różnicę między dwoma: niektóre ograniczenia użytkowników mają zastosowanie do całego wszechświata (doświadczenia), podczas gdy inne mają zastosowanie do konkretnych miejsc w wszechświecie. Oprócz niewielkiej dodatkowej do parametru ścieżki i dodatkowej ścieżki, wezwania są identyczne.
Wiele API w zwrocie drogi jako część swojej odpowiedzi, którą możesz użyć do złożenia dalszych wniosków. Jeśli API potrzebuje więcej niż kilku sekund na zakończenie prośba, zwykle w zwrocie pojawia się operacja zamiast zasobu lub odpowiedzi.
Długość i typ treści
Wiele wezwów API, w szczególności tych, które tworzą lub aktualizują zasoby, wymaga ciała prośby JSON. Jeśli Twoje zgłoszenie ma ciało, upewnij się, że zawiera Content-Length i Content-Type nagłówki. Większość klientów HTTP dodaje te nagłówki automatycznie.
Pagination
Jeśli określisz maxPageSize w swoim prośba, niektóre metody zwracają wyniki podzielone na strony — w zasadzie częściowe odpowiedzi:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25
{
"inventoryItems": [
...
],
"nextPageToken": "aaaBBB"
}
Jeśli odpowiedź zawiera wartość dla nextPageToken , użyj tej wartości w parametrze pageToken następnego zapytania, aby odzyskać następną stronę. Gdy nextPageToken jest pusty, osiągnąłeś końcę wyników:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB
{
"inventoryItems": [
...
],
"nextPageToken": ""
}
Oprócz pageToken , musisz użyć tej samej zapytania, aby prawidłowo działała pagination. Altering any filter parameter results in a 400 error.
Długoterminowe operacje
Niektóre metody zwracają obiekt Operation, który reprezentuje długoterminowe zadanie, które zwraca asynchroniczną odpowiedź później. Obiekt zawiera następujące pola:
- droga - Droga końcowa do wezwania do głosowania na ukończenie prośba. Załóż drogę do oryginalnej bazy URL metody zasobu.
- zakończony -wartośćBoolean, która określa, czy operacja została zakończona lub nie.
- odpowiedź - Obiekt odpowiedzi. To pole jest puste do czasu, aż pola done i true mają wartość 0> true0>.
- metadane meta - Dostosowane metadane do wymaganej prośby.
Przykład obiektu operacji
{
"path": "v1/assets/12345/operation/xyz",
"done": true,
"response": {
"value1": "myValue",
"value2": 1234
},
"metadata": {
"metadata1": "string",
"metadata2": 5678
}
}
Użyj ścieżki Operation obiektu, aby zagłosować, kiedy zasób jest gotowy. Dobrym strategią jest używanie eksponencjalnego odchylenia. Na przykład możesz zagłosować natychmiastnie, a potem po jednej sekundzie, dwóch sekundach, czterech sekundach itp.
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)
# Odczytaj ponownie logikę dla kolejnych czynności
else:
time.sleep(retryPollingDelay)
results = GetOperation(operationPath)
# Wyłącz
retryPollingDelay *= retryPollingMultiplier
# Sprawdź wyniki i powróć, jeśli istnieją
if (results.status_code != 200 or results.json()[doneJSONKey]):
return results
# W przeciwnym razie zwiększ liczbę prób
else:
currentRetries += 1
Dla bardziej kompletnego przykładu kodu, który używa stałego interwału prób lub zwrotów, zobacz Polling for Results .
Filtrowanie
Niektóre metody pozwalają na filtrowanie odpowiedzi poprzez uwzględnienie parametru filter w prośba. Następne sekcje opisują szybkę filtrowania i zasady dla określonych punktów końcowych.
Lista członkowstw grup
Dziką kartę można użyć w miejsce ID grupy, aby uzyskać listę członkowstw w wszystkich grupach: - .
Filtrowanie zgodne z CommonExpressionLanguage (CEL). Wspierane są tylko dwa operatory:
- ==
- in [...]
Jeśli określisz ID grupy w ścieżce zasobu, możesz filtrować członkostwo według 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 dzikiego znaku dla ID grupy, musisz filtrować członkowstwo przez użytkownika (do 50) w następującej formie:
- Filtr użytkownika : filter="użytkownik w [usern/1, użytkownikach/156, użytkownikach/9876543210], itp] [...]
Lista przedmiotów w ekwipunku
Możesz filtrować według statusu zbieralności, wpisywaćprzedmiotu w ekwipunku i ID ekwipunku. Jeśli nie zapewnisz filtra, cały ekwipunek użytkownika zostanie zwrócony.
格式k filtra to lista rozdzielona semikolonami:
filter={field}={value};{field}={value},{value},...;{field}=...
- {field} może być dowolnym z wcześniej zdefiniowanych pola typu lub pola ID w następujących tabelach.
- {value} może być ciągiem, bułką lub listą. W zależności od wpisywaćpola może to być pojedyncza wartość (bułki pola) lub wieloroczny wątek (listy pola).
Nie możesz łączyć pola typu i ID w tym samym filtrze.
Typy pola
| Filtr | Typ | Opis | | :---------------- | : | | | Filter | Type | Description | | :---------------- | : | | | In
Pole ID
| Filtruj | Rodzaj | Opis | | :----------------- | :----- | :
Przykłady
Zwraca wszystkie zbieralne przedmioty, które posiada użytkownik:
filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Zwraca wszystkie pozycje typów określonych:
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Wyświetla wszystkie pozycje z listy typów lub dowolne przepustki do gry. Wyklucza odznaki z wyników (to samo zachowanie, jakby badges nie było włączone w filtr):
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Restituje zasoby, które odpowiadają podanym ID:
filter=assetIds=1,2,3,4
Zwraca zasoby, odznaki, przepustki do gry i prywatne serwery, które odpowiadają podanym ID:
filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4