Przewodnik użytkowania dla zasobów

Aplikacja Zasoby API Open Cloud pozwala na przesyłanie i aktualizowanie zasobów za pomocą jednej prośby HTTP, zamiast importować je ręcznie do Studio.Ta API wspiera:

• Przesyłanie nowych zasobów.
• Aktualizowanie istniejących zasobów za pomocą kontroli wersji.
• Aktualizowanie metadanych zasobów, w tym opisów, nazw wyświetlania, ikon i podglądów.
• Zarządzanie wersjami zasobów, takimi jak powrót do określonej poprzedniej wersji.
• Sprawdzanie istniejących informacji o aktywie, w tym metadanych, wersji i wszelkich operacji aktualizacyjnych w toku.

Wspierane typy zasobów i limity

Dla punktów końcowych, które nie tworzą nowego zasobu lub nie aktualizują zawartości istniejących zasobów, nie ma ograniczeń i ograniczeń.Jednak funkcjonalność przesyłania treści zasobów zasilana przez twórz zasób i aktualizuj zasób końcówki wspiera tylko ograniczone rodzaje zasobów z ograniczeniami.Dla każdego połączenia możesz utworzyć lub zaktualizować tylko jeden zasób z rozmiarem pliku do 20 MB z następującymi ograniczeniami:

Uprawnienia bezpieczeństwa

API wspiera zarówno użycie w pierwszym rzędzie za pomocą autoryzacji klucza API oraz użycie stron trzecich w aplikacjach OAuth 2.Każda strona wymaga różnych ustawień uprawnień bezpieczeństwa.

Klucze API

Aby korzystać z API w własnych skryptach lub narzędziach, musisz stworzyć klucz API do autoryzacji i bezpieczeństwa.Aby zarządzać zasobami, które posiadasz indywidualnie, utwórz klucz API pod swoim konto.Aby zarządzać zasobami własnością grupy, utwórz klucz API w ramach docelowej grupa.Aby uzyskać więcej informacji o kluczach API należących do grupy, zobacz uprawnienia do kluczy API należących do grupy.

Po utworzeniu klucza API nie możesz przełączać jego własności między osobami lub grupami, więc jeśli utworzysz klucz API pod własnym kontem, nie możesz go używać do zarządzania zasobami grup.

Niezależnie od tego, czy tworzysz klucz API dla siebie czy dla swojej grupa, upewnij się, że dodajesz następujące uprawnienia:

1. Dodaj aktywa do uprawnień dostępu .
2. Dodaj Przeczytaj i Napisz uprawnienia operacji do wybranego doświadczenia, w zależności od wymaganych zakresów końcówek, które planujesz wezwać.

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

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

Aplikacje OAuth 2.0

Aby korzystać z API dla aplikacji zewnętrznej OAuth 2.0, dodaj zakresy uprawnień i podczas rejestracji aplikacji .Wybierz te zakresy w oparciu o wymagania końcówek, które planujesz używać.

Stwórz nowy zasób

Aby przesłać nowy zasób za pomocą prośbaHTTP:

1. Kopiuj klucz API do nagłówka żądania x-api-key z punktu końcowego Twórz zasób.

2. W twoim prośba:

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

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

   Example Request for Create Asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"This is a description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Użyj groupId do tworzenia zasobu grupy
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aktualizuj istniejący zasób

Aby zaktualizować istniejący zasób za pomocą prośbaHTTP:

1. Kopiuj klucz API do nagłówka żądania x-api-key z punktu końcowego Aktualizuj zasób.
2. Dodaj typ zasobu i ID zasobu w swojej prośba. Aby skopiować ID zasobu:

   1. Przejdź do strony Tworzenie z menu Pulpitu nawigacyjnego twórcy .
   2. Wybierz kategoria Przedmioty rozwojowe .
   3. Wybierz kategorię swojego aktywa i znajdź docelowe aktywa.
   4. Najedź na miniaturę docelowego zasobu i kliknij przycisk ⋯ , aby wyświetlić listę opcji, a następnie wybierz Kopiuj ID zasobu z listy.

Example Request for Updating Asset Content
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}"'

Zbierz status operacji zasobu

Jeśli twoja prośba o utworzenie nowego zasobu lub aktualizację istniejącego zasobu powiedzie się, zwraca ID operacji w formacie .Możesz go użyć do sprawdzenia stanu i wyniku przesłania za pomocą następujących kroków:

1. Kopiuj klucz API do nagłówka żądania x-api-key metody Zdobądź operację i wysyłaj prośba, tak jak następujący przykład kodu:

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

2. Jeśli twoja prośba się powiedzie, zwraca obiekt Operation, który zawiera response reprezentujący informacje o przesłanej informacji o zasobie lub obiekt status, który wyjaśnia, dlaczego przesłanie zasobu nie powiodło się, jak pokazuje poniższy przykład kodu:

   Example Response for Get Operation
   {
     "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": "Name",
       "description": "This is a description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Opcjonalnie) Sprawdź utworzone zasoby na swoim koncie Roblox.

   1. Przejdź do strony Inwentarz twojego konta Roblox.
   2. Wybierz Kategorię zasobu, który chcesz sprawdzać.
   3. Znajdź docelowy zasób i kliknij jego miniaturę, aby zobaczyć 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ć użytkownikom przesyłanie i aktualizowanie zasobów do Roblox.

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

1. Gdy rejestrujesz aplikację, w ramach uprawnień , wybierz przeczytanie zasobu i zapisanie zasobu zakresy.

2. Gdy implementujesz przepływ autoryzacji, uwzględnij asset:read i asset:write jako parametry zakresu adresu URL autoryzacji, który przekieruje użytkowników z powrotem do Twojej aplikacji, tak jak w następnym przykładzie:

   https://authorize.roblox.com?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. Wysyłając prośba, uwzględnij token dostępu w nagłówku autoryzacji i dane formularza zawartości zasobu, które należy utworzyć lub zaktualizować w adresie żądania.Poniższy przykład pokazuje próbną prośbę o przesłanie nowego zasobu:

   Przykładowe żądanie
   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\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'