Varlıklar için kullanım kılavuzu

Open Cloud'un Varlıklar API'si, varlıkları tek bir HTTP isteği ile yüklemenizi ve güncellemenizi sağlar; böylece bunları Studio'ya manuel olarak aktarmanıza gerek kalmaz. Bu API şunları destekler:

• Yeni varlıkların yüklenmesi.
• Mevcut varlıkların sürüm kontrolü ile güncellenmesi.
• Açıklamalar, görüntü adları, simgeler ve önizlemeler dahil varlık meta verilerinin güncellenmesi.
• Belirli bir önceki sürüme geri dönme gibi varlık sürümlerinin yönetilmesi.
• Bir varlığın mevcut bilgilerini kontrol etme, meta veriler, sürümler ve herhangi bir işlemdeki güncelleme işlemleri dahil.

Desteklenen varlık türleri ve sınırlamalar

Yeni bir varlık oluşturmayan veya mevcut varlıkların içeriğini güncellemeyen uç noktalar için herhangi bir kısıtlama ve sınırlama yoktur. Ancak, Varlık Oluştur ve Varlık Güncelle uç noktaları tarafından desteklenen varlık içeriği yükleme işlevselliği, sınırlı türde varlıkları destekler. Her çağrıda, yalnızca 20 MB'a kadar dosya boyutuna sahip bir varlık oluşturabilir veya güncelleyebilirsiniz. Aşağıdaki sınırlamalar geçerlidir:

Güvenlik izinleri

API, hem API anahtarı yetkilendirmesi ile birinci taraf kullanımını hem de OAuth 2 uygulamalarında üçüncü taraf kullanımını destekler. Her iki yol da farklı güvenlik izin ayarları gerektirir.

API anahtarları

API'yi kendi betiklerinizde veya araçlarınızda kullanmak için, yetkilendirme ve güvenlik için bir API anahtarı oluşturmanız gerekir.

Bir API anahtarı oluştururken, aşağıdaki izinleri eklediğinizden emin olun:

1. Erişim İzinleri'ne varlıklar ekleyin.
2. Çağırmayı planladığınız uç noktaların gerektirdiği kapsamlara bağlı olarak, seçtiğiniz oyuna Okuma ve Yazma işlem izinleri ekleyin.

API anahtarını aldıktan sonra, x-api-key istek başlığına kopyalayın. Tüm uç noktalar x-api-key istek başlığını gerektirir.

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

OAuth 2.0 uygulamaları

API'yi üçüncü taraf bir OAuth 2.0 uygulaması için kullanmak üzere, uygulamanızı kaydederken asset:read ve asset:write izin kapsamlarını ekleyin. Bu kapsamları, kullanmayı planladığınız uç noktaların gereksinimlerine göre seçin.

Yeni bir varlık oluşturma

Bir HTTP isteği ile yeni bir varlık yüklemek için:

1. Varlık Oluştur uç noktasının x-api-key istek başlığına API anahtarını kopyalayın.

2. İsteğinizde:

   1. Hedef varlık türünü belirtin.
   2. Varlık adınızı ve açıklamanızı ekleyin.
   3. Oluşturucu bilgilerini ekleyin.

      • Varlığı kendi adınıza oluşturmak istiyorsanız, kullanıcı kimliğinizi ekleyin. Kullanıcı kimliğinizi Roblox profilinizin URL'sinde bulabilirsiniz. Örneğin, https://www.roblox.com/users/1234567/profile,için kullanıcı kimliğiniz1234567`'dir.
      • Varlığı bir grup varlığı olarak oluşturmak istiyorsanız, grubunuzun grup kimliğini ekleyin. Grup kimliğinizi grubunuzun sayfasının URL'sinde bulabilirsiniz. Örneğin, https://www.roblox.com/groups/7654321/example-group#!/,için grup kimliği7654321`'dir.
   4. Varlığınızın dosya yolunu ve içerik türünü ekleyin.

   Varlık Oluşturma İsteği Örneği

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"İsim\",
     \"description\": \"Bu bir açıklamadır\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Grup varlığı oluşturmak için groupId kullanın
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mevcut bir varlığı güncelleme

Mevcut bir varlığı bir HTTP isteği ile güncellemek için:

