Antes de enviar solicitudes a Open Cloud APIs para almacenamiento de datos estándar y almacenamiento de datos ordenados, necesitas entender cómo manejarlos correctamente. Para obtener información sobre el uso de la API, see the Guía de uso .
Autentificación
Al igual que todas las API de Open Cloud, los puntos de finalización de almacenamiento de datos requieren todos los pedidos para incluir el encabezado x-api-key, que contiene una llave de API con suficientes permisos para la solicitud. Esto requiere que apliques la llave a la experiencia y al almacén de datos, y la operación de punto de finalización está permitida. Si la llave no es vál
Acelerador
Todos los puntos de final tienen dos tipos de nivel de universo de limitación: solicitud-por-minuto limitación y a través de la limitación de velocidad . Con cada experiencia, limitación de solicitud por minuto le permite enviar un cierto número de solicitudes por minuto, y 1> limitación de velocidad1> le permite enviar una determinada cantidad de datos
A diferencia de la API de Lua, estos límites no escalan según el número de usuarios. Exceder estos límites hace que el punto de interfaz de usuario devuelva 429 Too Many Requests .
Límites estándar de almacenamiento de datos
Tipo de solicitud | Método | Límites de acelerador |
---|---|---|
Escriba |
|
|
Leer | Almacenamiento de datos de la lista Lista de entradas Obtener la entrada lista 1> Lista de versiones de la entrada 1> 4> Obtener la versión de la entrada lista 4> |
|
Límites de aceleración de almacenes de datos ordenados
Tipo de solicitud | Método | Límites de acelerador |
---|---|---|
Escriba |
1> Eliminar 1> ” |
|
Leer |
|
|
Validación de entrada
Antes de enviar su solicitud, asegúrese de validar los parámetros de los endpoints en los requisitos de formato y las limitaciones según la siguiente tabla. Los endpoints individuales pueden tener requisitos adicionales más allá de estos. Si un parámetro no satisface las siguientes limitaciones, el endpoints devuelve un 400 Bad Request .
Entrada | Tipo | Notas |
---|---|---|
universeId | número |
|
datastoreName | cuerda |
|
scope | cuerda |
|
entryKey | cuerda |
|
content-md5 | cuerda |
|
roblox-entry-attributes | cuerda |
SerIALizado por objeto de JSON. |
roblox-entry-userids | Cuerda |
|
cursor | cuerda |
|
ID del Universo
El identificador del universo es el identificador único de la experiencia en la que quieres acceder a tus almacenes de datos. El valor de un identificador de universo es el valor de su DataModel.GameId, no no es el mismo que el 2>identificador del lugar de inicio2>, que identifica el lugar de inicio de una experiencia en lugar de toda la experiencia.
Puedes obtener el ID del Universo de una experiencia con los siguientes pasos:
Navegar al Panel del Creador .
Encuentra la experiencia con los almacenes de datos que quieres acceso.
Haga clic en el botón ⋯ en la miniatura de la experiencia objetivo para mostrar una lista de opciones, luego seleccione Copiar ID del Universo .
Mira
Puede organizar sus almacenes de datos al configurar una cadena única como un alcance que especifica un sub directorio para la entrada. Una vez que se configura un alcance, se añade automáticamente a todas las llaves en todas las operaciones realizadas en el tiendade datos. Los alcances son opcionales y por defecto como global para los almacenes de datos estándar, pero requeridos para los almacenes de datos ordenados.
El alcance categoriza sus datos con una cadena y un separador con "/", como:
Clave | Mira |
---|---|
casas/User_1 | casas |
mascotas/User_1 | mascotas |
inventario/User_1 | inventario |
Todos los métodos de entrada de almacenamiento de datos tienen un parámetro Scope para cuando necesitas acceder a las entradas almac
Además, si desea contar todas las llaves almacenadas en un almacén de datos que tengan uno o múltiples escenarios no
No puedes pasar Scope y AllScopes parámetros en la misma solicitud, de lo contrario, la llamada devuelve un error. Aprovechar las funciones de ayuda de las API de Open Cloud para almacenamiento de datos, el siguiente código ilustra cómo puedes leer cada clave en un almacén de datos con un rango personalizado:
Lista de teclas para diferentes escenarios
# Configurarimport tutorialFunctionsDatastoresApi = tutorialFunctions.DataStores()datastoreName = "PlayerInventory"# Lista de teclas para el alcance globalspecialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)print(keys.content)# Lista las llaves para un alcance especialspecialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)print(keys.content)# Lista las llaves para todos los valores de alcance establecidos en verdaderospecialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)print(specialScopeKeys.content)
Las llaves con el alcance correspondiente se devuelven en la respuesta:
Ejemplos de respuestas para diferentes escenarios
// Respuesta para el alcance global
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }
// Respuesta para escopios especiales
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}
// Respuesta para Todos los Escopos
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}
Contenido-MD5
Content-MD5 es el base-64 codificado MD5 checksum de contenido. Es un encabezado de solicitud opcional para el punto de interfaz de Establecer entrada que comprueba la integridad de los datos y detecta posibles problemas.
Puede usar el lenguaje de su elección para calcular el valor del encabezado content-md5. El ejemplo siguiente usa Python. Las funciones siguientes son disponibles en librerías estándar de Python (2.7, 3+).
Generando Contenido-MD5
# Con prompts$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"content: 750content-md5: sTf90fedVsft8zZf6nUg8g==# Usando solo stdin ystdout$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"sTf90fedVsft8zZf6nUg8g==
Si te enfrentas a problemas para generar un valor de content-md5 válido, es posible que deba encodar su cuerpo de solicitud en UTF-8 antes de calcular el checksum.
Cursores
Los puntos de finalización que devuelven listas de datos también pueden devolver una cadena de nextPageCursor. Esto indica que hay más datos disponibles en el establecerde resultados solicitados. Para recibirlo, proporcione esta cadena en el parámetro de consulta de cursor en una solicitud posterior. Si el parámetro de curso de acción no se proporciona, pero no es válido, el punto de finalización devuelve 400 Bad Request</
El formato de las cadenas de cursor no está definido. No deberías interpretar o procesarlas como cambiarán en cualquier momento.
Filtros
Al enviar solicitudes a la List``filter, puede agregar un parámetro de consulta opcional para devolver entradas con valores en un rango especificado.
El parámetro filter soporta un operador lógico, && , y dos operadores de comparación, <= para establecer el valor máximo y 1> >=1> para establecer el valor mínimo. Si desea establecer un rango con ambos un valor máximo y mínimo, agregue 4> &&4> entre las dos secuencias.
Por ejemplo, para devolver entradas con valores que son menores o iguales a 10, necesita ingresar entry <= 10 como el valor de filter. Para devolver entradas con valores entre 10 y 50, ingrese entry <= 50 && entry >= 10 .
Los siguientes ejemplos son valores incorrectos de filter que pueden fallar sus solicitudes:
- entry <= 10 - no hay espacio entre cada parte de la secuencia.
- 10 <= entry - entry y el valor de comparación está en el lado incorrecto.
- entry <= 10 && entry <= 50 - && sólo se puede usar para especificar un rango con dos operadores de comparación para el valor min y max.
Permitir banderas faltantes
Al enviar solicitudes a la Update método para actualizar un almacén de datos existente, puede agregar una etiqueta de allow_missing opcional para permitir la creación de un registro incluso si el registro no existe.
Cuando estableces la bandera allow_missing a True :
Si la entrada no existe, la respuesta devuelve una nueva entrada.
Si la entrada existe pero el contenido coincide con el valor existente de la entrada, la entrada existente se mantiene sin cambios.
Si la entrada existe y el contenido no coincide con el valor actual de la entrada, la respuesta devuelve la entrada con el nuevo valor de contenido actualizado.