Cấu hình trải nghiệm | Tài liệu - Trung Tâm Nhà Sáng Tạo Roblox

API cấu hình cho phép bạn quản lý cấu hình trải nghiệm một cách tự động thay vì sử dụng Creator Hub hoặc Studio. Hướng dẫn này bao gồm một quy trình điển hình:

Tạo hoặc cập nhật một cấu hình nháp.
Xuất bản nó.
Lấy giá trị cấu hình mới nhất.
Quay lại giá trị trước đó bằng cách sử dụng lịch sử phiên bản.

Các giá trị bạn xuất bản sẽ có sẵn trong trải nghiệm của bạn ngay lập tức. Trong các script server, sử dụng ConfigService để đọc các cấu hình và phản ứng với các cập nhật theo thời gian thực. ConfigService:GetConfigAsync() và ConfigSnapshot:GetValue() cho phép bạn đọc các giá trị, và ConfigSnapshot.UpdateAvailable với ConfigSnapshot:Refresh() hoặc ConfigSnapshot:GetValueChangedSignal() cho phép bạn phản ứng khi các giá trị thay đổi. Để xem các mẫu mã Luau và các chi tiết thêm, hãy xem Thêm cấu hình vào mã của bạn và Làm mới các bản sao trong hướng dẫn cấu hình trải nghiệm.

Trước khi bạn bắt đầu, tạo một khóa API hoặc cấu hình một ứng dụng OAuth 2.0. Các yêu cầu đọc yêu cầu phạm vi universe:read. Các yêu cầu ghi (nháp, xuất bản, phục hồi) cần universe:write.

Tất cả các điểm cuối sử dụng ID vũ trụ của bạn, mà bạn có thể tìm thấy trên Bảng điều khiển Creator. Nhấp vào menu thả xuống của ô trải nghiệm và Sao chép ID Vũ Trụ.

Để biết tham chiếu đầy đủ về điểm cuối, các lược đồ yêu cầu và phản hồi, và mã lỗi, hãy xem Tham chiếu API Cloud.

Kho lưu trữ

Các yêu cầu đến các điểm cuối cấu hình sử dụng một kho lưu trữ trong đường dẫn và một đối tượng entries trong thân yêu cầu. Ví dụ, yêu cầu này thêm một cấu hình nháp:


PATCH /creator-configs-public-api/v1/configs/universes/<UNIVERSE_ID>/repositories/<REPOSITORY>/draft
{
  "entries": {
    "enableNewTutorial": true
  }
}

Kho lưu trữ khác nhau theo sản phẩm và phân tách các cấu hình theo hệ thống.
Entries là các cặp khóa-giá trị cấu hình. Bạn gửi và nhận một đối tượng phẳng đơn lẻ của các khóa và giá trị.

Hướng dẫn này bao gồm các cấu hình trong trải nghiệm, vì vậy tất cả các yêu cầu sử dụng InExperienceConfig cho kho lưu trữ. Các kho lưu trữ sẽ mở rộng để bao phủ thêm các sản phẩm và trường hợp sử dụng.

Trường hợp sử dụng	Kho lưu trữ
Cấu hình trong trải nghiệm	InExperienceConfig

Tạo hoặc cập nhật cấu hình

Trước khi chính thức hoạt động, các thay đổi cấu hình được đặt ở dạng nháp. Bạn có thể đặt toàn bộ cấu hình trong một thao tác hoặc áp dụng các cập nhật một phần cho đến khi bạn hài lòng với nó:

Bắt đầu từ đầu hoặc thay thế mọi thứ — Sử dụng điểm cuối ghi đè để tải lên trạng thái đầy đủ mong muốn. Mọi khóa bạn bỏ qua sẽ được coi là bị xóa.
Thay đổi chỉ một số khóa — Sử dụng điểm cuối cập nhật một phần để chỉ cập nhật các khóa bạn gửi; mọi thứ khác vẫn giữ nguyên.

Mẫu mã này thiết lập bossHealth thành 100 và sử dụng điểm cuối ghi đè:


import requests

API_KEY = "<API_KEY>"
UNIVERSE_ID = "<UNIVERSE_ID>"
BASE = f"https://apis.roblox.com/creator-configs-public-api/v1/configs/universes/{UNIVERSE_ID}/repositories/InExperienceConfig"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# Tùy chọn: gửi previousDraftHash nếu bạn có một nháp hiện có và muốn đảm bảo tính tương thích tối ưu
payload = {
    "entries": {
        "bossHealth": 100
    }
}
r = requests.put(f"{BASE}/draft:overwrite", headers=headers, json=payload)
r.raise_for_status()
draft = r.json()
draft_hash = draft["draftHash"]  # Giữ cái này cho việc xuất bản
print("Nháp đã được đặt. draftHash:", draft_hash)

Phản hồi bao gồm giá trị draftHash. Bạn cần cái này để xuất bản. Nếu bạn chỉ muốn điều chỉnh một vài khóa trong nháp của mình, hãy sử dụng phương thức PATCH trên điểm cuối /draft và chỉ gửi các entries (khóa) bạn muốn thay đổi.

