คู่มือการใช้งานสำหรับแอสเซ็ต

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

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

ประเภทของแอสเซ็ตที่รองรับและขีดจำกัด

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

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

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

คีย์ API

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

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

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

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

ตัวอย่างส่วนหัวคำขอ API
--header 'x-api-key: ${ApiKey}' \

แอป OAuth 2.0

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

สร้างแอสเซ็ตใหม่

เพื่ออัปโหลดแอสเซ็ตใหม่ด้วยคำขอ HTTP:

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

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

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

      • หากคุณต้องการสร้างแอสเซ็ต แทนตัวเอง ให้เพิ่ม 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 endpoint
2. เพิ่มประเภทแอสเซ็ตและ ID ของแอสเซ็ตในคำขอของคุณ เพื่อคัดลอก ID ของแอสเซ็ตของคุณ:

   1. ไปที่หน้าการ สร้าง ของ Creator Dashboard
   2. เลือกหมวดหมู่ Development Items
   3. เลือกหมวดหมู่ของแอสเซ็ตของคุณและหาแอสเซ็ตเป้าหมาย
   4. เลือกโปสเตอร์ของแอสเซ็ตเป้าหมายแล้วคลิกปุ่ม ⋯ เพื่อแสดงรายการตัวเลือก จากนั้นเลือก คัดลอก 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. ไปที่หน้า Inventories ของ บัญชี Roblox ของคุณ
   2. เลือก หมวดหมู่ ของแอสเซ็ตที่คุณต้องการตรวจสอบ
   3. หาแอสเซ็ตเป้าหมายและคลิกโปสเตอร์เพื่อดูแอสเซ็ต

เพิ่ม Assets API ไปยังแอป OAuth 2.0

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

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

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

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. เมื่อส่งคำขอ ให้รวม token การเข้าถึงในส่วนหัวการอนุญาตและข้อมูลฟอร์มของเนื้อหาของแอสเซ็ตที่ต้องการสร้างหรือปรับปรุงใน 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"'