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 la Configuración de la experiencia para tu juego.
Uso en plugins
Puedes usar HttpService en plugins de Studio para verificar actualizaciones, descargar contenido u otra lógica comercial. La primera vez que un plugin intenta usar el servicio, se le puede pedir al usuario que le conceda al plugin permiso para comunicarse con la dirección web en particular. Los usuarios pueden aceptar, denegar y revocar estos permisos en cualquier momento a través de la ventana de Gestión de plugins.
Los plugins también pueden comunicarse con otro software que esté ejecutándose en la misma computadora a través de los hosts localhost y 127.0.0.1. Al ejecutar programas compatibles con tales plugins, puedes ampliar la funcionalidad de tu plugin 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 plugin en sí y puede representar riesgos de seguridad.
Uso con Open Cloud
HttpService actualmente puede 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:
- 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", -- ¡Al enviar 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("Cabeceras 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 admitidos
Los siguientes puntos finales son admitidos. Debido a las limitaciones actuales en HttpService, la cadena .. no está permitida en los parámetros de ruta de la URL para los dominios de Roblox. Esto significa, por ejemplo, que las tiendas de datos y las entradas que contienen esta cadena son actualmente inaccesibles desde HttpService.
Activos
Prohibiciones y bloqueos
Configs
Tienda del creador
Productos de desarrollador
Pases de juego
Tiendas de datos y memoria
Tiendas de datos:
Tiendas de memoria:
Tiendas de datos ordenados:
Grupos
Inventarios
Ejecución de Luau
Notificaciones
Lugares
Universos
Usuarios
Limitaciones
- Solo se permiten los encabezados x-api-key y content-type.
- La cadena ".." no está permitida en los parámetros de ruta de la 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. Exceder este límite 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 excedió el límite.
- Las solicitudes de Open Cloud no consumen el mismo límite general de 500 solicitudes HTTP por minuto que se aplica a todas las demás solicitudes.
- Cada punto final tiene su propio límite por propietario de clave API (que 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 tasas basada en la autenticación y las mejores prácticas, consulta Límites de tasa.
Mejores prácticas
Para optimizar tu uso de HttpService y evitar exceder los límites, aplica las siguientes mejores prácticas:
Maneja los errores de forma elegante. Las solicitudes web pueden fallar por muchas razones. Usa pcall() y ten un plan para cuando las solicitudes fallen. Además, valida y desinfecta estrictamente todos los datos recibidos de APIs externas, asegurando la corrección de los datos donde puedas.
Utiliza retroceso exponencial para mantenerte por debajo de los límites.
Si una solicitud devuelve un error recuperable, en lugar de intentarlo de inmediato, espera dos segundos, luego cuatro, ocho, etc. entre intentos. Esto ayuda a reducir la congestión y mejora la probabilidad de una solicitud exitosa al darle al punto final tiempo para "enfriarse".
Agrega y envía datos en bloque.
Cuando sea posible, se recomienda 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 para 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.
Utiliza puntos finales HTTP/2. HTTP/2 proporciona beneficios de rendimiento significativos a través de características como compresión de encabezados y multiplexació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 se envíen todos los nombres de los encabezados en minúsculas.
Observabilidad
El Panel de Observabilidad proporciona información y análisis para monitorear y solucionar problemas relacionados con el uso de HttpService. El panel cuenta con 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 el filtrado y desglose se definen de la siguiente manera:
Tipo de solicitud
- GET
- POST
- PUT
- PATCH
- DELETE
- Otro (para tipos de solicitudes no especificados)
Estado
- Éxito (códigos de estado HTTP 1xx y 2xx)
- Redireccionar (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 precompartida, 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 tasas de los servidores web a los que se están enviando las solicitudes.