Panduan penggunaan untuk aset

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

• Mengupload 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 sebuah 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 pembatasan dan batasan. Namun, fungsionalitas mengupload konten aset yang didorong oleh endpoint Buat Aset dan Perbarui Aset hanya mendukung jenis aset tertentu dengan pembatasan. Untuk setiap panggilan, Anda hanya dapat membuat atau memperbarui satu aset dengan ukuran file maksimum 20 MB dengan batasan berikut:

Izin keamanan

API mendukung penggunaan pihak pertama dengan otentikasi kunci API dan penggunaan pihak ketiga dalam aplikasi OAuth 2. Masing-masing 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.

Ketika 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 ruang lingkup yang dibutuhkan dari endpoint yang akan Anda panggil.

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

Contoh Header Permintaan API
--header 'x-api-key: ${ApiKey}' \

Aplikasi OAuth 2.0

Untuk menggunakan API untuk aplikasi OAuth 2.0 pihak ketiga, tambahkan ruang lingkup izin asset:read dan asset:write saat mendaftarkan aplikasi Anda. Pilih ruang lingkup ini berdasarkan kebutuhan endpoint yang akan Anda gunakan.

Buat aset baru

Untuk mengupload aset baru melalui permintaan HTTP:

1. Salin kunci API ke dalam 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 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\": \"Name\",
     \"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 dalam 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 target.
   4. Arahkan kursor ke thumbnail aset target dan klik tombol ⋯ untuk menampilkan daftar opsi, lalu pilih Salin ID Aset dari daftar.

Contoh Permintaan untuk Memperbarui Konten Aset
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, ia mengembalikan ID Operasi dalam format { "path": "operations/${operationId}" }. Anda dapat menggunakannya untuk memeriksa status dan hasil upload Anda dengan langkah-langkah berikut:

1. Salin kunci API ke dalam 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, akan mengembalikan objek Operation, termasuk response yang mewakili informasi aset yang diupload atau status yang menjelaskan mengapa upload 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": "Name",
       "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 target dan klik thumbnailnya 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 mengupload 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 ruang lingkup asset:read dan asset:write.

2. Saat menerapkan alur otorisasi, sertakan asset:read dan asset:write sebagai parameter ruang lingkup 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 form data dari konten aset yang akan dibuat atau diperbarui dalam URI permintaan. Contoh berikut menunjukkan permintaan contoh untuk mengupload 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"'