Yêu cầu HTTP trong trò chơi

Bạn có thể sử dụng HttpService để gửi các yêu cầu HTTP chung đến các dịch vụ web bên thứ ba cho các trường hợp sử dụng như phân tích, lưu trữ dữ liệu hoặc ghi lỗi. HttpService cũng hỗ trợ một số điểm cuối Open Cloud nhất định.

Bật yêu cầu HTTP

Các phương thức HttpService:GetAsync(), HttpService:PostAsync(), và HttpService:RequestAsync() không được bật theo mặc định. Để gửi yêu cầu, bạn phải Cho phép yêu cầu HTTP trong Tệp ⟩ Cài đặt trải nghiệm ⟩ Bảo mật trong Studio.

Sử dụng trong các plugin

Bạn có thể sử dụng HttpService trong các plugin Studio để kiểm tra cập nhật, tải nội dung hoặc các logic kinh doanh khác. Lần đầu tiên một plugin cố gắng sử dụng dịch vụ, người dùng có thể được nhắc cho phép plugin giao tiếp với địa chỉ web cụ thể. Người dùng có thể chấp nhận, từ chối và thu hồi những quyền này bất cứ lúc nào thông qua cửa sổ Quản lý Plugin.

Các plugin cũng có thể giao tiếp với phần mềm khác đang chạy trên cùng một máy tính thông qua các máy chủ localhost và 127.0.0.1. Bằng cách chạy các chương trình tương thích với các plugin như vậy, bạn có thể mở rộng chức năng của plugin của mình vượt ra ngoài khả năng bình thường của Studio, chẳng hạn như tương tác với hệ thống tệp của máy tính của bạn. Hãy cẩn thận rằng phần mềm như vậy phải được phân phối riêng biệt với chính plugin và có thể gây ra rủi ro bảo mật.

Sử dụng với Open Cloud

HttpService hiện có thể gọi một tập hợp con của các điểm cuối Open Cloud. Bạn có thể gọi các điểm cuối này theo cách mà bạn gọi bất kỳ điểm cuối nào khác thông qua HttpService. Sự khác biệt duy nhất là bạn phải bao gồm một khóa API Open Cloud trong yêu cầu:

1. Tạo một khóa API Open Cloud.
2. Lưu khóa API vào kho bí mật của bạn.
3. Thực hiện yêu cầu.

Mẫu mã sau đây minh họa cách cập nhật tư cách thành viên nhóm của người dùng từ trong một trò chơi:

local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- Khi gửi JSON, hãy đặt cái này!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Đặt trong Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Phản hồi thành công:", response.StatusCode, response.StatusMessage)
	else
		print("Phản hồi trả về lỗi:", response.StatusCode, response.StatusMessage)
	end
	print("Nội dung phản hồi:\n", response.Body)
	print("Tiêu đề phản hồi:\n", HttpService:JSONEncode(response.Headers))
end

-- Bọc hàm trong pcall() để an toàn
local success, errorMessage = pcall(request)
if not success then
	print("Yêu cầu HTTP không gửi được:", errorMessage)
end

Các điểm cuối Open Cloud được hỗ trợ

Các điểm cuối sau đây được hỗ trợ. Do các hạn chế hiện tại trên HttpService, chuỗi .. không được phép trong các tham số đường dẫn URL đến các miền Roblox. Điều này có nghĩa là, ví dụ, các kho dữ liệu và các mục chứa chuỗi này hiện không thể truy cập từ HttpService.

Tài sản

• GetAsset
• ListAssetVersions
• GetAssetVersion

Cấm và chặn

• ListUserRestrictions (Nơi)
• GetUserRestriction (Nơi)
• UpdateUserRestriction (Nơi)
• ListUserRestrictions (Vũ trụ)
• GetUserRestriction (Vũ trụ)
• UpdateUserRestriction (Vũ trụ)
• ListUserRestrictionLogs (Vũ trụ)

Cấu hình

