Patrones

Esta página cubre patrones comunes con las API de nube abierta, particularmente alrededor de hacer solicitudes y manejar respuestas.

Caminos

Para hacer una solicitud a las API de nube abierta, primero debes formar una URL.Esta URL es una combinación de la URL base (https://apis.roblox.com/cloud/v2), el camino de la API de nube abierta (por ejemplo, /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

Muchos caminos, incluido el ejemplo anterior, tienen parámetros de ruta , designados por curly brackets en la referencia de la API.Los parámetros de ruta son solo variables que insertas antes de hacer la solicitud y casi siempre son ID: ID de usuario, ID de grupo, ID de lugar, etc.A menudo, las identificaciones son numéricas, pero no necesariamente; por ejemplo, las identificaciones de almacén de datos y almacén de memoria admiten un establecerde caracteres más amplio.

Algunos recursos tienen múltiples patrones de ruta visibles bajo el encabezado Caminos de recursos en la referencia de la API.Por ejemplo, la URL para Listar restricciones de usuario puede ser cualquiera de las 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 puedas inferir la diferencia entre los dos: algunas restricciones 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 camino y el parámetro de ruta adicional, las llamadas son idénticas.

Muchas API devuelven un camino como parte de su respuesta, que puedes usar para hacer más solicitudes.Si una API necesita más de unos pocos segundos para cumplir con una solicitud, a menudo devuelve una operación en lugar de la propia recurso o respuesta.

Longitud y introducirde contenido

Muchas llamadas de API, particularmente las que crean o actualizan recursos, 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 agrega estas cabeceras automáticamente.

Paginación

Si especifica maxPageSize en su 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 , use ese valor en el parámetro pageToken de la solicitud siguiente para recuperar la siguiente página.Cuando nextPageToken está vacío o se omite por completo, 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, debe usar la misma consulta para que la página funcione correctamente. Al cambiar cualquier parámetro de filtro se produce un error de 400.

Operaciones de ejecución larga

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:

camino - El camino de punto final para llamar a poll para la finalización de la solicitud. Añade el camino a la URL original de la base del método de recursos.
terminado - Un valor booleano que representa si la operación se ha completado o no.
respuesta - 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á haciendo.

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 la recurso esté lista.Una buena estrategia es usar retroceso exponencial.Por ejemplo, puedes encuestar 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 demora en la primera verificar, comprobar
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Retomar la lógica para verificaciones posteriores
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Retroceso exponencial
            retryPollingDelay *= retryPollingMultiplier
        # Compruebe los resultados y devuelva si existen
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # De lo contrario, aumenta el recuento de reintentos
        else:
           currentRetries += 1

Para un ejemplo de código más completo que utiliza un intervalo de reintentos fijo en lugar de un retroceso exponencial, vea Encuesta para obtener resultados.

Filtreo

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

Lista de membresías de grupo

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

La filtración se ajusta al idioma 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 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 del inventario

Puedes filtrar por estado de coleccionable, introducirde artículo de inventario y ID de artículo de inventario.Si no proporciona un filtro, se devuelve todo el inventario del usuario.

El formato de filtro es una lista separada por comas:

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

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

No puedes combinar campos de tipo y de ID en el mismo filtro.

Campos de tipo

| Filtro | Tipo | Descripción - | :------------------------ | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- - | | badges | boolean | Incluye insignias en la respuesta.Por defecto es falso. | | gamePasses | booleano | Incluir pases de juego en la respuesta.Por defecto es falso. | | inventoryItemAssetTypes | Vea detalles de activos para la lista completa de tipos de activos.| Lista separada por comas de tipos de activos para incluir.Por defecto es ninguno.Especifique * para todos los tipos de activos.Debe tener alcance de lectura de inventario para filtrar por lugares comprados. | | onlyCollectibles | boolean | Incluya solo coleccionables en la respuesta.Por defecto es falso.Este campo debe usarse con el campo inventoryItemAssetTypes para devolver artículos y solo devuelve artículos limitados no UGC.| | privateServers | booleano | Incluir servidores privados en la respuesta.Por defecto es falso.Debe tener alcance de lectura de inventario para filtrar por este campo. |

Campos de ID

Ejemplos

Devuelve todos los artículos coleccionables 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 artículos de los tipos enumerados o cualquier pase de juego.Excluye insignias de los resultados (el mismo comportamiento que si badges no se incluyó en el filtro):

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Devuelve recursos que coincidan con los ID especificados:

filter=assetIds=1,2,3,4
Devuelve recursos, insignias, pases de juego y servidores privados que coinciden con los ID especificados:

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

En esta página