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

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

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

ประเภทสินทรัพย์ที่สนับสนุนและขีดจํากัด

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

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

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

คีย์ API

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

เมื่อคุณสร้างคีย์ API คุณไม่สามารถสลับสิทธิ์การเป็นเจ้าของระหว่างบุคคลหรือกลุ่มได้ ดังนั้นหากคุณสร้างคีย์ API ภายใต้บัญชีของคุณเอง คุณไม่สามารถใช้มันในการจัดการทรัพยากรกลุ่มได้

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

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

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

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

แอป OAuth 2.0

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

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

เพื่ออัปโหลดสินทรัพย์ใหม่โดยคำขอ HTTP:

1. คัดลอกคีย์ API ไปยังหัวข้อคำขอ x-api-key ของเอนด์พอยท์ สร้างสินทรัพย์

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

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

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

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

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

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

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

   1. นําทางไปที่หน้า การสร้าง ของ แดชบอร์ดผู้สร้าง 2. เลือกหมวดหมู่ รายการการพัฒนา 3. เลือกประเภทของสินทรัพย์และค้นหาสินทรัพย์เป้าหมาย
   2. เลื่อนเมาส์ไปที่ภาพขนาดย่อของสินทรัพย์เป้าหมายและคลิกที่ปุ่ม ⋯ เพื่อแสดงรายการตัวเลือกจากนั้นเลือก คัดลอก ID สินทรัพย์ จากรายการ

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

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

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

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

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

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

   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. (オプション) Roblox บัญชีของคุณตรวจสอบสินทรัพย์ที่สร้างขึ้น

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

เพิ่ม API สําหรับทรัพยากรไปยังแอป OAuth 2.0

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

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

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

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

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