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

Açık Bulut'un Varlıklar API si, varlıkları Studio'ya manuel olarak ithal etmek yerine tek bir HTTP isteği ile yükleme ve güncellemeye izin verir.Bu API destekler:

• Yeni varlıklar yükleniyor.
• Mevcut varlıkları sürüm kontrolü ile güncelleme.
• Açıklamalar, ekran adları, simgeler ve önizlemeler dahil olmak üzere varlık metadatlarını güncelleştirme
• Belirli bir önceki sürüme geri gitmek gibi varlık sürümlerini yönetmek.
• Metadatlar, sürümler ve herhangi bir devam eden güncelleme işlemi dahil olmak üzere varlığın mevcut bilgilerini kontrol etmek.

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

Yeni bir varlık oluşturmayan veya mevcut varlıkların içeriğini güncellemeyen uç noktalar için kısıtlama ve sınır yoktur.Ancak, Varlık oluşturma ve Varlığı güncelleme uç noktaları tarafından desteklenen varlık içeriği yükleme işlevi sınırlı türde varlıklarla sınırlıdır.Her çağrı için, aşağıdaki sınırlarla birlikte dosya boyutu 20 MB'ye kadar olan bir varlık yalnızca oluşturabilir veya güncelleyebilirsiniz:

Güvenlik izinleri

API hem ilk parti kullanımı ile API anahtar yetkilendirmesi hem de üçüncü parti kullanımı ile OAuth 2 uygulamalarında destekler.Her yol farklı güvenlik izin ayarları gerektirir.

API anahtarları

API'yi kendi senaryolarınızda veya araçlarınızda kullanmak için, yetkilendirme ve güvenlik için bir API anahtarı oluşturmanız gerekir API anahtarı oluştur.Bireysel olarak sahip olduğunuz varlıkları yönetmek için, hesapaltında API anahtarı oluşturun.Grup sahibi varlıkları yönetmek için, hedef grupaltında API anahtarı oluşturun.Grup sahibi API anahtarları hakkında daha fazla bilgi için, Grup sahibi API anahtar izinleri bakın.

Bir API anahtarı oluşturduktan sonra, bunun sahipliğini bireyler veya gruplar arasında değiştiremezsiniz, bu nedenle kendi hesapaltında bir API anahtarı oluşturursanız, grup varlıklarını yönetmek için kullanamazsınız.

Kendiniz veya grupiçin API anahtarı oluşturuyor olsanız da, aşağıdaki izinleri eklemekten kaçınmayın:

1. Ekleyin varlıkları Erişim İzinlerine .
2. Seçilen deneyime Oku ve Yaz işlem izinlerini ekleyin, çağırmayı planladığınız son noktaların gerektirdiği alanlara bağlı olarak.

API anahtarına sahip olduğunuzda, x-api-key istek başlığına kopyalayın. Tüm son noktalar x-api-key istek başlığını gerektirir.

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

OAuth 2.0 uygulamaları

Üçüncü taraf bir OAuth 2.0 uygulaması için API'yi kullanmak için, asset:read ve asset:write izin alanlarını ekleyin, uygulamanızı kaydettikten sonra.Kullanmayı planladığınız uç noktaların gereksinimlerine göre bu alanları seçin.

Yeni bir varlık oluştur

Bir HTTP talepyeni bir varlık yükletmek için:

1. API anahtarını x-api-key oluşturma noktasının Yaratma İsteği başlığına kopyalayın.

2. talep:

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

      • Eğer varlığı kendi adına oluşturmak istiyorsanız **** , kullanıcı ID'nizi ekleyin.Kullanıcı kimliğinizi Roblox profilinizin URL'sinde bulabilirsiniz.Örneğin, https://www.roblox.com/users/1234567/profile için, kullanıcı kimliğiniz 1234567 dir.
      • Eşyayı bir grup öğesi olarak oluşturmak istiyorsanız , grubunuzun grup kimliğini ekleyin.Grup ID'sini grubunuzun sayfasının URL'sinde bulabilirsiniz.Örneğin, https://www.roblox.com/groups/7654321/example-group#!/ için, grup kimliği 7654321 dir.
   4. Varlığınızın dosya yolu ve içerik türünü ekleyin.

   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}\" # Bir grup varlığı oluşturmak için grupId'yi kullan
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mevcut bir varlığı güncelle

Mevcut bir varlığı HTTP talepgüncelletmek için:

1. API anahtarını x-api-key güncelleme noktasının varlığı güncelle istek başlığına kopyalayın.
2. Varlık türünü ve varlık kimliğini talepekleyin. Varlık kimliğinizi kopyalamak için:

   1. Navigate to the Yaratma page of the Yaratıcı Panosu .
   2. Geliştirme Eşyaları kategorisini seçin.
   3. Varlığın kategorisini seçin ve hedef varlığı bulun.
   4. Hedef varlığın küçük resminin üzerine gelin ve bir seçenek listesi görüntülemek için ⋯ düğmesine tıklayın, ardından listeden Varlık Kimliğini Kopyala seçin.

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

Varlık operasyonu durumunu geri al

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

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

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

2. Talebiniz başarılı olursa, yüklendiği varlık bilgilerini temsil eden bir Operation nesne veya varlık yükleme başarısız olmasının nedenini açıklayan bir response nesne döndürür: yüklendiği varlık bilgilerini temsil eden bir status nesne veya varlık yükleme başarısız olmasının nedenini açıklayan bir nesne:

   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. (Opsiyonel) Roblox hesapoluşturulan varlığı kontrol edin.

   1. Navigate to the Envanter sayfasına Roblox hesabınızın.
   2. Kontrol etmek istediğiniz varlığın Kategorisi kontrol et.
   3. Hedef varlığı bulun ve varlığı görüntülemek için küçük resmine tıklayın.

OAuth 2.0 uygulamalarına varlık API'si ekleyin

Kullanıcılarınızın Roblox'a varlıklar yüklemeye ve güncellemeye izin vermek için OAuth 2.0 uygulamaları oluşturabilir ve Assets API'yi destekleyebilirsiniz.

Uygulamanız için Varlık API'sini kullanmak ve kullanıcılarınızdan izinler istemek için aşağıdaki ayarları yapın:

1. Uygulamanızı kaydettikten sonra, İzinler altında, varlık:okuma ve varlık:yazma alanlarını seçin.

2. Yetkilendirme akışını uygularken , kullanıcıları uygulamanıza geri yönlendiren yetkilendirme URL'sinin alanına ve dahil edin, örneğin aşağıdaki örnekte olduğu gibi:

   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. talepgönderirken, erişim jetonunu yetkilendirme başlığına ve varlık içeriğinin form verilerine dahil ederek istek URI'sinde oluşturun veya güncelleyin.Aşağıdaki örnek, yeni bir varlık yükleme için örnek bir istek gösterir:

   Ö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\": \"Decal\",
   
     \"displayName\": \"DecalDemo123\",
   
     \"description\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'