Wzorce

Ta strona obejmuje wspólne wzorce z interfejsami API Open Cloud, szczególnie dotyczące składania żądań i obsługi odpowiedzi.

Ścieżki

Aby wysłać żądanie do interfejsów API Open Cloud, należy najpierw utworzyć adres URL. Ten adres URL to połączenie podstawowego adresu URL (np. https://apis.roblox.com), ścieżki API Open Cloud (na przykład /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions) oraz wszelkich parametrów zapytania (na przykład ?maxPageSize=25). Pełny adres URL żądania może wyglądać tak:

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

Wiele ścieżek, w tym powyższy przykład, ma parametry ścieżki, oznaczone nawiasami klamrowymi w dokumentacji API. Parametry ścieżki to po prostu zmienne, które wstawiasz przed wysłaniem żądania i są zazwyczaj identyfikatorami: identyfikatory użytkowników, identyfikatory grup, identyfikatory miejsc itp. Identyfikatory są często numeryczne, ale niekoniecznie; na przykład identyfikatory magazynów danych i pamięci obsługują szerszy zestaw znaków.

Długość i typ zawartości

Wiele wywołań API, szczególnie tych, które tworzą lub aktualizują, wymaga ciała żądania w formacie JSON. Jeśli Twoje żądanie ma ciało, upewnij się, że dołączasz nagłówki Content-Length i Content-Type. Większość klientów HTTP dodaje te nagłówki automatycznie.

Stronicowanie

Jeśli określisz maxPageSize w swoim żądaniu, niektóre metody zwracają wyniki stronicowane — 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 kolejnego żądania, aby pobrać następną stronę. Gdy nextPageToken jest pusty lub całkowicie pominięty, osiągnąłeś koniec swoich 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żyć tego samego zapytania, aby stronicowanie działało prawidłowo. Zmiana dowolnego parametru filtra skutkuje błędem 400.

Open Cloud v2

Wiele ścieżek

Niektóre zasoby mają wiele wzorców ścieżek, które można zobaczyć w sekcji Ścieżki zasobów w dokumentacji API. Na przykład adres URL dla Lista ograniczeń dla użytkowników może być jednym z następujących:

• 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żytkowników mają zastosowanie do całego uniwersum (gry), podczas gdy inne mają zastosowanie do konkretnych miejsc w uniwersum. Oprócz małego dodatku do ścieżki i dodatkowego parametru ścieżki, wywołania są identyczne.

Wiele punktów końcowych zwraca ścieżkę jako część swojej odpowiedzi, której można użyć do kolejnych żądań. Jeśli API potrzebuje więcej niż kilku sekund, aby zrealizować żądanie, często zwraca operację zamiast samego zasobu lub odpowiedzi.

Długoterminowe operacje

Niektóre metody zwracają obiekt Operation, który reprezentuje żądanie długoterminowe, które zwraca asynchroniczną odpowiedź później. Obiekt zawiera następujące pola:

• path - Ścieżka punktu końcowego, aby sprawdzić zakończenie żądania. Dodaj ścieżkę do oryginalnego podstawowego adresu URL metody zasobu.
• done - Wartość logiczna, która reprezentuje, czy operacja została zakończona.
• response - Obiekt odpowiedzi. To pole jest puste, dopóki pole done nie ma wartości true.
• metadata - Niestandardowe metadane specyficzne dla złożonego żądania.

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 obiektu Operation, aby sprawdzić, kiedy zasób jest gotowy. Dobrym rozwiązaniem jest użycie wykładniczego opóźnienia. Na przykład, możesz sprawdzać natychmiast, a następnie po jednej sekundzie, dwóch sekundach, czterech sekundach itd.

def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Brak opóźnienia przy pierwszym sprawdzeniu
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logika ponawiania dla kolejnych sprawdzeń
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Wykładnicze opóźnienie
            retryPollingDelay *= retryPollingMultiplier
        # Sprawdzenie wyników i zwrócenie ich, jeśli istnieją
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # W przeciwnym razie zwiększ liczbę ponownych prób
        else:
           currentRetries += 1

Aby uzyskać bardziej kompletny przykład kodu, który używa stałego interwału ponawiania zamiast wykładniczego opóźnienia, zobacz Sprawdź wyniki.

Filtrowanie

Niektóre metody umożliwiają filtrowanie odpowiedzi, dodając parametr filter w żądaniu. Poniższe sekcje opisują składnię filtru i wytyczne dla określonych punktów końcowych.

Lista członkostw w grupach

Znak wieloznaczny - może być używany zamiast identyfikatora grupy, aby wyświetlać członkostwa we wszystkich grupach: groups/-/memberships.

Filtrowanie jest zgodne z Common Expression Language (CEL). Obsługiwane są tylko dwa operatory:

• ==
• in [...]

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

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

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

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

Lista przedmiotów w ekwipunku

Możesz filtrować według statusu przedmiotu kolekcjonerskiego, typu przedmiotu w ekwipunku oraz identyfikatora przedmiotu w ekwipunku. Jeśli nie podasz filtra, zwrócone zostanie całe ekwipunek użytkownika.

Format filtru to lista oddzielona średnikami:

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

• {field} może być dowolnym z predefiniowanych pól typu lub pól ID w poniższych tabelach.
• {value} może być ciągiem, wartością logiczną lub wartością enum. W zależności od typu pola, może to być jedna wartość (pola logiczne) lub wiele wartości (pola listy).

Pola typu

Pola ID

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 wymienionych typów lub jakiekolwiek karty dostępu. Wyklucza odznaki z wyników (to samo 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 odpowiadają określonym identyfikatorom:

  filter=assetIds=1,2,3,4

• Zwraca zasoby, odznaki, karty dostępu i prywatne serwery, które odpowiadają określonym identyfikatorom:

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