Patrones

Esta página cubre patrones comunes con las API de Open Cloud, particularmente en relación con la realización de solicitudes y el manejo de respuestas.

Rutas

Para hacer una solicitud a las API de Open Cloud, primero debes formar una URL. Esta URL es una combinación de la URL base (por ejemplo, https://apis.roblox.com), la ruta de la API de Open Cloud (por ejemplo, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), y cualquier parámetro de consulta (por ejemplo, ?maxPageSize=25). Una URL de solicitud completa podría verse así:

https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Muchas rutas, incluida la del ejemplo anterior, tienen parámetros de ruta, designados por llaves en la referencia de la API. Los parámetros de ruta son simplemente variables que insertas antes de hacer la solicitud y casi siempre son IDs: IDs de usuario, IDs de grupo, IDs de lugar, etc. Los IDs son a menudo numéricos, pero no necesariamente; por ejemplo, los IDs de almacenes de datos y almacenes de memoria admiten un conjunto de caracteres más amplio.

Longitud y tipo de contenido

Muchas llamadas a la API, en particular aquellas que crean o actualizan, requieren un cuerpo de solicitud JSON. Si tu solicitud tiene un cuerpo, asegúrate de incluir los encabezados Content-Length y Content-Type. La mayoría de los clientes HTTP añaden estos encabezados automáticamente.

Paginación

Si especificas maxPageSize en tu solicitud, algunos métodos devuelven resultados paginados—esencialmente respuestas parciales:

GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

Si una respuesta incluye un valor para nextPageToken, utiliza ese valor en el parámetro pageToken de la solicitud subsecuente para recuperar la siguiente página. Cuando nextPageToken está vacío o completamente omitido, has llegado al final de tus resultados:

GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

Aparte del pageToken, debes utilizar la misma consulta para que la paginación funcione correctamente. Alterar cualquier parámetro de filtro resulta en un error 400.

Open Cloud v2

Múltiples rutas

Algunos recursos tienen múltiples patrones de ruta, visibles bajo el encabezado Rutas del recurso en la referencia de la API. Por ejemplo, la URL para Listar Restricciones de Usuario puede ser cualquiera de las siguientes:

• 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 puedas inferir la diferencia entre las dos: algunas restricciones de usuario se aplican a un universo entero (juego), mientras que otras se aplican a lugares específicos dentro de un universo. Aparte de la pequeña adición a la ruta y el parámetro de ruta adicional, las llamadas son idénticas.

Muchos endpoints devuelven una ruta como parte de su respuesta, que puedes utilizar para realizar más solicitudes. Si una API necesita más de unos pocos segundos para cumplir una solicitud, a menudo devuelve una operación en lugar del recurso o la respuesta en sí.

Operaciones de larga duración

Algunos métodos devuelven un objeto Operation que representa una solicitud de larga duración que devuelve una respuesta asincrónica más tarde. El objeto contiene los siguientes campos:

• path - La ruta del endpoint a la que llamar para sondear la finalización de la solicitud. Agrega la ruta a la URL base original del método de recurso.
• done - Un valor booleano que representa si la operación ha finalizado o no.
• response - El objeto de respuesta. Este campo está vacío hasta que el campo done tenga un valor de true.
• metadata - Metadatos personalizados específicos de la solicitud que se está realizando.

Ejemplo de objeto de operación
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "miValor",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "cadena",
    "metadata2": 5678
  }
}

Utiliza la ruta del objeto Operation para sondear cuándo el recurso está listo. Una buena estrategia es utilizar retroceso exponencial. Por ejemplo, podrías sondear 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 verificación
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Lógica de reintento para verificaciones subsecuentes
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Retroceso exponencial
            retryPollingDelay *= retryPollingMultiplier
        # Verificar resultados y devolver si existen
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # De lo contrario, incrementar el conteo de reintentos
        else:
           currentRetries += 1

Para un ejemplo de código más completo que utiliza un intervalo de reintento fijo en lugar de retroceso exponencial, consulta Sondear resultados.

Filtrado

Algunos métodos te permiten filtrar la respuesta incluyendo un parámetro filter en la solicitud. Las siguientes secciones describen la sintaxis de filtro y las directrices para los endpoints especificados.

Listar membresías de grupo

El carácter comodín - puede usarse en lugar del ID de grupo para listar membresías en todos los grupos: groups/-/memberships.

El filtrado se ajusta al Lenguaje de Expresión Común (CEL). Solo se admiten dos operadores:

• ==
• in [...]

Si especificas un ID de grupo en la ruta del recurso, puedes 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 especificas el carácter comodín para el ID de grupo, debes 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 elementos del inventario

Puedes filtrar por estado de coleccionable, tipo de elemento del inventario e ID del elemento del inventario. Si no proporcionas un filtro, se devuelve todo el inventario del usuario.

El formato del filtro es una lista separada por punto y coma:

filter={field}={value};{field}={value},{value},...;{field}=...

• {field} puede ser cualquiera de los campos de tipo predefinidos o campos de ID en las siguientes tablas.
• {value} puede ser una cadena, booleano o enumeración. Dependiendo del tipo de campo, esto puede ser un solo valor (campos booleanos) o múltiples valores (campos de lista).

Campos de tipo

Campos de ID

Ejemplos

• Devuelve todos los elementos coleccionables que posee el usuario:

  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 insignias de los resultados (el mismo comportamiento que si badges no se hubiera incluido en el filtro):

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Devuelve activos que coincidan con los IDs especificados:

  filter=assetIds=1,2,3,4

• Devuelve activos, insignias, pases de juego y servidores privados que coincidan con los IDs especificados:

  filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4