คู่มือการใช้งานสำหรับทรัพย์สิน

API Assets ของ Open Cloud ช่วยให้คุณสามารถอัปโหลดและอัปเดตทรัพย์สินด้วยคำขอ HTTP เพียงครั้งเดียว แทนที่จะนำเข้าทรัพย์สินไปยัง Studio ด้วยตนเอง API นี้สนับสนุน:

• การอัปโหลดทรัพย์สินใหม่
• การอัปเดตทรัพย์สินที่มีอยู่ด้วยการควบคุมเวอร์ชัน
• การอัปเดตข้อมูลเมตาของทรัพย์สิน รวมถึงคำอธิบาย ชื่อที่แสดง ไอคอน และตัวอย่าง
• การจัดการเวอร์ชันของทรัพย์สิน เช่น การย้อนกลับไปยังเวอร์ชันก่อนหน้า
• การตรวจสอบข้อมูลที่มีอยู่ของทรัพย์สิน รวมถึงข้อมูลเมตา เวอร์ชัน และการดำเนินการอัปเดตที่กำลังดำเนินการอยู่

ประเภททรัพย์สินที่รองรับและข้อจำกัด

สำหรับจุดสิ้นสุดที่ไม่สร้างทรัพย์สินใหม่หรืออัปเดตเนื้อหาของทรัพย์สินที่มีอยู่ จะไม่มีข้อจำกัดและข้อกำหนด อย่างไรก็ตาม ฟังก์ชันการอัปโหลดเนื้อหาทรัพย์สินที่ขับเคลื่อนโดยจุดสิ้นสุด Create Asset และ Update Asset รองรับประเภททรัพย์สินที่จำกัดพร้อมข้อจำกัด สำหรับแต่ละการเรียก คุณสามารถสร้างหรืออัปเดตทรัพย์สินได้เพียงหนึ่งรายการโดยมีขนาดไฟล์สูงสุด 20 MB โดยมีข้อจำกัดดังต่อไปนี้:

สิทธิ์ด้านความปลอดภัย

API รองรับการใช้งานทั้งแบบแรกที่ใช้ การอนุญาตด้วยคีย์ API และการใช้งานของบุคคลที่สามใน แอปพลิเคชัน OAuth 2 แต่ละวิธีต้องการการตั้งค่าสิทธิ์ด้านความปลอดภัยที่แตกต่างกัน

คีย์ API

ในการใช้ API ในสคริปต์หรือเครื่องมือของคุณเอง คุณต้อง สร้างคีย์ API สำหรับการอนุญาตและความปลอดภัย

เมื่อสร้างคีย์ API ให้แน่ใจว่าได้เพิ่มสิทธิ์ต่อไปนี้:

1. เพิ่ม assets ใน สิทธิ์การเข้าถึง
2. เพิ่มสิทธิ์การดำเนินการ อ่าน และ เขียน ในเกมที่คุณเลือก ขึ้นอยู่กับขอบเขตที่จำเป็นของจุดสิ้นสุดที่คุณวางแผนจะเรียก

เมื่อคุณมีคีย์ API แล้ว ให้คัดลอกไปยังส่วนหัวคำขอ x-api-key ทุกจุดสิ้นสุดต้องการส่วนหัวคำขอ x-api-key

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

แอป OAuth 2.0

ในการใช้ API สำหรับแอปพลิเคชัน OAuth 2.0 ของบุคคลที่สาม ให้เพิ่มขอบเขตการอนุญาต asset:read และ asset:write เมื่อ ลงทะเบียนแอปของคุณ เลือกขอบเขตเหล่านี้ตามความต้องการของจุดสิ้นสุดที่คุณวางแผนจะใช้

สร้างทรัพย์สินใหม่

ในการอัปโหลดทรัพย์สินใหม่โดยใช้คำขอ HTTP:

1. คัดลอกคีย์ API ไปยังส่วนหัวคำขอ x-api-key ของจุดสิ้นสุด Create Asset

2. ในคำขอของคุณ:

   1. ระบุ ประเภททรัพย์สิน ที่ต้องการ
   2. เพิ่มชื่อและคำอธิบายของทรัพย์สินของคุณ
   3. เพิ่มข้อมูลผู้สร้าง

      • หากคุณต้องการสร้างทรัพย์สิน ในนามของคุณเอง ให้เพิ่ม ID ผู้ใช้ของคุณ คุณสามารถค้นหา ID ผู้ใช้ของคุณได้จาก URL ของโปรไฟล์ Roblox ของคุณ ตัวอย่างเช่น สำหรับ https://www.roblox.com/users/1234567/profile, ID ผู้ใช้ของคุณคือ 1234567
      • หากคุณต้องการสร้างทรัพย์สิน ในฐานะทรัพย์สินของกลุ่ม ให้เพิ่ม ID กลุ่มของคุณ คุณสามารถค้นหา ID กลุ่มได้จาก URL ของหน้ากลุ่มของคุณ ตัวอย่างเช่น สำหรับ https://www.roblox.com/groups/7654321/example-group#!/, ID กลุ่มคือ 7654321
   4. เพิ่มเส้นทางไฟล์และประเภทเนื้อหาของทรัพย์สินของคุณ

   ตัวอย่างคำขอสำหรับสร้างทรัพย์สิน

   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}\" # ใช้ groupId สำหรับการสร้างทรัพย์สินของกลุ่ม
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

