Esta página cubre patrones comunes con las API de Open Cloud, particularmente alrededor de hacer solicitudes y manejar respuestas.
Rutas
Para hacer una solicitud a las API de Open Cloud, debe formar una URL primero. Esta URL es una combinación de la URL de base ( https://apis.roblox.com/cloud/v2 ) y el camino de la API de Open Cloud (por ejemplo, /universo/universo-id/plazas/place-id/usario-restricciones </
Muchos caminos, incluido el ejemplo de arriba, tienen parámetros de camino , designados por curly brackets en la referencia de la API. Los parámetros de camino son solo variables que ingresas antes de hacer la solicitud y son casi siempre ID: ID del usuario, ID del grupo, ID de lugar, etc. Los ID son a menudo numéricos, pero no necesariamente; por ejemplo, los datos almacenados y los almacenados de memoria soportan un establecerde caracteres más ampl
Algunas fuentes tienen múltiples patrones de camino, visibles debajo del encabezado Caminos de recursos en la referencia de API. Por ejemplo, la URL para Restricciones de listas puede ser uno de los siguiendo:
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/user-restrictions
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/places/{place-id}/user-restrictions
Probablemente pueda inferir la diferencia entre los dos: algunas limitaciones de usuario se aplican a un universo entero (experiencia), mientras que otras se aplican a lugares específicos dentro de un universo. Aparte de la pequeña adición al parámetro de ruta y ruta extra, las llamadas son idénticas.
Muchas API返回路径 como parte de su respuesta, que puede usar para hacer solicitudes adicionales. Si una API necesita más de unos segundos para cumplir una solicitud, a menudo返回一个 oper作 rather than el recurso o la respuesta misma.
Longitud y tipo de contenido
Muchas llamadas de API, particularmente las que crean o actualizan recursos, requieren un cuerpo de solicitud JSON. Si su solicitud tiene un cuerpo, asegúrese de incluir los encabezados Content-Length y Content-Type. La mayoría de los clientes HTTP agregan automáticamente estos encabezados.
Paginación
Si especifica maxPageSize en su solicitud, algunos métodos devuelven resultados pagados: esencialmente respuestas parciales:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25
{
"inventoryItems": [
...
],
"nextPageToken": "aaaBBB"
}
Si una respuesta incluye un valor para nextPageToken , usa ese valor en el parámetro pageToken de la siguiente solicitud para recuperar la siguiente página. Cuando nextPageToken está vacío, has alcanzado el final de tus resultados:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB
{
"inventoryItems": [
...
],
"nextPageToken": ""
}
Aparte del pageToken , debes usar la misma consulta para que la página se cargue correctamente. Alterar cualquier parámetro de filtro resulta en un error 400.
Operaciones de larga duración
Algunos métodos devuelven un objeto Operation que representa una solicitud que se ejecuta en el tiempo que se necesita que devuelva una respuesta asíncrona más tarde. El objeto contiene los siguientes campos:
- camino - El camino de la interfaz de usuario para llamar para completar la solicitud. Añade el camino a la URL de la interfaz de usuario original.
- hecho - Un valor deBooleano que representa si la operación se ha completado o no.
- respuesta - La respuesta objeto. Este campo está vacío hasta que el campo done tenga un valor de true .
- metadatos - Metadatos personalizados específicos para la solicitud que se está realizando.
Objeto de Operación de Ejemplo
{
"path": "v1/assets/12345/operation/xyz",
"done": true,
"response": {
"value1": "myValue",
"value2": 1234
},
"metadata": {
"metadata1": "string",
"metadata2": 5678
}
}
Usa el camino del objeto Operation para votar cuando el recurso esté listo. Una buena estrategia es usar el backoff exponencial. Por ejemplo, puedes votar inmediatamente, luego después de un segundo, dos segundos, cuatro segundos, etc.
def PollForResults(operationPath):
currentRetries = 0
maxRetries = 10
retryPollingDelay = 1
retryPollingMultiplier = 2
while (currentRetries < maxRetries):
# Sin retraso en la primera verificar, comprobar
if (currentRetries == 0):
results = GetOperation(operationPath)
# Reproducir lógica para siguientes controles
else:
time.sleep(retryPollingDelay)
results = GetOperation(operationPath)
# Volumen de salida exponencial
retryPollingDelay *= retryPollingMultiplier
# Verifique los resultados y devuelva si existen
if (results.status_code != 200 or results.json()[doneJSONKey]):
return results
# De lo contrario, incrementa el recuento de intentos
else:
currentRetries += 1
Para un ejemplo de código más completo que usa un tiempo de reutilización fijo en lugar de un tiempo de reutilización exponencial, véase Polling for Results .
Filtrado
Algunos métodos te permiten filtrar la respuesta incluendo un parámetro filter en la solicitud. Las siguientes secciones describen la sintaxis de filtro y las pautas para los endpoints especificados.
Lista de afiliaciones de grupo
El carácter de comodín - se puede usar en lugar del ID de grupo para agrupar membresías en todos los grupos: groups/-/memberships .
La filtración coincide con el lenguaje de expresión común (CEL). Solo se admiten dos operadores:
- ==
- in [...]
Si especifica un ID de grupo en el camino de recursos, puede filtrar las membresías por usuario o rol en los siguientes formatos:
- Filtro de usuario : filter="user == 'users/9876543210'"/>
- Filtro de rol : filter="role == 'groups/123/roles/7920705'"
Si especifica el carácter de comodín para el ID del grupo, debe filtrar las membresías por usuario (hasta 50) en el siguiente formato:
- Filtro de usuario : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"
Listar artículos de inventario
Puede filtrar por estado de coleccionable, introducirde artículo de inventario y ID de artículo de inventario. Si no proporciona un filtro, todo el inventario del usuario se devuelve.
El formato de filtro es una lista separada por semicolón:
filter={field}={value};{field}={value},{value},...;{field}=...
- {field} puede ser cualquiera de los campos de tipo predeterminados o campos de ID en las siguientes tablas.
- {value} puede ser una cadena, un valor de verdadero o un conjunto de valores. Dependiendo del introducirde campo, esto puede ser un valor único (valores de campo de verdadero) o múltiples valores (valores de lista).
No puedes combinar campos de tipo y ID en el mismo filtro.
Tipos de Campos
| Filtro | Tipo | Descripción | | :---------------- | : | : | | badges | | gamePasses
Campos de ID
| Filtro | Tipo | Descripción | | :----------------- | :إلى | :
Ejemplos
Regresa todos los artículos recolectables que el usuario posee:
filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Devuelve todos los elementos de los tipos especificados:
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Devuelve todos los elementos de los tipos listados o cualquier pase de juego. Excluye las insignias de los resultados (el mismo comportamiento que si badges no estuviera incluido en el filtro):
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Restaura los elementos que coinciden con los ID especificados:
filter=assetIds=1,2,3,4
Restaura recursos, insignias, pases de juego y servidores privados que coinciden con las ID especificadas:
filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4