Solicitudes HTTP en el juego

*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.

Puedes usar HttpService para enviar solicitudes HTTP genéricas a servicios web de terceros para casos de uso como análisis, almacenamiento de datos o registro de errores. HttpService también admite ciertos puntos finales de Open Cloud.

Habilitar solicitudes HTTP

Los métodos HttpService:GetAsync(), HttpService:PostAsync() y HttpService:RequestAsync() no están habilitados por defecto. Para enviar solicitudes, debes Permitir Solicitudes HTTP en Archivo ⟩ Configuraciones de Experiencia ⟩ Seguridad en Studio.

Uso en complementos

Puedes usar HttpService en complementos de Studio para verificar actualizaciones, descargar contenido u otra lógica de negocio. La primera vez que un complemento intenta usar el servicio, se puede solicitar al usuario que le dé permiso al complemento para comunicarse con la dirección web particular. Los usuarios pueden aceptar, denegar y revocar estos permisos en cualquier momento a través de la ventana de Gestión de Complementos.

Los complementos también pueden comunicarse con otro software que se ejecute en la misma computadora a través de los hosts localhost y 127.0.0.1. Al ejecutar programas compatibles con tales complementos, puedes extender la funcionalidad de tu complemento más allá de las capacidades normales de Studio, como interactuar con el sistema de archivos de tu computadora. Ten en cuenta que dicho software debe distribuirse por separado del complemento en sí y puede presentar riesgos de seguridad.

Uso con Open Cloud

HttpService puede actualmente llamar a un subconjunto de los puntos finales de Open Cloud. Puedes llamar a estos puntos finales de la misma manera que llamarías a cualquier otro punto final a través de HttpService. La única diferencia es que debes incluir una clave API de Open Cloud en la solicitud:

Crea una clave API de Open Cloud.
Guarda la clave API en tu almacén de secretos.
Realiza la solicitud.

El siguiente ejemplo de código demuestra cómo actualizar la membresía de un grupo de un usuario desde dentro de un juego:

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", -- ¡Cuando envíes JSON, establece esto!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Establecido en Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("La respuesta fue exitosa:", response.StatusCode, response.StatusMessage)
	else
		print("La respuesta devolvió un error:", response.StatusCode, response.StatusMessage)
	end
	print("Cuerpo de la respuesta:\n", response.Body)
	print("Encabezados de la respuesta:\n", HttpService:JSONEncode(response.Headers))
end

-- Envuelve la función en pcall() por seguridad
local success, errorMessage = pcall(request)
if not success then
	print("La solicitud HTTP falló al enviarse:", errorMessage)
end

Puntos finales de Open Cloud soportados

Los siguientes puntos finales son compatibles. Debido a las limitaciones actuales en HttpService, la cadena .. no está permitida en los parámetros de ruta de URL a los dominios de Roblox. Esto significa, por ejemplo, que los almacenes de datos y las entradas que contienen esta cadena son actualmente inaccesibles desde HttpService.

Activos

Prohibiciones y bloqueos

Configuraciones

Tienda de Creadores

Productos de desarrollador

Pases de juego

Almacenes de datos y memoria

Almacenes de datos:

Almacenes de memoria:

Almacenes de datos ordenados:

Grupos

Inventarios

ListInventoryItems

Ejecución de Luau

Notificaciones

CreateUserNotification

Lugares

Universos

Usuarios

Limitaciones

Solo se permiten los encabezados x-api-key y content-type.
El encabezado x-api-key debe ser un Secret. Consulta Almacenes de secretos.
La cadena ".." no está permitida en los parámetros de ruta de URL.
Solo se admite el protocolo HTTPS.
No puedes usar el puerto 1194 ni ningún puerto por debajo de 1024, excepto 80 y 443. Si intentas usar un puerto bloqueado, recibirás un error 403 Forbidden o ERR_ACCESS_DENIED.

Límites de tasa

