Przewodnik użytkowania dla zasobów

API Zasobów Open Cloud pozwala na przesyłanie i aktualizowanie zasobów za pomocą jednego żądania HTTP zamiast ręcznego importowania ich do Studio. To API wspiera:

• Przesyłanie nowych zasobów.
• Aktualizowanie istniejących zasobów z kontrolą wersji.
• Aktualizowanie metadanych zasobów, w tym opisów, nazw wyświetlanych, ikon i podglądów.
• Zarządzanie wersjami zasobów, takimi jak przywracanie do określonej poprzedniej wersji.
• Sprawdzanie istniejących informacji o zasobie, w tym metadanych, wersjach oraz wszelkich operacjach aktualizacji w toku.

Obsługiwane typy zasobów i ograniczenia

Dla punktów końcowych, które nie tworzą nowego zasobu ani nie aktualizują zawartości istniejących zasobów, nie ma ograniczeń ani limitów. Jednak funkcjonalność przesyłania zawartości zasobów, wspierana przez końcówki Utwórz Zasób i Aktualizuj Zasób, obsługuje tylko ograniczone typy zasobów z restrykcjami. Dla każdego wywołania można utworzyć lub zaktualizować tylko jeden zasób o wielkości pliku do 20 MB z następującymi ograniczeniami:

Uprawnienia bezpieczeństwa

API obsługuje zarówno użycie pierwszej strony z autoryzacją klucza API, jak i użycie trzeciej strony w aplikacjach OAuth 2. Każda opcja wymaga różnych ustawień uprawnień bezpieczeństwa.

Klucze API

Aby korzystać z API w swoich własnych skryptach lub narzędziach, musisz utworzyć klucz API dla autoryzacji i bezpieczeństwa.

Tworząc klucz API, upewnij się, że dodasz następujące uprawnienia:

1. Dodaj assets do Uprawnień dostępu.
2. Dodaj uprawnienia do operacji Odczyt i Zapis do swojego wybranego doświadczenia, w zależności od wymaganych zakresów punktów końcowych, które zamierzasz wywołać.

Gdy posiadasz klucz API, skopiuj go do nagłówka żądania x-api-key. Wszystkie punkty końcowe wymagają nagłówka żądania x-api-key.

Przykład nagłówka żądania API
--header 'x-api-key: ${ApiKey}' \

Aplikacje OAuth 2.0

Aby skorzystać z API dla aplikacji OAuth 2.0 innej firmy, dodaj uprawnienia asset:read i asset:write podczas rejestrowania swojej aplikacji. Wybierz te zakresy na podstawie wymagań punktów końcowych, które zamierzasz użyć.

Utwórz nowy zasób

Aby przesłać nowy zasób za pomocą żądania HTTP:

1. Skopiuj klucz API do nagłówka żądania x-api-key punktu końcowego Utwórz Zasób.

2. W swoim żądaniu:

   1. Określ docelowy typ zasobu.
   2. Dodaj nazwę i opis swojego zasobu.
   3. Dodaj informacje o twórcy.

      • Jeśli chcesz utworzyć zasób w swoim imieniu, dodaj swój identyfikator użytkownika. Możesz znaleźć swój identyfikator użytkownika w adresie URL swojego profilu Roblox. Na przykład, dla https://www.roblox.com/users/1234567/profile, twój identyfikator użytkownika to 1234567.
      • Jeśli chcesz utworzyć zasób jako zasób grupy, dodaj identyfikator grupy swojej grupy. Możesz znaleźć identyfikator grupy w adresie URL strony swojej grupy. Na przykład, dla https://www.roblox.com/groups/7654321/example-group#!/, identyfikator grupy to 7654321.
   4. Dodaj ścieżkę pliku i typ zawartości swojego zasobu.

   Przykład żądania dla Utwórz Zasób
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nazwa\",
     \"description\": \"To jest opis\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Użyj groupId do tworzenia zasobu grupy
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Zaktualizuj istniejący zasób

Aby zaktualizować istniejący zasób za pomocą żądania HTTP:

1. Skopiuj klucz API do nagłówka żądania x-api-key punktu końcowego Aktualizuj Zasób.
2. Dodaj typ zasobu i identyfikator zasobu w swoim żądaniu. Aby skopiować swój identyfikator zasobu:

   1. Przejdź do strony Tworzenia w Panelu Twórcy.
   2. Wybierz kategorię Elementy rozwojowe.
   3. Wybierz kategorię swojego zasobu i znajdź docelowy zasób.
   4. Najedź na miniaturę docelowego zasobu i kliknij przycisk ⋯, aby wyświetlić listę opcji, a następnie wybierz Kopiuj identyfikator zasobu z listy.

Przykład żądania dla aktualizacji zawartości zasobu
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

Sprawdź status operacji zasobu

Jeśli Twoje żądanie utworzenia nowego zasobu lub aktualizacji istniejącego zasobu się powiodło, zwraca ono ID operacji w formacie { "path": "operations/${operationId}" }. Możesz go użyć, aby sprawdzić status i wynik przesyłania za pomocą następujących kroków:

1. Skopiuj klucz API do nagłówka żądania x-api-key metody Pobierz Operację i wyślij żądanie, jak w poniższym przykładzie kodu:

   Przykład żądania dla Pobierz Operację
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Jeśli Twoje żądanie się powiedzie, zwraca obiekt Operation, który może zawierać response reprezentujące informacje o przesłanym zasobie lub status wyjaśniający, dlaczego przesyłanie zasobu się nie powiodło, jak pokazano w poniższym przykładzie kodu:

   Przykład odpowiedzi dla Pobierz Operację
   {
     "path": "operations/{operationId}",
     "done": true,
     "response": {
       "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
       "path": "assets/2205400862",
       "revisionId": "1",
       "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
       "assetId": "2205400862",
       "displayName": "Nazwa",
       "description": "To jest opis",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Opcjonalnie) Sprawdź utworzony zasób na swoim koncie Roblox.

   1. Przejdź do strony Inwentarz swojego konta Roblox.
   2. Wybierz Kategorii zasobu, który chcesz sprawdzić.
   3. Znajdź docelowy zasób i kliknij jego miniaturę, aby wyświetlić zasób.

Dodaj API zasobów do aplikacji OAuth 2.0

Możesz stworzyć aplikacje OAuth 2.0 wspierające API Zasobów, aby umożliwić Twoim użytkownikom przesyłanie i aktualizowanie zasobów w Robloxie.

Aby użyć API Zasobów w swojej aplikacji i zażądać uprawnień od swoich użytkowników, wykonaj następujące ustawienia:

1. Podczas rejestrowania swojej aplikacji, w sekcji Uprawnienia, wybierz zakresy asset:read i asset:write.

2. Podczas implementacji przepływu autoryzacji, dołącz asset:read i asset:write jako parametry zakresu adresu URL autoryzacji, który przekierowuje użytkowników z powrotem do Twojej aplikacji, jak w poniższym przykładzie:

   https://apis.roblox.com/oauth/v1/authorize?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. Podczas wysyłania żądania dołącz token dostępu w nagłówku autoryzacji i dane formularza zawartości zasobu, które mają zostać utworzone lub zaktualizowane w URI żądania. Poniższy przykład pokazuje przykładowe żądanie przesyłania nowego zasobu:

   Przykład żądania
   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Decal\",
   
     \"displayName\": \"DecalDemo123\",
   
     \"description\": \"To jest opis\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'