游戏内 HTTP 请求

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按此处。

您可以使用 HttpService 向第三方 Web 服务发送通用 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 端点。您可以通过 HttpService 以与调用任何其他端点相同的方式调用这些端点。唯一的区别是您必须在请求中包含 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 当前的限制，Roblox 域的 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 游戏服务器，每分钟最多允许 2500 个 Open Cloud 请求。超出此限制可能导致请求发送方法暂停大约 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 规范要求所有头部名称以小写字母发送。

可观察性

可观察性仪表板提供 insights 和分析，用于监控和排除 HttpService 使用中的故障。仪表板具有两个主要图表：请求计数追踪您的游戏中 HttpService 请求的数量，以及响应时间测量端点的响应延迟。

可用于过滤和细分的维度定义如下：

请求类型

GET
POST
PUT
PATCH
DELETE
其他（用于未指定的请求类型）

状态

成功（HTTP 1xx 和 2xx 状态码）
重定向（HTTP 3xx 状态码）
400（错误请求）
401（未经授权）
403（禁止访问）
404（未找到）
429（请求过多）
500（内部服务器错误）
503（服务不可用）
ExternalError（来自外部服务的任何其他未指定错误代码）
InternalError（从 Roblox 的 HttpService 返回的问题）

响应时间图表与状态数据没有相关性。如果您选择“状态”作为细分或过滤项，则此图表将不会显示数据。

其他考虑事项

请求应该提供安全的身份验证形式，例如预共享密钥，以便恶意行为者无法伪装成您的 Roblox 服务器之一。
请注意发送请求的 Web 服务器的一般容量和速率限制策略。

中文(简体)