คู่มือการใช้งานสำหรับร้านข้อมูล

*เนื้อหานี้แปลโดยใช้ AI (เวอร์ชัน Beta) และอาจมีข้อผิดพลาด หากต้องการดูหน้านี้เป็นภาษาอังกฤษ ให้คลิกที่นี่

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

การใช้งาน

คุณสามารถปรับปรุงหลายพื้นที่ในกระบวนการทำงานของคุณโดยการเข้าถึงข้อมูลด้วย API เหล่านี้ เช่น:

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

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

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

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

ความแตกต่างกับ Engine API

แม้ว่า API เมฆเปิดจะคล้ายกับ DataStoreService แต่มีความแตกต่างสำคัญไม่กี่อย่าง:

  • ชื่อ ID และชื่อร้านข้อมูลของจักรวาล : ไม่เหมือนกับ Engine APIเครื่องยนต์, Open Cloud APIs เป็นไร้สถานะและสามารถมาจากทุกที่, ดังนั้นคุณต้องให้ universal ID , ตัวระบุเฉพาะของประสบการณ์ของคุณ, และชื่อร้านข้อมูล เมื่อส่งคำขอ เสมอสำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีรับ ID จักรวาล ดูที่ ID จักรวาล

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

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

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

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

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

เครื่องมือสร้าง

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

พอร์ทัลสนับสนุนสินค้าคงคลังผู้ใช้

ส่วนนี้ให้ตัวอย่างที่ชัดเจนของการสร้างพอร์ทัลสนับสนุนรายการสิ่งของผู้ใช้ในภาษาพายธองใน Python คลังไอเท็มทำการแก้ไข ร้านค้า

สำหรับตัวอย่างนี้, กำลังติดตาม:

  • ชื่อของคลังข้อมูลที่เก็บสินค้าคงคลังของผู้ใช้มีชื่อว่า Inventory

  • สคูลข้อมูลสำหรับแต่ละรายการข้อมูลคือ "userId": {"currency": number, "weapon": string, "level": number} คีย์คือเพียง userId

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

จากระดับสูง คุณสามารถสร้างแอป Python โดยเพิ่มสิทธิ์การเข้าถึง API แล้วเพิ่มสคริปต์

เพิ่มสิทธิ์การใช้คีย์ API สำหรับร้านข้อมูล

เมื่อสร้างคีย์ API สําหรับตัวอย่างนี้ ให้แน่ใจว่าคุณดําเนินการตามการตั้งค่าต่อไปนี้:

  1. จากเมนู เลือกระบบ API ในส่วน สิทธิ์การเข้าถึง เลือก universe-datastores

  2. (เลือกได้) ในส่วน ร้านข้อมูล เลือกการดำเนินการ API สำหรับร้านข้อมูลเฉพาะ

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

  3. เลือกการดำเนินการ API สำหรับประสบการณ์ทั้งหมด

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

  4. ในส่วน ความปลอดภัย กำหนดการเข้าถึง IP โดยเฉพาะเพื่อกุญแจโดยใช้ การบันทึก CIDR และตั้งวันหมดอายุโดยเฉพาะเพื่อให้กุญแจหยุดทำงานหลังวันที่นั้นโดยอัตโนมัติสำหรับตัวอย่างนี้ หากคุณวางแผนที่จะทดสอบท้องถิ่นก่อน คุณสามารถลบการจำกัด IP โดยการตั้งค่าเป็น 0.0.0.0/0 และปล่อยให้หมดอายุใน 30 วัน

เพิ่มสคริปต์สำหรับพอร์ทัลสนับสนุนสินค้าคงคลังของผู้ใช้

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

dataStoresMethods.js
const fetch = require('node-fetch');



class DataStores {

  constructor() {

    this._baseUrl =

      'https://apis.roblox.com/datastores/v1/universes/{universeId}';

    this._apiKey = process.env.API_KEY;

    this._universeId = 'UNIVERSE_ID';

    this.ATTR_HDR = 'Roblox-entry-Attributes';

    this.USER_ID_HDR = 'Roblox-entry-UserIds';

    this._objectsUrl = `${this._baseUrl}${this._universeId}/standard-datastores/datastore/entries/entry`;

    this._incrementUrl = `${this._objectsUrl}/increment`;

    this._listObjectsUrl = `${this._baseUrl}${this._universeId}/standard-datastores/datastore/entries`;

  }