1. Varlık Güncelle uç noktasının x-api-key istek başlığına API anahtarını kopyalayın.
2. İsteğinizde varlık türünü ve varlık kimliğini ekleyin. Varlık kimliğinizi kopyalamak için:

   1. Yaratıcı Kontrol Paneli'nin Oluşturma sayfasına gidin.
   2. Geliştirme Öğeleri kategorisini seçin.
   3. Varlığınızın kategorisini seçin ve hedef varlığı bulun.
   4. Hedef varlığın küçük resminin üzerine gelin ve seçenekler listesini görüntülemek için ⋯ butonuna tıklayın, ardından listeden Varlık Kimliğini Kopyala seçeneğini seçin.

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

Varlık işlem durumunu alma

Yeni bir varlık oluşturma veya mevcut bir varlığı güncelleme isteğiniz başarılı olursa, { "path": "operations/${operationId}" } formatında bir İşlem Kimliği döner. Yüklemenizin durumunu ve sonucunu kontrol etmek için aşağıdaki adımları kullanabilirsiniz:

1. Get Operation yönteminin x-api-key istek başlığına API anahtarını kopyalayın ve isteği gönderin, aşağıdaki kod örneği gibi:

   İşlem Alma İsteği Örneği

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

2. İsteğiniz başarılı olursa, ya yüklenen varlık bilgilerini temsil eden bir response içeren bir Operation nesnesi ya da varlık yüklemesinin neden başarısız olduğunu açıklayan bir status döner; aşağıdaki kod örneği gibi:

   İşlem Alma Yanıtı Örneği

   {
     "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": "İsim",
       "description": "Bu bir açıklamadır",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. İSTEĞE BAĞLI

   Oluşturulan varlığı Roblox hesabınızda kontrol edin.

   1. Roblox hesabınızın Envanter sayfasına gidin.
   2. Kontrol etmek istediğiniz varlık Kategorisini seçin.
   3. Hedef varlığı bulun ve varlığın küçük resmine tıklayarak varlığı görüntüleyin.

Yüklenen varlıkları Studio'da kullanma

Yüklediğiniz bir varlık, isteğinizin creationContext'inde belirtilen kullanıcıya veya gruba aittir, bu nedenle Studio'da, yaratıcının sahip olduğu diğer varlıklar gibi kullanılabilir:

• Araç Kutusu veya Varlık Yöneticisi üzerinden ekleyin.
• Modeller paketler olarak yüklenir, bu nedenle Araç Kutusu'nda Envanter ⟩ Benim Paketlerim'i kontrol edin (veya bir grup sahipleniyorsa Yaratımlar ⟩ Grup Paketleri).
• Bir varlığı bir özellikte kullanmak için, rbxassetid:// ifadesini yazın ve ardından Özellikler penceresindeki işlem yanıtından assetId'yi ekleyin. Bir betikte, bu dizeyi AudioPlayer.Asset gibi bir dize özelliğine atayın veya Content.fromAssetId()'ye assetId'yi geçirin; bu, Decal.ColorMapContent gibi Content türünde bir özellik içindir. Daha fazla bilgi için rbxassetid sayfasına bakın.

Varlıklar API'sini OAuth 2.0 uygulamalarına ekleme

Kullanıcılarınızın Roblox'a varlık yüklemesine ve güncellemesine izin vermek için Varlıklar API'sini destekleyen OAuth 2.0 uygulamaları oluşturabilirsiniz.

Uygulamanız için Varlıklar API'sini kullanmak ve kullanıcılarınızdan izin istemek için aşağıdaki ayarları gerçekleştirin:

1. Uygulamanızı kaydederken, İzinler altında asset:read ve asset:write kapsamlarını seçin.

2. Yetkilendirme akışını uygularken, kullanıcıları uygulamanıza geri yönlendiren yetkilendirme URL'sinin kapsam parametreleri olarak asset:read ve asset:write'i ekleyin; aşağıdaki örnek gibi:

   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. İsteği gönderirken, yetkilendirme başlığında erişim belirtecini ve varlık içeriğini oluşturmak veya güncellemek için istek URI'sinde form verilerini ekleyin. Aşağıdaki örnek, yeni bir varlık yüklemek için bir örnek isteği göstermektedir:

   İstek Örneği

   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\": \"Bu bir açıklamadır\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'