Hướng dẫn sử dụng cho kho dữ liệu

*Nội dung này được dịch bằng AI (Beta) và có thể có lỗi. Để xem trang này bằng tiếng Anh, hãy nhấp vào đây.

Ngoài việc truy cập kho dữ liệu bằng API Động cơ ( DataStoreService ) trong Studio hoặc máy chủ trực tiếp, bạn có thể sử dụng các API Mở đám mây để truy cập và sử dụng dữ liệu tiêu chuẩn và dữ liệu được đặt hàng từ các kịch bản và công cụ bên ngoài với quyền truy cập và kiểm soát bảo mật chi tiết.

Sử dụng

Bạn có thể cải thiện một số khu vực trong quy trình làm việc của bạn bằng cách truy cập dữ liệu của bạn với các API này, chẳng hạn như:

  • Cổng Hỗ trợ Khách hàng : Các kho dữ liệu hữu ích để lưu trữ các tài nguyên người dùng vĩnh viễn, chẳng hạn như vật phẩm trong kho hàng của người dùng hoặc điểm kỹ năng.Đôi khi bạn cần cập nhật các tài nguyên này cho hỗ chăm sóc khách hànghàng.Thay vì sử dụng Studio hoặc tham gia vào một trải nghiệm thủ công, bạn có thể xây dựng một ứng dụng web để cho phép các đại lý dịch vụ khách hàng của bạn xử lý trực tiếp các yêu cầu hỗ trợ khách hàng, chẳng hạn như xem và chỉnh sửa kho hàng người dùng và phát hành hoàn trả.

  • Bảng điều khiển LiveOps : Bạn có thể xây dựng bảng điều khiển LiveOps bằng cách sử dụng API để cải thiện hiệu quả của các hoạt động trực tiếp.Ví dụ, bạn có thể lên lịch một sự kiện trước, giấu nó dưới một cờ nhãn tính năng như một phần dữ liệu cấu hình trong một kho dữ cửa hàng, và đặt một thời gian để chuyển đổi cờ cho việc xuất bản sự kiện.Các máy chủ trải nghiệm của bạn có thể phát hiện thay đổi này bằng cách đọc lá cờ để khởi động sự kiện.

  • Bảng xếp hạng bên ngoài : Để quảng bá trải nghiệm của bạn bên ngoài Roblox, bạn có thể kéo thông tin về trải nghiệm của mình, chẳng hạn như bảng xếp hạng của một cuộc đua, trong thời gian thực và hiển thị nó trên một trang web bên ngoài.Bạn có thể cấp quyền truy cập chỉ đọc cho các kho dữ liệu được yêu cầu của bạn cho trang web để yêu cầu dữ liệu mới nhất thường xuyên thông qua HTTP và cập nhật trang web.

  • Tự động hóa di chuyển dữ liệu : Dữ liệu có thể thay đổi hoặc cập nhật khi trải nghiệm của bạn phát triển, chẳng hạn như nâng cấp các sơ đồ dữ liệu để hỗ trợ các tính năng mới.Để tránh mất dữ liệu người dùng hiện tại, đôi khi bạn cần phải di chuyển các kho dữ liệu của mình từ cơ sở dữ liệu cũ sang một cơ sở dữ liệu mới.Bạn có thể viết một kịch bản bên ngoài đọc mỗi bản ghi từ các kho dữ liệu hiện tại, định dạng dữ liệu sang cấu trúc mới và viết bản ghi trở lại kho dữ liệu mới để tự động hóa việc di chuyển dữ liệu.

Sự khác biệt với API Động cơ

Mặc dù API Mở đám mây tương tự với DataStoreService, có một vài sự khác biệt chính:

  • ID và tên kho dữ liệu của vũ trụ : Không giống như API Động cơ, Open Cloud APIs là vô chủ và có thể đến từ bất cứ nơi nào, vì vậy bạn phải luôn cung cấp ID vũ trụ , nhận dạng duy nhất của trải nghiệm của bạn, và tên kho dữ liệu name khi gửi các yêu cầu.Để biết thêm thông tin về cách nhận được ID vũ trụ, xem ID vũ trụ .

  • Quyền riêng biệt để tạo và cập nhật : API Động cơ tạo các bản ghi mới nếu chúng không tồn tại khi bạn gọi DataStore:SetAsync() , nhưng các phương pháp Mở đám mây cho tạo và cập nhật các bản ghi là riêng biệt.Các quyền riêng biệt có thể an toàn và linh hoạt hơn trong một số tình huống nhất định.Ví dụ, bạn có thể tạo công cụ hỗ trợ khách hàng có thể chỉnh sửa hồ sơ của người dùng hiện có, nhưng không thể tạo hồ sơ của người dùng mới.

  • serialization dữ liệu : Tất cả các điểm cuối mở đám mây yêu cầu bạn phải serialize tất cả dữ liệu trước khi vận chuyển mạng. Serialization có nghĩa là chuyển đổi một đối tượng thành một chuỗi.Giải mã là ngược lại (chuyển một chuỗi thành một đối tượng).API Động cơ serialize và deserialize nội dung nhập tự động, nhưng đối với Open Cloud, bạn cần tạo hoặc phân tích dữ liệu nhập của mình với JSON sở hữu.