  async _getHeaders() {

    return { 'x-api-key': this._apiKey };

  }



  async getEntry(datastore, objectKey, scope = null) {

    const url = `${

      this._objectsUrl

    }?datastoreName=${datastore}&entryKey=${objectKey}&scope=${scope || ''}`;

    const response = await fetch(url, { headers: await this._getHeaders() });

    const data = await response.json();

    return data;

  }



  async listEntries(datastore, scope = null, prefix = '', limit = 100) {

    const url = `${this._listObjectsUrl}?datastoreName=${datastore}&scope=${scope}&prefix=${prefix}&limit=${limit}`;

    const response = await fetch(url, { headers: await this._getHeaders() });

    const data = await response.json();

    return data;

  }



  async incrementEntry(datastore, objectKey, incrementBy, scope = null) {

    const url = `${

      this._incrementUrl

    }?datastoreName=${datastore}&entryKey=${objectKey}&incrementBy=${incrementBy}&scope=${

      scope || ''

    }`;

    const response = await fetch(url, {

      method: 'POST',

      headers: await this._getHeaders(),

    });

    const data = await response.json();

    return data;

  }

}



module.exports = DataStores;
updateInventory.js
const DataStores = require('./dataStoresMethods');

const dataStoresApi = new DataStores();



// Set up

const datastoreName = 'Inventory';



// List keys for a subset of users

dataStoresApi.listEntries(datastoreName).then((keys) => {

  console.log(keys);

});



// Read inventory for each user

for (let x = 0; x < 5; x++) {

  const updatedObjectKey = `User_${x + 1}`;

  dataStoresApi.getEntry(datastoreName, updatedObjectKey).then((value) => {

    console.log(

      `${updatedObjectKey} has ${value.gems} gems in their inventory`

    );

  });

}



// Update the currency of each user by 10

for (let x = 0; x < 5; x++) {

  const updatedObjectKey = `User_${x + 1}`;

  dataStoresApi

    .incrementEntry(datastoreName, updatedObjectKey, 10)

    .then((value) => {

      console.log(

        `${updatedObjectKey} now has ${value.robux} robux in their inventory`

      );

    });

}

เพื่อทดสอบตั้งแปลงตัวแปรสภาพแวดล้อม API_KEY และดำเนินไฟล์ JavaScript:

export API_KEY=... \

node updateInventory.js

ตารางอันดับ

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

สำหรับตัวอย่างนี้, กำลังติดตาม:

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

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

จากระดับสูง คุณสามารถสร้างแอป Python โดยเพิ่มสิทธิ์การเข้าถึง API แล้วเพิ่มสคริปต์

เพิ่มสิทธิ์การใช้คีย์ API สำหรับร้านข้อมูลที่สั่งซื้อ

แอปตัวอย่างต้องการสี่วิธีในการบรรลุฟังก์ชันของมัน: List , Create และ Update และ Increment , ดังนั้นคุณจึงต้องเพิ่มสิทธิ์ API ต่อไปนี้:

  • อ่าน สำหรับวิธี list
  • เขียน สำหรับ Create , Update และ Increment วิธี

เมื่อสร้างคีย์ API สําหรับตัวอย่างนี้ ให้แน่ใจว่าคุณดําเนินการดังต่อไปนี้:

  1. จากเมนู เลือกระบบ API ในส่วน สิทธิ์การเข้าถึง เลือก ร้านข้อมูลที่จัดเรียง

  2. เพิ่มสิทธิ์การดำเนินการของ API เพื่ออ่านและเขียนคลังข้อมูลที่สั่งซื้อในประสบการณ์เป้าหมาย

    1. คลิกที่ เลือกประสบการณ์เพื่อเพิ่ม กล่องเลื่อนและเลือกประสบการณ์เป้าหมาย
    2. ใน การดำเนินการประสบการณ์ ขยายการเลื่อนลงเพื่อเลือก อ่าน และ เขียน การดำเนินการ

  3. ในส่วน ความปลอดภัย กำหนดการเข้าถึง IP โดยเฉพาะเพื่อกุญแจโดยใช้ การบันทึก CIDR และตั้งวันหมดอายุโดยเฉพาะเพื่อให้กุญแจหยุดทำงานหลังวันที่นั้นโดยอัตโนมัติสำหรับตัวอย่างนี้ หากคุณวางแผนที่จะทดสอบท้องถิ่นก่อน คุณสามารถลบการจำกัด IP โดยการตั้งค่าเป็น 0.0.0.0/0 และปล่อยให้หมดอายุใน 30 วัน

