Panduan penggunaan untuk aset

The API Aset dari Open Cloud memungkinkan Anda untuk mengunggah dan memperbarui aset dengan satu permintaan HTTP tunggal daripada mem导入nya secara manual ke Studio.API ini mendukung:

• Memuat aset baru.
• Memperbarui aset yang ada dengan kontrol versi.
• Memperbarui metadata aset, termasuk deskripsi, nama tampilan, ikon, dan pratinjau.
• 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 aset dan batas yang didukung

Untuk akhiran yang tidak membuat aset baru atau memperbarui konten aset yang ada, tidak ada batasan dan batasan.Namun, fungsi pengunggahan konten aset yang didukung oleh Buat Asset dan Update Asset akhir hanya mendukung jenis aset terbatas dengan batasan.Untuk setiap panggilan, Anda hanya dapat membuat atau memperbarui satu aset dengan ukuran file hingga 20 MB dengan batas berikut:

Otorisasi keamanan

API mendukung penggunaan pertama dengan otorisasi kunci API dan penggunaan pihak ketiga di 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.Untuk mengelola aset yang Anda miliki secara individual, buat kunci API di bawah akun Anda.Untuk mengelola aset milik kelompok, buat kunci API di bawah gruptarget.Untuk informasi lebih lanjut tentang kunci API milik kelompok, lihat Izin kunci API milik kelompok.

Setelah Anda membuat kunci API, Anda tidak dapat beralih kepemilikannya di antara individ atau kelompok, jadi jika Anda membuat kunci API di bawah akun Anda sendiri, Anda tidak dapat menggunakannya untuk mengelola aset kelompok.

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

1. Tambahkan aset ke Izin Akses .
2. Tambahkan Baca dan Tulis izin operasi ke pengalaman yang dipilih Anda, tergantung pada cakupan yang diperlukan dari akhiran yang direncanakan untuk dipanggil.

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

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

Aplikasi OAuth 2.0

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 ujung yang Anda rencanakan untuk digunakan.

Buat aset baru

Untuk mengunggah aset baru dengan permintaan HTTP:

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

2. Dalam permintaan Anda:

   1. Tentukan jenis aset target .
   2. Tambahkan nama dan deskripsi aset Anda.
   3. Tambahkan informasi pencipta.

      • Jika Anda ingin membuat aset atas nama Anda sendiri , tambahkan ID pengguna Anda.Anda dapat menemukan ID pengguna Anda di URL profil Roblox Anda.Sebagai contoh, untuk https://www.roblox.com/users/1234567/profile , ID pengguna Anda adalah 1234567 .
      • Jika Anda ingin membuat aset sebagai aset kelompok , tambahkan ID kelompok dari kelompok Anda.Anda dapat menemukan ID grup di URL halaman grup Anda.Sebagai contoh, untuk https://www.roblox.com/groups/7654321/example-group#!/ , ID grup adalah 7654321 .
   4. Tambahkan jalur file dan jenis konten 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 membuat aset kelompok
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Perbarui aset yang ada

Untuk memperbarui aset yang ada dengan permintaan HTTP:

1. Salin kunci API ke kepala permintaan x-api-key dari endpoint Update Asset.
2. Tambahkan jenis aset dan ID aset di permintaan Anda. Untuk menyalin ID aset Anda:

   1. Navigasikan ke halaman Penciptaan dari Dashboard Pencipta .
   2. Pilih kategori Item Pengembangan .
   3. Pilih kategori aset Anda dan temukan aset target.
   4. Pasang mouse di atas thumbnail aset target dan klik tombol ⋯ untuk menampilkan daftar opsi, lalu pilih Copy Asset ID dari daftar.

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

Ambil status operasi aset

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

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

   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 akan mengembalikan objek Operation yang termasuk menyertakan response mewakili informasi aset yang diunggah atau status menjelaskan mengapa pengunggahan aset gagal seperti 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. (Opsi) Periksa aset yang dibuat di akun Roblox Anda.

   1. Navigasikan ke halaman Inventaris dari akun Roblox Anda.
   2. Pilih Kategori dari aset yang ingin Anda periksa.
   3. Temukan aset target dan klik thumbnailnya untuk melihat aset.

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 aset:dibaca dan aset:ditulis scope.

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

   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. Saat mengirim permintaan, termasuk token akses dalam header otorisasi dan data bentuk konten aset untuk dibuat atau diperbarui dalam URI permintaan.Contoh berikut menunjukkan permintaan sampel 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"'