遊戲內 HTTP 請求

您可以使用 HttpService 向第三方網路服務發送通用 HTTP 請求，用於分析、數據存儲或錯誤日誌等用例。HttpService 也支持某些 Open Cloud 端點。

啟用 HTTP 請求

HttpService:GetAsync()、HttpService:PostAsync() 和 HttpService:RequestAsync() 方法預設是禁用的。要發送請求，您必須在 Studio 中的 檔案 ⟩ 體驗設定 ⟩ 安全性 下 允許 HTTP 請求。

在插件中使用

您可以在 Studio 插件中使用 HttpService 來檢查更新、下載內容或其他業務邏輯。當插件第一次嘗試使用該服務時，可能會提示用戶授予插件與特定網路地址通信的權限。用戶可以隨時通過 插件管理 窗口接受、拒絕或撤銷這些權限。

插件還可以通過 localhost 和 127.0.0.1 主機與同一計算機上運行的其他軟體進行通信。通過運行與這些插件兼容的程序，您可以擴展插件的功能，超越 Studio 的正常能力，例如與計算機的文件系統交互。請注意，這些軟體必須與插件本身分開分發，並可能帶來安全風險。

與 Open Cloud 一起使用

HttpService 目前可以調用 Open Cloud 端點的子集。您可以以與調用任何其他端點相同的方式調用這些端點。唯一的區別是您必須在請求中包含 Open Cloud API 密鑰：

1. 創建 Open Cloud API 密鑰。
2. 將 API 密鑰保存到您的秘密存儲。
3. 發送請求。

以下代碼示例演示如何在遊戲中更新用戶的群組成員資格：

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", -- 發送 JSON 時，請設置此項！
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- 在 Creator Hub 中設置
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("回應成功:", response.StatusCode, response.StatusMessage)
	else
		print("回應返回錯誤:", response.StatusCode, response.StatusMessage)
	end
	print("回應主體:\n", response.Body)
	print("回應標頭:\n", HttpService:JSONEncode(response.Headers))
end

-- 將函數包裝在 pcall() 中以確保安全
local success, errorMessage = pcall(request)
if not success then
	print("HTTP 請求發送失敗:", errorMessage)
end

支持的 Open Cloud 端點

以下端點是支持的。由於 HttpService 的當前限制，URL 路徑參數中不允許使用 .. 字串。這意味著，例如，包含此字串的數據存儲和條目目前無法從 HttpService 訪問。

資產

• GetAsset
• ListAssetVersions
• GetAssetVersion

禁止和封鎖

• ListUserRestrictions (Place)
• GetUserRestriction (Place)
• UpdateUserRestriction (Place)
• ListUserRestrictions (Universe)
• GetUserRestriction (Universe)
• UpdateUserRestriction (Universe)
• ListUserRestrictionLogs (Universe)

配置

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

創作者商店

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

開發者產品

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

遊戲通行證

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

數據和內存存儲

數據存儲：

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (With Scope)
• CreateDataStoreEntry (With Scope)
• GetDataStoreEntry (With Scope)
• DeleteDataStoreEntry (With Scope)
• UpdateDataStoreEntry (With Scope)
• IncrementDataStoreEntry (With Scope)
• ListDataStoreEntryRevisions (With Scope)

內存存儲：

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

有序數據存儲：

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

群組

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

庫存

• ListInventoryItems

Luau 執行

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (with version)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

通知

• CreateUserNotification

地方

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

宇宙

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

用戶

• GetUser
• GenerateUserThumbnail

限制

• 只允許 x-api-key 和 content-type 標頭。
• x-api-key 標頭必須是 Secret。請參見 Secrets stores。
• URL 路徑參數中不允許使用 ".." 字串。
• 只支持 HTTPS 協議。
• 您不能使用端口 1194 或任何低於 1024 的端口，除了 80 和 443。如果您嘗試使用被阻止的端口，您將收到 403 Forbidden 或 ERR_ACCESS_DENIED 錯誤。

速率限制

對於每個 Roblox 遊戲伺服器，每分鐘最多可以發送 2500 個 Open Cloud 請求。超過此限制可能會導致請求發送方法暫停約 30 秒。您的 pcall() 也可能會因為 Open Cloud 請求數量超過限制 而失敗。

• Open Cloud 請求 不 會消耗所有其他請求的每分鐘 500 個 HTTP 請求的總限制。
• 每個端點對於每個 API 密鑰擁有者（可以是用戶或群組）都有自己的限制，無論調用來自何處（HttpService、網路等）都會強制執行。

有關 Open Cloud 速率限制、基於身份驗證的速率限制和最佳實踐的詳細信息，請參見 Rate Limits。

最佳實踐

為了優化您的 HttpService 使用並避免超過限制，請遵循以下最佳實踐：

• 優雅地處理錯誤。網路請求可能因多種原因失敗。使用 pcall() 並制定請求失敗時的計劃。此外，嚴格驗證和清理來自外部 API 的所有接收數據，確保數據的正確性。

• 使用 指數退避 以保持在限制之下。

  如果請求返回可恢復的錯誤，則不要立即重試，而是等待兩秒，然後四秒、八秒等。這有助於限制擁塞，並通過給端點時間“冷卻”來提高成功請求的機會。

• 聚合並批量發送數據。

  在可能的情況下，建議讓您的伺服器收集所有必要數據，以便發送一個 HTTP 請求，而不是多個小請求。例如，如果您為伺服器中的每個玩家發送 HTTP 請求，請檢查 API 是否有批量/批次端點，如果有，則收集所有玩家的信息並一次性發送。

  在某些情況下，您可能需要使用 HttpService:RequestAsync() 將數據包含在請求的主體中。

• 使用 HTTP/2 端點。HTTP/2 通過標頭壓縮和單個連接上的請求/響應多路復用等功能提供顯著的性能優勢。HttpService 在可用時會自動使用 HTTP/2。請注意，HTTP/2 規範要求所有標頭名稱以小寫字母發送。

可觀察性

可觀察性儀表板 提供有關監控和故障排除您的 HttpService 使用情況的見解和分析。儀表板具有兩個主要圖表：請求計數 跟踪來自您遊戲的 HttpService 請求量，響應時間 測量端點的延遲。

可用的過濾和細分維度定義如下：

請求類型

• GET
• POST
• PUT
• PATCH
• DELETE
• 其他（對於未指定的請求類型）

狀態

• 成功（HTTP 1xx 和 2xx 狀態碼）
• 重定向（HTTP 3xx 狀態碼）
• 400（錯誤請求）
• 401（未授權）
• 403（禁止）
• 404（未找到）
• 429（請求過多）
• 500（內部伺服器錯誤）
• 503（服務不可用）
• ExternalError（來自外部服務的任何其他未指定錯誤代碼）
• InternalError（來自 Roblox 中的 HttpService 的問題）

響應時間 圖表與狀態數據無關。如果您選擇“狀態”作為細分或過濾，則此圖表將不顯示數據。

其他考慮事項

• 請求應提供安全的身份驗證形式，例如預共享的密鑰，以防止壞人冒充您的 Roblox 伺服器。
• 注意發送請求的網路伺服器的一般容量和速率限制政策。