Panduan penggunaan untuk aset

API Aset dari Open Cloud memungkinkan Anda untuk mengunggah dan memperbarui aset dengan satu permintaan HTTP daripada mengimpornya secara manual ke Studio. API ini mendukung:

• Mengunggah aset baru.
• Memperbarui aset yang ada dengan kontrol versi.
• Memperbarui metadata aset, termasuk deskripsi, nama tampilan, ikon, dan pratinjau.
• Mengelola versi aset, seperti mengembalikan ke versi sebelumnya yang ditentukan.
• Memeriksa informasi yang ada dari suatu aset, termasuk metadata, versi, dan operasi pembaruan yang sedang berlangsung.

Jenis aset yang didukung dan batasan

Untuk endpoint yang tidak membuat aset baru atau memperbarui konten aset yang ada, tidak ada batasan dan pembatasan. Namun, fungsionalitas pengunggahan konten aset yang didukung oleh endpoint Buat Aset dan Perbarui Aset hanya mendukung jenis aset terbatas dengan pembatasan. Untuk setiap panggilan, Anda hanya dapat membuat atau memperbarui satu aset dengan ukuran file hingga 20 MB dengan batasan berikut:

Izin keamanan

API mendukung penggunaan pihak pertama dengan otorisasi kunci API dan penggunaan pihak ketiga dalam aplikasi OAuth 2. Setiap cara memerlukan pengaturan izin keamanan yang berbeda.

Kunci API

Untuk menggunakan API dalam skrip atau alat Anda sendiri, Anda perlu membuat kunci API untuk otorisasi dan keamanan.

Saat membuat kunci API, pastikan untuk menambahkan izin berikut:

1. Tambahkan aset ke Izin Akses.
2. Tambahkan izin operasi Baca dan Tulis ke game yang Anda pilih, tergantung pada cakupan yang diperlukan dari endpoint yang ingin Anda panggil.

Setelah Anda memiliki kunci API, salin ke header permintaan x-api-key. Semua endpoint memerlukan header permintaan x-api-key.

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

Aplikasi OAuth 2.0

Untuk menggunakan API untuk aplikasi OAuth 2.0 pihak ketiga, tambahkan izin asset:read dan asset:write saat mendaftarkan aplikasi Anda. Pilih izin ini berdasarkan persyaratan dari endpoint yang ingin Anda gunakan.

Buat aset baru

Untuk mengunggah aset baru melalui permintaan HTTP:

1. Salin kunci API ke header permintaan x-api-key dari endpoint Buat Aset.

2. Dalam permintaan Anda:

   1. Tentukan jenis aset yang ditargetkan.
   2. Tambahkan nama dan deskripsi aset Anda.
   3. Tambahkan informasi pembuat.

      • Jika Anda ingin membuat aset atas nama Anda sendiri, tambahkan ID pengguna Anda. Anda dapat menemukan ID pengguna Anda di URL profil Roblox Anda. Misalnya, untuk https://www.roblox.com/users/1234567/profile, ID pengguna Anda adalah 1234567.
      • Jika Anda ingin membuat aset sebagai aset grup, tambahkan ID grup dari grup Anda. Anda dapat menemukan ID grup di URL halaman grup Anda. Misalnya, untuk https://www.roblox.com/groups/7654321/example-group#!/, ID grupnya adalah 7654321.
   4. Tambahkan jalur file dan jenis konten aset Anda.

   Contoh Permintaan untuk Membuat Aset

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nama\",
     \"description\": \"Ini adalah deskripsi\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Gunakan groupId untuk membuat aset grup
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Perbarui aset yang ada

Untuk memperbarui aset yang ada melalui permintaan HTTP:

1. Salin kunci API ke header permintaan x-api-key dari endpoint Perbarui Aset.
2. Tambahkan jenis aset dan ID aset dalam permintaan Anda. Untuk menyalin ID aset Anda:

   1. Navigasikan ke halaman Pembuatan dari Dasbor Pembuat.
   2. Pilih kategori Item Pengembangan.
   3. Pilih kategori aset Anda dan temukan aset yang ditargetkan.
   4. Arahkan kursor ke thumbnail aset yang ditargetkan dan klik tombol ⋯ untuk menampilkan daftar opsi, lalu pilih Salin ID Aset dari daftar.

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

Ambil status operasi aset

Jika permintaan Anda untuk membuat aset baru atau memperbarui aset yang ada berhasil, itu mengembalikan ID Operasi dalam format { "path": "operations/${operationId}" }. Anda dapat menggunakannya untuk memeriksa status dan hasil unggahan Anda dengan langkah-langkah berikut:

1. Salin kunci API ke header permintaan x-api-key dari metode Dapatkan Operasi dan kirim permintaan, seperti contoh kode berikut:

   Contoh Permintaan untuk Dapatkan Operasi

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

2. Jika permintaan Anda berhasil, itu mengembalikan objek Operation, baik menyertakan response yang mewakili informasi aset yang diunggah atau status yang menjelaskan mengapa unggahan aset gagal seperti contoh kode berikut:

   Contoh Respons untuk Dapatkan Operasi

   {
     "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": "Nama",
       "description": "Ini adalah deskripsi",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. OPSIONAL

   Periksa aset yang dibuat di akun Roblox Anda.

   1. Navigasikan ke halaman Inventaris dari akun Roblox Anda.
   2. Pilih Kategori aset yang ingin Anda periksa.
   3. Temukan aset yang ditargetkan dan klik thumbnail-nya untuk melihat aset tersebut.

Tambahkan API aset ke aplikasi OAuth 2.0

Anda dapat membuat aplikasi OAuth 2.0 yang mendukung API Aset untuk memungkinkan pengguna Anda mengunggah dan memperbarui aset ke Roblox.

Untuk menggunakan API Aset untuk aplikasi Anda dan meminta izin dari pengguna Anda, lakukan pengaturan berikut:

1. Saat mendaftarkan aplikasi Anda, di bawah Izin, pilih cakupan asset:read dan asset:write.

2. Saat mengimplementasikan alur otorisasi, sertakan asset:read dan asset:write sebagai parameter cakupan dari URL otorisasi yang mengarahkan pengguna kembali ke aplikasi Anda, seperti contoh berikut:

   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. Saat mengirim permintaan, sertakan token akses dalam header otorisasi dan data formulir konten aset untuk dibuat atau diperbarui dalam URI permintaan. Contoh berikut menunjukkan contoh permintaan untuk mengunggah aset baru:

   Contoh Permintaan

   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\": \"Ini adalah deskripsi\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'