• GetConfigRepositoryValues
• GetConfigRepositoryDraft
• UpdateDraft
• DeleteDraft
• OverwriteDraft
• GetConfigRepositoryFull
• PublishDraft
• ListRevisions
• RestoreRevision

Cửa hàng người sáng tạo

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Sản phẩm phát triển

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Thẻ game

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Kho dữ liệu và bộ nhớ

Kho dữ liệu:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Với Phạm vi)
• CreateDataStoreEntry (Với Phạm vi)
• GetDataStoreEntry (Với Phạm vi)
• DeleteDataStoreEntry (Với Phạm vi)
• UpdateDataStoreEntry (Với Phạm vi)
• IncrementDataStoreEntry (Với Phạm vi)
• ListDataStoreEntryRevisions (Với Phạm vi)

Kho nhớ:

• CreateMemoryStoreQueueItem
• DiscardMemoryStoreQueueItems
• ReadMemoryStoreQueueItems
• ListMemoryStoreSortedMapItems
• CreateMemoryStoreSortedMapItem
• GetMemoryStoreSortedMapItem
• DeleteMemoryStoreSortedMapItem
• UpdateMemoryStoreSortedMapItem
• FlushMemoryStore

Kho dữ liệu có thứ tự:

• ListOrderedDataStoreEntries
• CreateOrderedDataStoreEntry
• GetOrderedDataStoreEntry
• DeleteOrderedDataStoreEntry
• UpdateOrderedDataStoreEntry
• IncrementOrderedDataStoreEntry

Nhóm

• GetGroup
• ListGroupJoinRequests
• AcceptGroupJoinRequest
• DeclineGroupJoinRequest
• ListGroupMemberships
• UpdateGroupMembership
• ListGroupRoles
• GetGroupRole
• GetGroupShout

Kho hàng

• ListInventoryItems

Thực thi Luau

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (với phiên bản)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Thông báo

• CreateUserNotification

Địa điểm

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Vũ trụ

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Người dùng

• GetUser
• GenerateUserThumbnail

Hạn chế

• Chỉ có các tiêu đề x-api-key và content-type được phép.
• Tiêu đề x-api-key phải là một Secret. Xem Kho bí mật.
• Chuỗi ".." không được phép trong các tham số đường dẫn URL.
• Chỉ giao thức HTTPS được hỗ trợ.
• Bạn không thể sử dụng cổng 1194 hoặc bất kỳ cổng nào dưới 1024, ngoại trừ 80 và 443. Nếu bạn cố gắng sử dụng một cổng bị chặn, bạn sẽ nhận được lỗi 403 Forbidden hoặc ERR_ACCESS_DENIED.

Giới hạn tần suất

Đối với mỗi máy chủ trò chơi Roblox, có giới hạn 2500 yêu cầu Open Cloud mỗi phút. Vượt quá giới hạn này có thể khiến các phương thức gửi yêu cầu bị tạm dừng khoảng 30 giây. pcall() của bạn cũng có thể thất bại với thông báo Số lượng yêu cầu Open Cloud vượt quá giới hạn.

• Các yêu cầu Open Cloud không tiêu thụ cùng một giới hạn tổng thể 500 yêu cầu HTTP mỗi phút được áp dụng cho tất cả các yêu cầu khác.
• Mỗi điểm cuối có giới hạn riêng cho mỗi chủ sở hữu khóa API (có thể là người dùng hoặc nhóm) được áp dụng bất kể các cuộc gọi đến từ đâu (HttpService, web, v.v.).

Để biết thông tin chi tiết về giới hạn tần suất Open Cloud, giới hạn tần suất dựa trên xác thực và các phương pháp tốt nhất, hãy xem Giới hạn tần suất.

Các phương pháp tốt nhất

Để tối ưu hóa việc sử dụng HttpService của bạn và tránh vượt quá giới hạn, hãy áp dụng các phương pháp tốt nhất sau:

