遊戲內 HTTP 請求

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

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

啟用 HTTP 請求

HttpService:GetAsync(), HttpService:PostAsync(), 和 HttpService:RequestAsync() 方法預設並未啟用。要發送請求，您必須在體驗設定中為您的遊戲允許 HTTP 請求。

在插件中使用

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

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

與 Open Cloud 一起使用

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

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


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"), -- 在創作者中心設置
		},
		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 訪問。

資產

禁止和封鎖

配置

創作者商店

開發者產品

遊戲通行證

數據和內存存儲

數據存儲：

內存存儲：

有序數據存儲：

群組

庫存

ListInventoryItems

Luau 執行

通知

CreateUserNotification

場地

宇宙

用戶

限制

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

請求限制

對於每個 Roblox 遊戲伺服器，Open Cloud 請求的限制為每分鐘 2500 次。超過此限制會導致請求發送方法停滯約 30 秒。您的 pcall() 也可能會因訊息為 Number of Open Cloud requests exceeded limit 而失敗。

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

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

最佳實踐

為了優化您的 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 伺服器。
了解對於請求所發送的網路伺服器的一般容量和速率限制政策。

中文(繁體)