อัปเดตทรัพย์สินที่มีอยู่

ในการอัปเดตทรัพย์สินที่มีอยู่โดยใช้คำขอ HTTP:

1. คัดลอกคีย์ API ไปยังส่วนหัวคำขอ x-api-key ของจุดสิ้นสุด Update Asset
2. เพิ่มประเภททรัพย์สินและ ID ของทรัพย์สินในคำขอของคุณ เพื่อคัดลอก ID ของทรัพย์สินของคุณ:

   1. ไปที่หน้า Creation ของ Creator Dashboard
   2. เลือกหมวดหมู่ Development Items
   3. เลือกหมวดหมู่ของทรัพย์สินของคุณและค้นหาทรัพย์สินที่ต้องการ
   4. เลื่อนเมาส์ไปที่ภาพขนาดย่อของทรัพย์สินที่ต้องการและคลิกที่ปุ่ม ⋯ เพื่อแสดงรายการตัวเลือก จากนั้นเลือก Copy Asset ID จากรายการ

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

ดึงสถานะการดำเนินการทรัพย์สิน

หากคำขอของคุณในการสร้างทรัพย์สินใหม่หรืออัปเดตทรัพย์สินที่มีอยู่สำเร็จ จะส่งคืน Operation ID ในรูปแบบ { "path": "operations/${operationId}" } คุณสามารถใช้เพื่อตรวจสอบสถานะและผลลัพธ์ของการอัปโหลดของคุณโดยทำตามขั้นตอนต่อไปนี้:

1. คัดลอกคีย์ API ไปยังส่วนหัวคำขอ x-api-key ของวิธี Get Operation และส่งคำขอ เช่น ตัวอย่างโค้ดต่อไปนี้:

   ตัวอย่างคำขอสำหรับการดึงการดำเนินการ

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

2. หากคำขอของคุณสำเร็จ จะส่งคืนวัตถุ Operation ซึ่งอาจรวมถึง response ที่แสดงข้อมูลทรัพย์สินที่อัปโหลดหรือ status ที่อธิบายว่าทำไมการอัปโหลดทรัพย์สินจึงล้มเหลว เช่น ตัวอย่างโค้ดต่อไปนี้:

   ตัวอย่างการตอบกลับสำหรับการดึงการดำเนินการ

   {
     "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. ทางเลือก

   ตรวจสอบทรัพย์สินที่สร้างขึ้นในบัญชี Roblox ของคุณ

   1. ไปที่หน้า Inventory ของ บัญชี Roblox ของคุณ
   2. เลือก Category ของทรัพย์สินที่คุณต้องการตรวจสอบ
   3. ค้นหาทรัพย์สินที่ต้องการและคลิกที่ภาพขนาดย่อเพื่อดูทรัพย์สิน

เพิ่ม API ทรัพย์สินไปยังแอป OAuth 2.0

คุณสามารถสร้าง แอปพลิเคชัน OAuth 2.0 ที่สนับสนุน API ทรัพย์สินเพื่ออนุญาตให้ผู้ใช้ของคุณอัปโหลดและอัปเดตทรัพย์สินไปยัง Roblox

ในการใช้ API ทรัพย์สินสำหรับแอปพลิเคชันของคุณและขอสิทธิ์จากผู้ใช้ของคุณ ให้ดำเนินการตั้งค่าต่อไปนี้:

1. เมื่อ ลงทะเบียนแอปพลิเคชันของคุณ ในส่วน Permissions ให้เลือกขอบเขต asset:read และ asset:write

2. เมื่อ ดำเนินการตามกระบวนการอนุญาต ให้รวม asset:read และ asset:write เป็นพารามิเตอร์ขอบเขตของ URL การอนุญาตที่เปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปพลิเคชันของคุณ เช่น ตัวอย่างต่อไปนี้:

   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. เมื่อส่งคำขอ ให้รวมโทเค็นการเข้าถึงในส่วนหัวการอนุญาตและข้อมูลฟอร์มของเนื้อหาทรัพย์สินที่ต้องการสร้างหรืออัปเดตใน URI ของคำขอ ตัวอย่างต่อไปนี้แสดงคำขอตัวอย่างสำหรับการอัปโหลดทรัพย์สินใหม่:

   ตัวอย่างคำขอ

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