游戏内 HTTP 请求

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

您可以使用 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 端点的一个子集。您可以通过 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"), -- 在 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 访问。

资产

禁止和阻止

配置

创作者商店

开发者产品

游戏通行证

数据和内存存储

数据存储：

内存存储：

有序数据存储：

组

库存

ListInventoryItems

Luau 执行

通知

CreateUserNotification

场所

宇宙

用户

限制

仅允许 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() 也可能会失败，并显示 Number of Open Cloud requests exceeded limit 的消息。

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 服务器之一。
注意请求发送到的网络服务器的一般容量和速率限制政策。

中文(简体)