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ı manuel olarak Studio'ya aktarmak zorunda kalmazsınız. Bu API, şunları destekler:

• Yeni varlıkların yüklenmesi.
• Versiyon kontrolü ile mevcut varlıkların güncellenmesi.
• Açıklamalar, görünüm adları, simgeler ve önizlemeler dahil varlık meta verilerinin güncellenmesi.
• Belirtilen önceki bir sürüme geri dönmek gibi varlık sürümlerinin yönetimi.
• Bir varlığın mevcut bilgilerini kontrol etme, bu bilgiler arasında meta veriler, sürümler ve herhangi bir işlemde güncelleme operasyonları yer alır.

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şturma ve Varlık Güncelleme uç noktaları tarafından desteklenen varlık içeriği yükleme işlevi yalnızca kısıtlı türde varlıkları destekler. Her bir çağrı için yalnızca bir varlık oluşturabilir veya güncelleyebilirsiniz ve dosya boyutu 20 MB ile sınırlıdır:

Güvenlik izinleri

API, hem API anahtarı yetkilendirmesi ile birinci şahıs kullanımı, hem de OAuth 2 uygulamaları ile üçüncü şahıs kullanımı destekler. Her iki kullanım için farklı güvenlik izin ayarları gereklidir.

API Anahtarları

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

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

1. Erişim İzinleri bölümüne varlıklar ekleyin.
2. Kullanmayı planladığınız uç noktaların gereksinimlerine bağlı olarak, seçtiğiniz oyuna Okuma ve Yazma işlem izinlerini ekleyin.

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

API İsteği Başlığı Örneği
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 Uygulamaları

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

Yeni bir varlık oluşturma

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ı ve açıklamasını ekleyin.
   3. Oluşturucu bilgilerini ekleyin.

      • Varlığı kendi adınıza oluşturmak istiyorsanız, kullanıcı kimliğinizi ekleyin. Roblox profilinizin URL'sinde kullanıcı kimliğinizi 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çıklama\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Grup varlığı oluşturuyorsanız groupId kullanın
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mevcut bir varlığı güncelleme

HTTP isteği ile mevcut bir varlığı 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ü ve varlık kimliğini ekleyin. Varlık kimliğinizi kopyalamak için:

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

Varlık İçeriğini Güncelleme İsteği Örneği
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şleme 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 şu adımları izleyebilirsiniz:

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

   İş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 bilgisini temsil eden bir response içeren bir Operation nesnesi ya da yükleme işleminizin 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çıklama",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (İsteğe bağlı) 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ıkların Kategorisi'ni seçin.
   3. Hedef varlığı bulun ve varlığın küçük resmine tıklayarak görü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 üzere, şu ayarları yapın:

1. Uygulamanızı kaydettiğinizde, İzinler bölümünde asset:read ve asset:write izin alanlarını seçin.

2. Yetkilendirme akışını uygularken, kullanıcıların uygulamanıza geri döndüklerinde yönlendirileceği yetkilendirme URL'sinin kapsam parametreleri olarak asset:read ve asset:write ekleyin, aşağıdaki örnekte olduğu 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, yetki başlığında erişim jetonunu ve istek URI'sindeki yaratılacak veya güncellenecek varlık içeriğini içeren 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çıklama\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'