จัดการ API keys

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

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

สร้าง API keys

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

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

ในการสร้าง API key:

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

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

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

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

5. หากมีความเหมาะสม ให้เลือกเกมที่คุณต้องการเข้าถึงด้วย API key

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

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

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

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

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

8. (เลือกได้): เพื่อเพิ่มการป้องกันสำหรับทรัพยากรของคุณ ตั้งวันหมดอายุสำหรับ key ของคุณ

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

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

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

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

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

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

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

วิธีปฏิบัติที่ดีที่สุดในการจัดการ API Keys

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

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

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

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

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

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

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

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

รูปแบบ CIDR

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

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

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

สถานะของ API key

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

ตรวจสอบ API keys

POST api-keys/v1/introspect

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

คำขอ

(application/json)

ตัวอย่างคำขอ Introspect API Key
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 มีความเกี่ยวข้องเฉพาะกับ scopes ที่มีเป้าหมายเป็นผู้สร้าง ตัวระบุ universeDatastore มีความเกี่ยวข้องเฉพาะกับ scopes ที่มีเป้าหมายเป็น universe-datastore ตัวระบุทรัพยากรจะถูกละเว้นสำหรับ scopes ที่ไม่สนับสนุนการเลือกทรัพยากร

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

ตัวอย่างการตอบสนอง Introspect API Key
{
  "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"
}