Petunjuk Penggunaan untuk Aset

*Konten ini diterjemahkan menggunakan AI (Beta) dan mungkin mengandung kesalahan. Untuk melihat halaman ini dalam bahasa Inggris, klik di sini.

API Aset Open Cloud memungkinkan Anda untuk mengunggah dan menyimpan sumber daya dengan satu permintaan HTTP daripada mengimpornya secara manual ke Studio. API ini mendukung:

  • Mengunggah aset baru.
  • Meng-update aset yang ada dengan kontrol versi.
  • Meng-update deskripsi, nama, ikon, dan pratinjau aset.
  • Mengelola versi aset, seperti mundur ke versi sebelumnya yang ditentukan.
  • Memeriksa informasi yang ada dari aset, termasuk metadata, versi, dan setiap operasi pembaruan dalam proses.

Jenis dan Batas Aset Dukungan

Untuk endpoints yang tidak menciptakan aset baru atau menyimpan konten aset yang sudah ada, tidak ada batasan dan batasan. Namun, konten aset yang diunggah melalui Buat Asset dan Update Asset endpoints hanya mendukung jenis aset yang terbatas dengan batasan. Untuk setiap panggilan, Anda hanya dapat menciptakan

Jenis AsetFormatJenis KontenKetentuan
Suara

  • .mp3 >
  • .ogg >
  • >

  • audio/mpeg >
  • audio/ogg >
  • >

  • Sampai 7 menit durasi.
  • Sampai 100 unduhan per bulan jika Anda ID-verified.
  • Up to 10 total unduhan per bulan jika Anda bukan ID-verified.
  • 1> Tidak tersedia untuk diperbarui. 1>

Stiker

    .png > .jpeg > 0> 1> 2> .bmp2> >0> 5> 6> .tga6> >5>

    9> 0> .bmp0>

    9>

  • 1> .png
  • 1>

    image/png > image/jpeg > 0> image/bmp0> >0> 3> 4> image/tga4> >4>

    7> 8> image/mpeg

    8> >8> 0> 1> 4>

  • Tidak tersedia untuk diperbarui.
  • Harus lebih kecil dari 8000x8000 pixel.
Model

  • .fbx >
  • >

  • model/fbx >
  • >

Tergantung pada kasus penggunaan Anda, pertimbangkan untuk mengunggah beberapa model tertentu secara manual menggunakan 3D Importer.

Pengimpor 3D memberikan pratinjau 3D, berbagai pemeriksaan kesalahan, dan banyak pengaturan impor yang dapat disesuaikan.

Video

  • .mp4 >
  • .mov >
  • >

    video/mp4 video/mov 1> video/ogg1> sebuah video/mp4 yang dapat dihosting secara terbaik.

    video/mp4 video/mov 1> video/ogg

    1>

    Hingga 30 detik durasi. Hingga 4096x2160 resolusi. Hingga 375 MB. 1> Saat ini, hanya audio dan/atau video Inggris dan/atau Spanyol yang diizinkan. 1> 4> Saat ini, hanya 3 unduhan per bulan j

Izinkan Keamanan

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

Kunci API

Untuk menggunakan API di skrip atau alat Anda sendiri, Anda perlu Mengatur kunci API untuk autorisasi dan keamanan. Untuk menangani aset yang Anda miliki secara individual, buat kunci API di bawah akun Anda. Untuk mengelola aset yang dimiliki grup secara individual, buat kunci API di bawah grup target. Untuk informasi lebih lanjut tentang kunci API grup, lihat Izin

Setelah Anda menciptakan kunci API, Anda tidak dapat mengubah kepemilikan antara individu atau kelompok, jadi jika Anda menciptakan kunci API di bawah akun Anda sendiri, Anda tidak dapat menggunakannya untuk mengelola aset grup.