Para cada servidor de juego de Roblox, hay un límite de 2500 solicitudes de Open Cloud por minuto. Superar esto puede hacer que los métodos de envío de solicitudes se detengan durante aproximadamente 30 segundos. Tu pcall() también puede fallar con un mensaje de Número de solicitudes de Open Cloud superó el límite.

Las solicitudes de Open Cloud no consumen el mismo límite general de 500 solicitudes HTTP por minuto impuesto a todas las demás solicitudes.
Cada punto final tiene su propio límite por propietario de clave API (puede ser un usuario o un grupo) que se aplica sin importar de dónde provengan las llamadas (HttpService, la web, etc.).

Para obtener información detallada sobre los límites de tasa de Open Cloud, la limitación de tasa basada en la autenticación y las mejores prácticas, consulta Límites de Tasa.

Mejores prácticas

Para optimizar el uso de HttpService y evitar exceder los límites, aplica las siguientes mejores prácticas:

Maneja los errores de manera adecuada. Las solicitudes web pueden fallar por muchas razones. Usa pcall() y ten un plan para cuando las solicitudes fallen. Además, valida y sanitiza estrictamente todos los datos recibidos de APIs externas, asegurando datos correctos donde puedas.
Usa retroceso exponencial para mantenerte por debajo de los límites.

Si una solicitud devuelve un error recuperable, en lugar de volver a intentar de inmediato, espera dos segundos, luego cuatro, ocho, etc. entre intentos. Esto ayuda a limitar la congestión y mejora la posibilidad de una solicitud exitosa al darle tiempo al punto final para "enfriarse".
Agrega y envía datos en bloque.

Cuando sea posible, se recomienda permitir que tu servidor recopile todos los datos necesarios para enviar una solicitud HTTP, en lugar de múltiples solicitudes pequeñas. Por ejemplo, si estás enviando una solicitud HTTP por cada jugador en tu servidor, verifica si la API tiene un punto final de carga masiva/lote y, si es así, recopila la información de todos los jugadores y envíala en una sola solicitud.

En algunos casos, es posible que debas usar HttpService:RequestAsync() para incluir datos en el cuerpo de la solicitud.
Usa puntos finales HTTP/2. HTTP/2 proporciona beneficios de rendimiento significativos a través de características como la compresión de encabezados y la multiplexión de solicitudes/respuestas a través de una sola conexión. HttpService utiliza automáticamente HTTP/2 cuando está disponible. Ten en cuenta que la especificación HTTP/2 requiere que todos los nombres de encabezados se envíen en minúsculas.

Observabilidad

El Panel de Observabilidad proporciona información y análisis para monitorear y solucionar problemas en el uso de HttpService. El panel presenta dos gráficos principales: Conteo de Solicitudes, que rastrea el volumen de solicitudes de HttpService desde tu juego, y Tiempo de Respuesta, que mide la latencia para que los puntos finales respondan.

Las dimensiones disponibles para filtrar y desglosar se definen de la siguiente manera:

Tipo de Solicitud

GET
POST
PUT
PATCH
DELETE
Otro (para tipos de solicitud no especificados)

Estado

Éxito (códigos de estado HTTP 1xx y 2xx)
Redirección (códigos de estado HTTP 3xx)
400 (Solicitud Incorrecta)
401 (No Autorizado)
403 (Prohibido)
404 (No Encontrado)
429 (Demasiadas Solicitudes)
500 (Error Interno del Servidor)
503 (Servicio No Disponible)
ExternalError (cualquier otro código de error no especificado devuelto por el servicio externo)
InternalError (un problema devuelto desde HttpService dentro de Roblox)

El gráfico de Tiempo de Respuesta no está correlacionado con los datos de estado. Si seleccionas "Estado" como desglose o filtro, este gráfico no mostrará datos.

Consideraciones adicionales

Las solicitudes deben proporcionar una forma segura de autenticación, como una clave secreta compartida previamente, para que los actores malintencionados no puedan hacerse pasar por uno de tus servidores de Roblox.
Ten en cuenta la capacidad general y las políticas de limitación de tasa de los servidores web a los que se envían las solicitudes.

Español