ตารางอันดับ

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

ไฟล์ แสดงวิธีการกำหนด , , และ วิธีการไฟล์ leaderboard.js ใช้วิธีที่กำหนดไว้ในการสร้างรายการของผู้ใช้ในคลังข้อมูลที่เรียงลําดับได้ แสดงคะแนน เพิ่มคะแนนของผู้ชนะ และอัปเดตลีดเดอร์บอร์ดไฟล์ leaderboard.js ยังนำเข้าไฟล์ config.json สำหรับการกำหนดค่ารหัสจักรวาล โดเมน API และคีย์ API ของคุณ

ordered_data_stores.js
const axios = require('axios');

const fs = require('fs');



class DataStores {

  constructor(configFile) {

    this._config = JSON.parse(fs.readFileSync(configFile, 'utf-8'));

  }



  _H() {

    return {

      'x-api-key': this._config.api_key,

      'Content-Type': 'application/json',

    };

  }



  async list(

    datastore,

    scope,

    pageSize = 10,

    orderBy = '',

    filter = '',

    exclusiveStartKey = ''

  ) {

    const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries`;

    const response = await axios.get(url, {

      headers: this._H(),

      params: {

        max_page_size: pageSize,

        order_by: orderBy,

        filter: filter,

        page_token: exclusiveStartKey,

      },

    });

    return response.data;

  }



  async create(datastore, scope, entry, data) {

    const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries`;

    const payload = JSON.stringify({ value: 11 });

    const response = await axios.post(url, payload, {

      headers: this._H(),

      params: { id: entry },

    });

    return response.data;

  }



  async increment(datastore, scope, entry, incrementBy) {

    const url = `${this._config.api_key_url}universes/${this._config.universe_id}/orderedDataStores/${datastore}/scopes/${scope}/entries/${entry}:increment`;

    const payload = JSON.stringify({ amount: incrementBy });

    const response = await axios.post(url, payload, { headers: this._H() });

    return response.data;

  }

}
leaderboard.js
const leaderboardEndpoints = require('./ordered_data_stores');



const datastores = new leaderboardEndpoints.DataStores('config.json');



// Variables

const orderedDataStore = 'PlayerScores';

const scope = 'global';

const entryNames = ['Ragdoll', 'Balinese', 'Tabby', 'Siamese'];



// Create an entry and give each new player 50 points for joining the game

entryNames.forEach(async (name) => {

  await datastores.create(orderedDataStore, scope, name, 50);

});



// Display the players' scores

datastores.list(orderedDataStore, scope).then((playerScores) => {

  console.log(playerScores);

});



// Increment the first player's score for winning the game

datastores.increment(orderedDataStore, scope, entryNames[0], 100);



// Increment all the players' scores for participating in the game

entryNames.forEach(async (name) => {

  await datastores.increment(orderedDataStore, scope, name, 10);

});



// Display the updated leaderboard

datastores.list(orderedDataStore, scope).then((updatedPlayerScores) => {

  console.log(updatedPlayerScores);

});
กำหนดค่า
{

  "universe_id": "",

  "api_key_url": "https://apis.roblox.com/datastores/ordered-v1/"

  "api_key": ""

}

เพื่อทดสอบตั้งแปรสภาพแวดล้อม API_KEY และดำเนินไฟล์ leaderboard.js :

export API_KEY=... \

node leaderboard.js

หลังจากทำการทดสอบเสร็จแล้ว คุณสามารถเผยแพร่หรือฝังลีดเดอร์บอร์ดไปยังเว็บไซต์นอก Roblox เพื่อเพิ่มการเข้าถึง