Terlepas dari apakah Anda menciptakan kunci API untuk diri sendiri atau grup Anda, pastikan untuk menambahkan izin berikut:

  1. Tambahkan asi ke Izinkan Akses .
  2. Tambahkan Baca dan Tulis izin operasi ke pengalaman yang Anda pilih, tergantung pada scope yang diperlukan dari endpoint yang Anda berencana untuk memanggil.

Setelah Anda mendapatkan kunci API, salinan itu ke x-api-key request header. Semua ujung memerlukan x-api-key request header.

Example API Request Header

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

OAuth 2.0 Aplikasi

Untuk menggunakan API untuk aplikasi OAuth 2.0 pihak ketiga, tambahkan scope izin asset:read dan asset:write ketika mendaftarkan aplikasi Anda. Pilih scope ini berdasarkan persyaratan endpoint yang Anda rencanakan akan digunakan.

Membuat Aset Baru

Untuk mengunggah aset baru dengan permintaan HTTP:

  1. Kopi kunci API ke x-api-key request header dari Mbuat Aset endpoint.

  2. Dalam permintaan Anda:

    1. Spesifikasi target jenis aset .
    2. Tambahkan nama dan deskripsi aset Anda.
    3. Tambahkan informasi pencipta.
      • Jika Anda ingin membuat aset atas nama 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 kelompok , tambahkan ID kelompok grup Anda. Anda dapat menemukan ID kelompok di URL halaman grup Anda. Misalnya, untuk https://www.roblox.com/groups/7654321/example-group#!/ , ID kelompok adalah 7654321</
    4. Tambahkan jalan file dan jenis konten dari aset Anda.
    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}\" # Gunakan groupId untuk menciptakan aset kelompok
    }
    }
    }"' \
    --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Memperbarui Aset yang ada

Untuk menyetujui aset yang ada dengan permintaan HTTP:

  1. Salinan kunci API ke x-api-key request header of the Update Asset endpoint.
  2. Tambahkan jenis aset dan ID aset dalam permintaan Anda. Untuk menyalin ID aset Anda:
    1. Navigate to the Pembuatan page of the Dashboard Pencipta .
    2. Pilih kategori Barang Pengembangan .
    3. Pilih kategori aset Anda dan temukan aset target.
    4. Hover over the thumbnail of the target aset and click the button to display a list of options, then select Copy Asset ID from the list.
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}"'

Mengambil Status Operasi Aset

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

  1. Salinan kunci API ke x-api-key request header of the Dapatkan Operasi method and send the permintaan, like the following code sample:

    Example Request for Get Operation

    curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
    --header 'x-api-key: {$ApiKey}'
  2. Jika permintaan Anda berhasil, itu mengembalikan objek Operation, termasuk response mewakili informasi aset yang diunggah atau status menjelaskan mengapa pengunggah aset gagal sebagai contoh kode berikut:

    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. (Opsional) Periksa aset yang dibuat di akun Roblox Anda.

    1. Navigate to the Inventaris page of your akun Roblox .
    2. Pilih Kategori dari aset yang ingin Anda periksa.
    3. Temukan aset target dan klik thumbnail untuk menampilkan aset.

Menambahkan API Asset ke OAuth 2.0 Apps

Anda dapat menciptakan aplikasi OAuth 2.0 yang mendukung API Asset untuk memungkinkan pengguna Anda untuk mengunggah dan menyimpan sumber daya ke Roblox.

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

  1. Ketika mendaftarkan aplikasi Anda , di bawah keamanan , pilih asi:read dan 1>asi:write1> scope.

  2. Ketika menerapkan aliran otorisasi, termasuk asset:read dan asset:write sebagai parameter scope dari URL otorisasi yang mengirimkan pengguna kembali ke aplikasi Anda, seperti contoh berikut:


    https://www.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. Ketika mengirim permintaan, termasuk token akses di header autorisasi dan data formulir konten aset untuk membuat atau menyetel ulang dalam permintaan UI di. Contoh berikut menunjukkan contoh permintaan untuk mengunggah aset baru:

    Permintaan Contoh

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