Przewodnik po użyciu zasobów

API Assets 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, wersji i wszelkich operacjach aktualizacji w toku.

Obsługiwane typy zasobów i limity

Dla punktów końcowych, które nie tworzą nowego zasobu ani nie aktualizują zawartości istniejących zasobów, nie ma żadnych ograniczeń ani limitów. Jednak funkcjonalność przesyłania zawartości zasobów, wspierana przez punkty końcowe Create Asset i Update Asset, obsługuje tylko ograniczone typy zasobów z ograniczeniami. Dla każdego wywołania można utworzyć lub zaktualizować tylko jeden zasób o maksymalnym rozmiarze pliku do 20 MB z następującymi limitami:

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 z tych metod wymaga różnych ustawień uprawnień bezpieczeństwa.

Klucze API

Aby używać API w swoich skryptach lub narzędziach, musisz utworzyć klucz API do autoryzacji i bezpieczeństwa.

Podczas tworzenia klucza API upewnij się, że dodasz następujące uprawnienia:

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

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

--header 'x-api-key: ${ApiKey}' \

Aplikacje OAuth 2.0

Aby używać API w aplikacji OAuth 2.0 strony trzeciej, dodaj zakresy uprawnień asset:read i asset:write podczas rejestrowania swojej aplikacji. Wybierz te zakresy na podstawie wymagań punktów końcowych, które zamierzasz używać.

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 Create Asset.

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 do utworzenia zasobu

   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 Update Asset.
2. Dodaj typ zasobu i identyfikator zasobu w swoim żądaniu. Aby skopiować identyfikator swojego zasobu:

   1. Przejdź do strony Tworzenie 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.

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

Pobierz status operacji zasobu

Jeśli twoje żądanie dotyczące utworzenia nowego zasobu lub zaktualizowania istniejącego zasobu zakończy się sukcesem, zwraca ono ID operacji w formacie { "path": "operations/${operationId}" }. Możesz go użyć do sprawdzenia statusu i wyniku przesyłania za pomocą następujących kroków:

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

   Przykład żądania do pobrania operacji

   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Jeśli twoje żądanie zakończy się sukcesem, zwraca obiekt Operation, który zawiera response reprezentujący informacje o przesłanym zasobie lub status wyjaśniający, dlaczego przesyłanie zasobu się nie powiodło, jak pokazuje poniższy przykład kodu:

   Przykład odpowiedzi dla pobrania operacji

   {
     "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. OPCJONALNE

   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ć swoim użytkownikom przesyłanie i aktualizowanie zasobów w Roblox.

Aby używać API zasobów w swojej aplikacji i żą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 wdrażania przepływu autoryzacji, dołącz asset:read i asset:write jako parametry zakresu w adresie 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 oraz dane formularza zawartości zasobu do utworzenia lub zaktualizowania w URI żądania. Poniższy przykład pokazuje przykładowe żądanie do 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\": \"Dekal\", 
   
     \"displayName\": \"DekalDemo123\", 
   
     \"description\": \"To jest opis\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'