Quyền bảo mật

Các kho dữ liệu thường lưu trữ thông tin nhạy cảm, chẳng hạn như hồ sơ người dùng và tiền tệảo.Để duy trì an ninh, mỗi Open Cloud API có quyền cần thiết tương ứng mà bạn phải thêm vào chìa khóa API của mình, chẳng hạn như quyền List Keys cho API danh sách.Nếu bạn không thêm các quyền cần thiết, cuộc gọi API của bạn trả về một lỗi.Đối với các quyền cụ thể cần thiết cho mỗi hoạt động, xem tham chiếu API của tiêu chuẩn và cửa hàng dữ liệu được xếp hạng .

Khi cấu hình chìa khóa API của bạn, bạn có thể đặt các quyền cấp thấp, chẳng hạn như đã xem, viết và liệt kê danh sách, cho mỗi kho dữ liệu trong một trải nghiệm cụ thể, hoặc bạn có thể cung cấp một chìa khóa để đọc hoặc viết tất cả các kho dữ liệu trong một trải nghiệm.Bạn cũng có thể giới hạn quyền truy cập đến một phần của các kho dữ liệu cần thiết cho công cụ của bạn thay vì tiết lộ tất cả các kho dữ liệu.Điều này giảm thiểu tác động trong trường hợp chìa khóa bị rò rỉ.

Công cụ xây dựng

Bạn có thể sử dụng ngôn ngữ lựa chọn của bạn để xây dựng công cụ với Mở API đám mây cho kho dữ liệu để đáp ứng nhu cầu hoạt động của bạn.Các ví dụ sau đây sẽ đi qua quá trình xây dựng một cổng hỗ trợ kho lưu trữ người dùng ở Python bằng các kho dữ liệu tiêu chuẩn và một bảng xếp hạng vĩnh viễn bên ngoài sử dụng các kho dữ liệu được xếp hạng theo thứ tự.

Cổng hỗ trợ kho hàng người dùng

Phần này cung cấp một ví dụ cụ thể về việc xây dựng một cổng hỗ trợ kho hàng người dùng trong Python, trong đó bạn có thể liệt kê và đọc một phần của kho hàng người dùng của bạn, thực hiện các chỉnh sửa và sau đó cập nhật lại vào kho dữ cửa hàngkinh nghiệm.

Với ví dụ này, hãy cho theo dõi:

  • Tên của kho lưu trữ dữ liệu lưu trữ kho hàng người dùng là Inventory .

  • Bảng dữ liệu cho mỗi lượt truy cập dữ liệu là "userId": {"currency": number, "weapon": string, "level": number} . Chìa khóa chỉ là userId .

  • Tập lệnh Python liệt kê một phần tử của kho hàng người dùng dựa trên tiền tố, tăng tiền ảo của chúng lên 10 để khuyến mãicáo, và cập nhật dữ liệu.

Từ cấp cao, bạn có thể xây dựng ứng dụng Python của mình bằng cách thêm quyền API và sau đó thêm các tập lệnh.

Thêm quyền chìa khóa API cho kho dữ liệu

Khi tạo Chìa khóa API cho ví dụ này, hãy chắc chắn bạn thực hiện các cài đặt sau:

  1. Từ menu Chọn hệ thống API trong phần Quyền truy cập , chọn kho dữ liệu vũ trụ .

  2. (Tùy chọn) Trong phần Kho dữ liệu , chọn hoạt động API cho các kho dữ liệu cụ thể.

    1. Bật chuyển đổi Các hoạt động lưu trữ dữ liệu cụ thể .Mặc định, năm kho dữ liệu tự động tải, nhưng bạn có thể thêm kho dữ liệu bổ sung thông qua nút + Thêm kho dữ liệu vào danh sách .
    2. Chọn mũi tên thả xuống bên cạnh tên của kho dữ cửa hàng, sau đó chọn các hoạt động API bạn muốn kho dữ liệu có quyền truy cập.

  3. Chọn các hoạt động API cho toàn bộ trải nghiệm.

    1. Nhấp vào Chọn Trải nghiệm để Thêm menu thả xuống và chọn một trải nghiệm.
    2. Trong Hoạt động kinh nghiệm , nhấp vào mũi tên thả xuống và chọn các hoạt động bạn muốn thêm vào API của mình.Ví dụ này chọn Đọc thông tin , Cập nhật thông tin và Chìa khóa danh sách thông tin cho toàn bộ trải nghiệm.

  4. Trong phần Bảo mật , đặt rõ ràng truy cập IP vào chìa khóa bằng biểu tượng CIDR, và đặt ngày hết hạn rõ ràng để chìa khóa của bạn tự động ngừng hoạt động sau ngày đó.Với ví dụ này, nếu bạn dự định thực hiện kiểm tra địa phương trước tiên, bạn có thể loại bỏ hạn chế IP bằng cách đặt nó thành 0.0.0.0/0 và để nó hết hạn trong 30 ngày .