• Xử lý lỗi một cách nhẹ nhàng. Các yêu cầu web có thể thất bại vì nhiều lý do. Sử dụng pcall() và có một kế hoạch cho khi các yêu cầu thất bại. Hơn nữa, hãy xác thực và làm sạch tất cả dữ liệu nhận được từ các API bên ngoài, đảm bảo dữ liệu chính xác khi bạn có thể.

• Sử dụng exponential backoff để giữ dưới giới hạn.

  Nếu một yêu cầu trả về lỗi có thể khôi phục, thay vì ngay lập tức thử lại, hãy chờ hai giây, sau đó là bốn, tám, v.v. giữa các lần thử. Điều này giúp hạn chế tắc nghẽn và cải thiện khả năng thành công của yêu cầu bằng cách cho điểm cuối thời gian để "hạ nhiệt".

• Tập hợp và gửi dữ liệu theo lô.

  Khi có thể, nên để máy chủ của bạn thu thập tất cả dữ liệu cần thiết để gửi một yêu cầu HTTP, thay vì nhiều yêu cầu nhỏ. Ví dụ, nếu bạn đang gửi một yêu cầu HTTP cho mỗi người chơi trong máy chủ của bạn, hãy kiểm tra xem API có điểm cuối theo lô/batch hay không và, nếu có, hãy thu thập thông tin từ tất cả người chơi và gửi tất cả trong một yêu cầu.

  Trong một số trường hợp, bạn có thể phải sử dụng HttpService:RequestAsync() để bao gồm dữ liệu trong thân của yêu cầu.

• Sử dụng các điểm cuối HTTP/2. HTTP/2 cung cấp lợi ích hiệu suất đáng kể thông qua các tính năng như nén tiêu đề và đa hợp yêu cầu/phản hồi qua một kết nối duy nhất. HttpService tự động sử dụng HTTP/2 khi có sẵn. Lưu ý rằng thông số kỹ thuật HTTP/2 yêu cầu tất cả tên tiêu đề phải được gửi bằng chữ thường.

Khả năng quan sát

Bảng điều khiển Khả năng quan sát cung cấp thông tin và phân tích để theo dõi và khắc phục sự cố việc sử dụng HttpService của bạn. Bảng điều khiển có hai biểu đồ chính: Số lượng yêu cầu theo dõi khối lượng yêu cầu HttpService từ trò chơi của bạn, và Thời gian phản hồi đo lường độ trễ cho các điểm cuối phản hồi.

Các chiều có sẵn để lọc và phân tích được định nghĩa như sau:

Loại yêu cầu

• GET
• POST
• PUT
• PATCH
• DELETE
• Khác (đối với các loại yêu cầu không được chỉ định)

Trạng thái

• Thành công (mã trạng thái HTTP 1xx và 2xx)
• Chuyển hướng (mã trạng thái HTTP 3xx)
• 400 (Yêu cầu không hợp lệ)
• 401 (Không được phép)
• 403 (Bị cấm)
• 404 (Không tìm thấy)
• 429 (Quá nhiều yêu cầu)
• 500 (Lỗi máy chủ nội bộ)
• 503 (Dịch vụ không khả dụng)
• ExternalError (bất kỳ mã lỗi không được chỉ định nào khác trả về từ dịch vụ bên ngoài)
• InternalError (một vấn đề trả về từ HttpService trong Roblox)

Biểu đồ Thời gian phản hồi không tương quan với dữ liệu trạng thái. Nếu bạn chọn "Trạng thái" làm phân tích hoặc bộ lọc, biểu đồ này sẽ không hiển thị dữ liệu.

Các cân nhắc bổ sung

• Các yêu cầu nên cung cấp một hình thức xác thực an toàn, chẳng hạn như một khóa bí mật đã được chia sẻ trước, để các tác nhân xấu không thể giả mạo một trong các máy chủ Roblox của bạn.
• Hãy chú ý đến khả năng tổng thể và chính sách giới hạn tần suất của các máy chủ web mà các yêu cầu đang được gửi đến.