จัดการคีย์ API

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

API ของ Open Cloud ทุกตัวต้องการให้คุณสร้างคีย์ API ที่มีสิทธิ์ที่ถูกต้องและรวม x-api-key header ในคำขอของคุณ ซึ่งช่วยให้แอปพลิเคชันสามารถตรวจสอบตัวตนกับ Open Cloud ในนามของคุณ

สร้างคีย์ API

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

สำหรับรายละเอียดเกี่ยวกับวิธีการสร้างคีย์ API สำหรับการจัดการทรัพยากรของกลุ่ม โปรดดูที่ส่วน สร้างคีย์ API สำหรับการจัดการทรัพยากรที่เป็นของกลุ่ม ด้านล่าง

ในการสร้างคีย์ API:

1. ใน Creator Dashboard ไปที่หน้า API Keys

2. คลิกปุ่ม Create API Key

3. ป้อนชื่อที่ไม่ซ้ำกันสำหรับคีย์ API ของคุณ ใช้ชื่อที่ช่วยให้คุณจำวัตถุประสงค์ได้ในภายหลัง เช่น PLACE_PUBLISHING_KEY สำหรับการเผยแพร่สถานที่ในเกมของคุณ

4. ในส่วน Access Permissions ให้เลือก API จากเมนู Select API System ทำซ้ำขั้นตอนนี้หากคุณต้องการเพิ่มหลาย API ลงในคีย์

5. หากมีความจำเป็น ให้เลือกเกมที่คุณต้องการเข้าถึงด้วยคีย์ API

   คุณสามารถปิดการใช้งาน Restrict by Experience ได้ตามต้องการ เมื่อปิดการใช้งาน คีย์ API ของคุณจะเข้าถึงเกมที่เป็นของผู้ใช้ทั้งหมดและเกมที่เป็นของกลุ่มที่คุณมีสิทธิ์ที่เหมาะสม รวมถึงเกมใดๆ ที่คุณสร้างในอนาคต

6. จากเมนูดรอปดาวน์ Select Operations ให้เลือกการดำเนินการที่คุณต้องการเปิดใช้งานสำหรับคีย์ API

   การดำเนินการส่วนใหญ่ใน API reference รวมถึงขอบเขตสิทธิ์ที่จำเป็น ตัวอย่างเช่น การดำเนินการ flush memory store ต้องการสิทธิ์ universe.memory-store:flush

   สำหรับรายการของขอบเขตทั้งหมดและ API ที่พวกเขาสนับสนุน โปรดดูที่ Scopes

7. OPTIONAL

   ในส่วน Security ให้จำกัดการเข้าถึง IP ไปยังคีย์โดยใช้ CIDR notation คุณสามารถค้นหาที่อยู่ IP ของเครื่องคอมพิวเตอร์ของคุณและเพิ่มลงในส่วน Accepted IP Addresses พร้อมกับที่อยู่ IP เพิ่มเติมสำหรับผู้ที่ต้องการเข้าถึง หากคุณไม่มี IP ที่คงที่ หรือคุณใช้คีย์ API ในสภาพแวดล้อมท้องถิ่นเท่านั้น คุณสามารถปล่อยให้การตั้งค่า Restrict IP addresses ไม่ถูกเลือกเพื่ออนุญาตให้ IP ใดๆ ใช้คีย์ API ของคุณ

8. OPTIONAL

   เพื่อเพิ่มการป้องกันเพิ่มเติมสำหรับทรัพยากรของคุณ ให้ตั้งค่าวันหมดอายุสำหรับคีย์ของคุณ

9. คลิกปุ่ม Save & Generate key

10. คัดลอกและบันทึกสตริงคีย์ API ไปยังสถานที่ที่ปลอดภัย ไม่ใช่ ที่เก็บสาธารณะสำหรับโค้ดของคุณ

11. ตรวจสอบสถานะของคีย์ API ของคุณในหน้า API Extensions ของ Creator Dashboard

สร้างคีย์ API สำหรับการจัดการทรัพยากรที่เป็นของกลุ่ม

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

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