Thêm kịch bản cho cổng hỗ trợ kho lưu trữ người dùng

Sau khi tạo chìa khóa API với các quyền cần thiết cho ứng dụng ví dụ, bạn cần thêm mã JavaScript để thực hiện chức năng của ứng dụng.Tập tin data_stores_methods.js hiển thị cách định nghĩa List Entries , Get Entry và Increment Entry phương pháp.Tập tin update_inventory.js sử dụng các phương pháp được xác định để liệt kê một phần tài sản của người dùng, tăng tiền ảo cho mỗi người dùng và cập nhật dữ liệu.

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`

      );

    });

}

Để kiểm tra, hãy đặt biến môi trường API_KEY và chạy tập lệnh JavaScript:

export API_KEY=... \

node updateInventory.js

Bảng bảng xếp hạngvĩnh viễn bên ngoài

Phần này đi qua một ví dụ cụ thể về việc tạo một bảng xếp hạng vĩnh viễn bên ngoài trong Python, trong đó bạn có thể liệt kê và đọc thông tin người dùng được lưu trong các kho dữ liệu được sắp xếp, thực hiện các chỉnh sửa và sau đó xuất lên một trang web bên ngoài để khuyến mãibá.

Với ví dụ này, hãy cho theo dõi:

  • Mẫu mã code tạo ra một danh sách được định trước các tên người dùng cho mục đích trình diễn.Đối với ứng dụng của riêng bạn, bạn nên sử dụng danh sách người dùng thực sự trong trải nghiệm của bạn.

  • Ví dụ mã thêm 50 điểm cho mỗi người dùng tham gia trải nghiệm cho mục đích thử nghiệm.Đối với ứng dụng của riêng bạn, bạn nên xác định quy tắc dựa trên thiết kế kinh nghiệm của bạn.

Từ cấp cao, bạn có thể xây dựng ứng dụng Python của mình bằng cách thêm quyền API và sau đó thêm các tập lệnh.

Thêm quyền chìa khóa API cho các kho dữ liệu được đặt hàng

Ứng dụng ví dụ yêu cầu bốn phương pháp để đạt được chức năng của nó: List , Create , Update và Increment , vì vậy bạn cần thêm các quyền API sau:

  • Đọc cho phương pháp list.
  • Viết cho Create , Update , và Increment phương pháp.

Khi tạo một Chìa khóa API cho ví dụ này, hãy chắc chắn thực hiện các hoạt động sau:

  1. Từ menu Chọn hệ thống API trong phần Quyền truy cập , chọn Kho dữ liệu được xếp hạng .

  2. Thêm quyền của hoạt động API để đọc và viết các kho dữ liệu được xếp hạng trong trải nghiệm mục tiêu.

    1. Nhấp vào Chọn Trải nghiệm để Thêm menu thả xuống và chọn trải nghiệm mục tiêu.
    2. Trong Hoạt động kinh nghiệm , mở rộng danh sổ thả xuống để chọn Đọc và Viết hoạt động.

  3. Trong phần Bảo mật , đặt rõ ràng truy cập IP vào chìa khóa bằng biểu tượng CIDR, và đặt ngày hết hạn rõ ràng để chìa khóa của bạn tự động ngừng hoạt động sau ngày đó.Với ví dụ này, nếu bạn dự định thực hiện kiểm tra địa phương trước tiên, bạn có thể loại bỏ hạn chế IP bằng cách đặt nó thành 0.0.0.0/0 và để nó hết hạn trong 30 ngày .

Thêm kịch bản cho bảng xếp hạng

Sau khi tạo chìa khóa API với các quyền cần thiết cho ứng dụng ví dụ, bạn cần thêm mã JavaScript để thực hiện chức năng của ứng dụng.

Tập tin ordered_data_stores.js hiển thị cách định nghĩa List , Create , Update và Increment phương pháp.Tập tin leaderboard.js sử dụng các phương pháp được định nghĩa để tạo các bản ghi của người dùng trong các cửa hàng dữ liệu được sắp xếp, hiển thị điểm số, tăng điểm số của người chiến thắng và cập nhật bảng xếp hạng.Tập tin leaderboard.js cũng nhập một tập tin config.json để cấu hình ID Vũ trụ, API và chìa khóa API của bạn.

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);

});
cấu hình
{

  "universe_id": "",

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

  "api_key": ""

}

Để kiểm tra, hãy đặt biến môi trường API_KEY và chạy tập tin leaderboard.js:

export API_KEY=... \

node leaderboard.js

Sau khi hoàn thành kiểm tra, bạn có thể xuất bảng xếp hạng hoặc nhúng vào các trang web bên ngoài Roblox để có thêm phạm vi tiếp cận.