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 olmak üzere 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ığı 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. 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ına sahip olduktan sonra, bunu 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 için Örnek İstek

   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. Bunu, yüklemenizin durumunu ve sonucunu kontrol etmek için aşağıdaki adımlarla kullanabilirsiniz:

1. İşlem Alma 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 için Örnek İstek

   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 için Örnek Yanıt

   {
     "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ığı görüntülemek için küçük resmine tıklayı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 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, erişim belirtecini yetkilendirme başlığında ve varlık içeriğini oluşturmak veya güncellemek için form verisinde URI'de dahil edin. Aşağıdaki örnek, yeni bir varlık yüklemek için bir örnek isteği göstermektedir:

   Örnek İstek

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