Về các hash nháp

draft hash là một định danh không công khai cho trạng thái hiện tại của nháp của bạn. API trả lại sau mỗi thao tác đọc hoặc ghi vào một nháp (tạo, cập nhật, ghi đè, đặt lại, phục hồi).

Khi cập nhật hoặc xuất bản các nháp, bạn có thể gửi previousDraftHash trong thân yêu cầu. Nếu hash không khớp với nháp hiện tại của máy chủ (ví dụ: ai đó đã xuất bản hoặc chỉnh sửa trong thời gian đó), yêu cầu sẽ thất bại. Bạn có thể đọc lại nháp đã cập nhật, lấy hash mới và thử lại hoặc hợp nhất các thay đổi.

Luôn lưu lại draftHash từ phản hồi nháp cuối cùng trước khi gọi xuất bản hoặc trước khi thực hiện thay đổi nháp khác nếu bạn sử dụng previousDraftHash.

Xuất bản các thay đổi của bạn

Khi bạn hài lòng với nháp, hãy xuất bản nó để các giá trị mới được hoạt động. Truyền draftHash từ phản hồi nháp, message cho mục đích lịch sử phiên bản, và deploymentStrategy (hoặc GradualRollout cho một đợt triển khai kéo dài 15 phút hoặc Immediate). Mẫu mã sau đây triển khai cấu hình ngay lập tức:


publish_payload = {
    "draftHash": draft_hash,
    "message": "Đặt sức khỏe boss thành 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Đã xuất bản. configVersion:", result["configVersion"])

Sau khi xuất bản thành công, nháp sẽ được xóa, và trải nghiệm của bạn sẽ nhận được cấu hình mới theo chiến lược triển khai. Phản hồi bao gồm phiên bản cấu hình mới:


{
  "configVersion": 6
}

Lấy cấu hình đã xuất bản của bạn

Để xác nhận rằng thay đổi đã được thực hiện, hãy lấy cấu hình đã xuất bản mới nhất. Sử dụng điểm cuối chỉ giá trị khi bạn chỉ cần các khóa và giá trị; sử dụng điểm cuối đầy đủ khi bạn cũng cần siêu dữ liệu (mô tả, thời gian truy cập gần nhất, v.v.). Mẫu mã này sử dụng điểm cuối chỉ giá trị, với điểm cuối đầy đủ bị chú thích:


# Chỉ giá trị (cùng hình dạng mà RCC và trò chơi của bạn thấy)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Sức khỏe boss đã xuất bản:", boss_health)  # Sẽ là 100

# Hoặc với siêu dữ liệu đầy đủ:
# r = requests.get(f"{BASE}/full", headers=headers)

Xác minh rằng entries.bossHealth (hoặc khóa của bạn) khớp với những gì bạn đã xuất bản.

Xem lịch sử và quay lại

Mỗi lần xuất bản tạo ra một phiên bản sửa đổi, giống như một hệ thống kiểm soát phiên bản. Bạn có thể liệt kê các phiên bản sửa đổi để xem ai đã thay đổi cái gì và khi nào, sau đó phục hồi về một phiên bản sửa đổi trước đó nếu bạn cần quay lại.

Mẫu mã này gọi đến điểm cuối phiên bản sửa đổi và in kết quả. Mỗi phiên bản sửa đổi bao gồm revisionId, version, time, publishedBy, message, và changes (khóa, giá trị "trước", và giá trị "sau").


r = requests.get(f"{BASE}/revisions", headers=headers, params={"MaxPageSize": 10})
r.raise_for_status()
data = r.json()
for rev in data["revisions"]:
    print(rev["version"], rev["time"], rev["message"], "— revisionId:", rev["revisionId"])

Để quay lại, hãy gọi đến điểm cuối phục hồi với revisionId mà bạn muốn phục hồi về. Việc này làm xóa nháp hiện tại và thiết lập một cam kết quay lại; nó không xuất bản. Để xuất bản, bạn phải gọi publish với draftHash được trả về, giống như xuất bản một thay đổi mới.


REVISION_ID = "1234567890"  # Từ danh sách ở trên
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Xuất bản việc phục hồi
publish_payload = {
    "draftHash": restore_hash,
    "message": "Quay lại cấu hình trước đó",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Đã xuất bản quay lại. configVersion:", r.json()["configVersion"])

Giới hạn

Giới hạn	Tối đa
Khóa trên mỗi kho lưu trữ	100
Độ dài khóa	256 ký tự

Các yêu cầu vượt quá các giới hạn này sẽ thất bại. Để biết giới hạn giá trị cụ thể theo loại (ví dụ: chuỗi so với JSON) trong trải nghiệm của bạn, hãy xem Giới hạn trong hướng dẫn cấu hình trải nghiệm.

Để biết đầy đủ chi tiết về tất cả các điểm cuối trong hướng dẫn này, hãy xem Tham chiếu API Cloud.