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. Untuk ikon tempat dan thumbnail halaman detail pengalaman, lihat Kelola ikon dan thumbnail pengalaman.
- 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 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:
| Jenis aset | Format | Jenis konten | Pembatasan |
|---|---|---|---|
| Animasi |
|
|
|
| Audio |
|
|
|
| Decal, Gambar |
|
|
|
| Mesh | Hanya Roblox |
|
|
| Model |
|
|
|
| Video |
|
|
|
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:
- Tambahkan aset ke Izin Akses.
- 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 cakupan ini berdasarkan persyaratan endpoint yang ingin Anda gunakan.
Buat aset baru
Untuk mengunggah aset baru melalui permintaan HTTP:
Salin kunci API ke header permintaan x-api-key dari endpoint Buat Aset.
Dalam permintaan Anda:
- Tentukan jenis aset yang ditargetkan.
- Tambahkan nama dan deskripsi aset Anda.
- 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.
- Tambahkan jalur file dan jenis konten aset Anda.
Contoh Permintaan untuk Membuat Asetcurl --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:
- Salin kunci API ke header permintaan x-api-key dari endpoint Perbarui Aset.
- Tambahkan jenis aset dan ID aset dalam permintaan Anda. Untuk menyalin ID aset Anda:
- Navigasikan ke halaman Pembuatan dari Dasbor Pembuat.
- Pilih kategori Item Pengembangan.
- Pilih kategori aset Anda dan temukan aset yang ditargetkan.
- 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}"'Untuk memperbarui ikon tempat atau thumbnail halaman detail pengalaman, lihat Kelola ikon dan thumbnail pengalaman.
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:
Salin kunci API ke header permintaan x-api-key dari metode Dapatkan Operasi dan kirim permintaan, seperti contoh kode berikut:
Contoh Permintaan untuk Dapatkan Operasicurl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \--header 'x-api-key: {$ApiKey}'Jika permintaan Anda berhasil, itu mengembalikan objek Operation, baik termasuk 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"}}}- OPSIONALPeriksa aset yang dibuat di akun Roblox Anda.
- Navigasikan ke halaman Inventaris dari akun Roblox Anda.
- Pilih Kategori aset yang ingin Anda periksa.
- Temukan aset yang ditargetkan dan klik thumbnail-nya untuk melihat aset tersebut.
Gunakan aset yang diunggah di Studio
Aset yang Anda unggah menjadi milik pengguna atau grup dalam creationContext dari permintaan Anda, sehingga tersedia di Studio seperti aset lain yang dimiliki oleh pembuat:
- Masukkan dari Toolbox atau Manajer Aset.
- Model diunggah sebagai paket, jadi periksa Inventaris ⟩ Paket Saya di Toolbox (atau Kreasi ⟩ Paket Grup jika dimiliki oleh grup).
- Untuk menggunakan aset dalam properti, masukkan rbxassetid:// diikuti oleh assetId dari respons operasi di jendela Properti. Dalam skrip, tetapkan string itu ke properti string seperti AudioPlayer.Asset, atau kirim assetId ke Content.fromAssetId() untuk properti tipe Content, seperti Decal.ColorMapContent. Untuk informasi lebih lanjut, lihat rbxassetid.
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:
Saat mendaftarkan aplikasi Anda, di bawah Izin, pilih cakupan asset:read dan asset:write.
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=6789Saat 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 Permintaancurl --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"'