1. สร้างบัญชี Roblox ใหม่ที่ใช้เฉพาะสำหรับการทำงานอัตโนมัติของคุณ
2. เชิญบัญชีใหม่เข้ากลุ่มของคุณ
3. มอบบทบาทกลุ่มให้กับมันโดยมีสิทธิ์ขั้นต่ำที่จำเป็นสำหรับงานของมัน (เช่น "สร้างและแก้ไขประสบการณ์กลุ่ม" เท่านั้น)
4. ลงชื่อเข้าใช้บัญชีใหม่และทำตามขั้นตอนในส่วนด้านบนเพื่อ สร้างคีย์ API
5. ใช้คีย์ API ที่สร้างขึ้นสำหรับการทำงานอัตโนมัติของทรัพยากรกลุ่ม

แนวทางปฏิบัติที่ดีที่สุดในการจัดการคีย์ API

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

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

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

• ใช้การจำกัดที่อยู่ IP: จำกัดการเข้าถึงคีย์ API ไปยังที่อยู่ IP หรือช่วง CIDR ที่เฉพาะเจาะจงเพื่อป้องกันการใช้งานที่ไม่ได้รับอนุญาตจากสถานที่ที่ไม่รู้จัก อย่าใช้การจำกัดที่อยู่ IP เมื่อใช้คีย์ API ของคุณในสถานที่ Roblox เพื่อให้แน่ใจว่าคีย์ของคุณสามารถใช้กับเซิร์ฟเวอร์ Roblox ได้

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

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

• เก็บคีย์ API อย่างปลอดภัย: อย่าเก็บคีย์ API ไว้ในโค้ดต้นฉบับ ระบบควบคุมเวอร์ชัน หรือสคริปต์ที่อาจถูกเปิดเผย ใช้ระบบการจัดการความลับสำหรับการเก็บและควบคุมการเข้าถึงคีย์ของคุณ ในสถานที่ Roblox ให้ใช้ Secrets Store

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

รูปแบบ CIDR

เพื่อปกป้องทรัพยากรของคุณเพิ่มเติม เมื่อ สร้างคีย์ API ให้ระบุที่อยู่ IP ที่สามารถเข้าถึงคีย์ API ได้โดยใช้ที่อยู่ IP ปกติหรือใช้ CIDR notation ที่อยู่ IP CIDR จะมีลักษณะเหมือนที่อยู่ IP ปกติ แต่จะสิ้นสุดด้วยเครื่องหมายทับและทศนิยมที่แสดงถึงจำนวนบิตของที่อยู่ IP ที่สำคัญสำหรับการจัดเส้นทางเครือข่าย:

• ปกติ: 192.168.0.0
• CIDR: 192.168.0.0/24

ส่วนแรกคือที่อยู่ IP และส่วนหลังคือ netmask นับจำนวนบิตของ 1 ในรูปแบบไบนารี ในตัวอย่างก่อนหน้านี้ 24 หมายถึง 255.255.255.0 (24 1s) ที่อนุญาตให้ IP ทั้งหมดระหว่าง 192.168.0.0 และ 192.168.0.255 การเข้าใจรูปแบบ CIDR เป็นสิ่งที่มีประโยชน์โดยเฉพาะหากคุณวางแผนที่จะเรียกใช้แอปพลิเคชันของคุณบนเซิร์ฟเวอร์

สถานะคีย์ API

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

ตรวจสอบคีย์ API

POST api-keys/v1/introspect

ดึงข้อมูลเกี่ยวกับคีย์ API ตรวจสอบว่าคีย์สามารถใช้จากที่อยู่ IP ของผู้ร้องขอได้หรือไม่ และคีย์หรือผู้ใช้ที่สร้างล่าสุดอยู่ภายใต้การควบคุมหรือไม่

คำขอ

(application/json)

curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

การตอบกลับ

มีตัวระบุทรัพยากรสี่ตัวที่สามารถปรากฏในแต่ละวัตถุขอบเขต:

• userId
• groupId
• universeId
• universeDatastore

ตัวระบุ userId และ groupId จะเกี่ยวข้องเฉพาะกับขอบเขตที่มีเป้าหมายผู้สร้าง ตัวระบุ universeDatastore จะเกี่ยวข้องเฉพาะกับขอบเขตที่มีเป้าหมาย universe-datastore ตัวระบุทรัพยากรจะถูกละเว้นสำหรับขอบเขตที่ไม่สนับสนุนการเลือกทรัพยากร

เครื่องหมายดอกจัน (*) ในรายการตัวระบุทรัพยากรแสดงว่าขอบเขตมีสิทธิ์ในทรัพยากรทั้งหมดของประเภทนั้น

{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}