Antes de enviar solicitudes a Open Cloud APIs para almacenamientos de datos estándar y almacenamientos de datos solicitados, necesitas entender cómo manejarlos correctamente.Para obtener información sobre el uso de la API, consulte el Guía de uso.
Autorización
Al igual que todas las API de nube abierta, los puntos finales del almacén de datos requieren todas las solicitudes para incluir el encabezado x-api-key, que contiene una clave de API con suficientes permisos para la solicitud.Esto requiere que apliques la clave a la experiencia y al tiendade datos, y la operación de punto final está permitida.Si la clave no es no válido, se devuelve 403 Unauthorized .Para obtener más información sobre las claves de API, consulte Administrar claves de API.
Aceleración
Todos los puntos finales tienen dos tipos de limitación de nivel de universo: limitación de solicitudes por minuto y limitación de ancho de banda .Con cada experiencia, limitación de solicitudes por minuto te permite enviar una cierta cantidad de solicitudes por minuto, y limitación de ancho de banda te permite enviar una cierta cantidad de datos por minuto, independientemente del número de claves API.
A diferencia de la API de Luau, estos límites actualmente no se escalan en función del número de usuarios. Exceder estos límites hace que el punto final devuelva 429 Too Many Requests .
Almacenes de datos estándar establecen límites de velocidad
introducirde solicitud | Método | Límites de aceleración |
---|---|---|
Escribir |
|
|
Leer |
|
|
Almacenamientos de datos ordenados con límites de velocidad
introducirde solicitud | Método | Límites de aceleración |
---|---|---|
Escribir |
|
|
Leer |
|
|
Validación de entrada
Antes de enviar su solicitud, asegúrese de validar los parámetros de extremo en los requisitos de formato y las limitaciones basadas en la siguiente tabla.Los puntos finales individuales pueden tener requisitos adicionales más allá de estos.Si un parámetro no satisface las siguientes restricciones, el punto final devuelve un 400 Bad Request .
Entrada | Tipo | Notas |
---|---|---|
universeId | número |
|
datastoreName | cadena |
|
scope | cadena |
|
entryKey | cadena |
|
content-md5 | cadena |
|
roblox-entry-attributes | cadena |
|
roblox-entry-userids | Cadena |
|
cursor | cadena |
|
ID del universo
El ID del universo es el identificador único de la experiencia en la que quieres acceder a tus almacenes de datos.El valor del ID del universo de una experiencia es el valor de su DataModel.GameId , no el mismo que el de su ID de lugar de inicio , 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:
Navegue hasta el Panel del creador.
Encuentra la experiencia con almacenes de datos a la que quieres acceso.
Pase el cursor sobre la miniatura de la experiencia, haga clic en el botón ⋯ y seleccione Copiar ID del universo .
Alcances
Puedes organizar tus almacenes de datos estableciendo una cadena única como alcance que especifique una subcarpeta para la entrada.Una vez que establezca un alcance, se prefiere automáticamente a todas las claves en todas las operaciones realizadas en el tiendade datos.Los alcances son opcionales y por defecto como global para almacenes de datos estándar, pero se requieren para almacenes de datos ordenados.
El alcance categoriza sus datos con una cadena y un separador con "/", como:
Clave | Alcance |
---|---|
casas/User_1 | casas |
mascotas/User_1 | mascotas |
inventario/Usuario_1 | inventario |
Todos los métodos de entrada de almacenamiento de datos tienen un parámetro Scope para cuando necesite acceder a las entradas almacenadas bajo un alcance no predeterminado.Por ejemplo, es posible que tenga una clave 1234 bajo el alcance predeterminado global y la misma clave bajo el alcance special.Puedes acceder al primero sin usar el parámetro de alcance, pero para acceder al último, debes especificar el parámetro de alcance como special en Get Entry o Increment Entry llamadas de API.
Además, si quieres enumerar todas las claves almacenadas en un almacén de datos que tenga una o más áreas no predeterminadas, puedes establecer el parámetro en el método para que sea , en cuyo caso la llamada devuelve una tupla con la cadena de clave y el alcance.En el ejemplo anterior, el List Entries devolvería ambos ( 1234 , global ), y ( 1234 , special ) en la respuesta.
No puedes pasar Scope y AllScopes parámetros en la misma solicitud, de lo contrario, la llamada devuelve un error.Al aprovechar las funciones de ayuda de las API de nube abierta para el módulo de almacén de datos, el siguiente código ilustra cómo puede leer cada clave en un almacén de datos con un alcance personalizado:
Lista de claves para diferentes ámbitos
# Establecerimport tutorialFunctionsDatastoresApi = tutorialFunctions.DataStores()datastoreName = "PlayerInventory"# Lista de claves para alcance globalspecialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)print(keys.content)# Lista de claves para alcance especialspecialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)print(keys.content)# Lista de claves para todos los alcances establecidos en verdadspecialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)print(specialScopeKeys.content)
Las claves con el alcance correspondiente se devuelven en la respuesta:
Ejemplos de respuestas para diferentes ámbitos
// Respuesta para alcance global
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }
// Respuesta para alcance especial
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}
// Respuesta para AllScopes
{"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 hash de suma de control MD5 codificado en base-64 de contenido.Es un encabezado de solicitud opcional para el punto final Establecer entrada que comprueba la integridad de los datos y detecta posibles problemas.
Puedes usar el idioma de tu elección para calcular el valor del encabezado content-md5.El siguiente ejemplo usa Python.Las funciones hashlib.md5() y base64.b64encode() están disponibles en las bibliotecas estándar de Python (2.7, 3+).
Generando contenido-MD5
# Con instrucciones$ 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 sólo stdin y stdout$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"sTf90fedVsft8zZf6nUg8g==
Si te encuentras con problemas para generar un valor válido de content-md5 , es posible que debas codificar tu cuerpo de solicitud en binario UTF-8 antes de calcular el resumen.
Cursores
Los puntos finales que devuelven listas de datos también pueden devolver una cadena nextPageCursor .Esto indica que hay más datos disponibles en el establecerde resultados solicitado.Para recibirlo, proporcione esta cadena en el parámetro de consulta cursor en una solicitud posterior.Si el parámetro del cursor se proporciona pero es no válido, el punto final devuelve 400 Bad Request .
El formato de las cadenas del cursor no está definido . No deberías interpretarlas o analizarlas como pueden cambiar en cualquier momento.
Filtrados
Al enviar solicitudes al método List para almacenamientos de datos ordenados, puedes agregar un parámetro de consulta opcional filter para devolver entradas con valores en un rango especificado.
El parámetro filter admite un operador lógico, && , y dos operadores de comparación, <= para establecer el valor máximo y >= para establecer el valor mínimo.Si quieres establecer un rango con un valor máximo y mínimo, añade && entre las dos secuencias.
Por ejemplo, para devolver entradas con valores que sean inferiores o iguales a 10, debe introducir entry <= 10 como valor filter.Para devolver entradas con valores entre 10 y 50, ingrese entry <= 50 && entry >= 10 .
Los siguientes ejemplos son valores incorrectos filter que pueden fallar sus solicitudes:
- entry <= 10 - no hay espacio en blanco entre cada parte de la secuencia.
- 10 <= entry - entry y el valor de comparación está en el lado equivocado.
- entry <= 10 && entry <= 50 - && solo se puede usar para especificar un rango con ambos operadores de comparación para el valor mínimo y máximo.
Permitir banderas faltantes
Al enviar solicitudes al método Update para actualizar una entrada de almacén de datos ordenada existente, puedes agregar una bandera opcional allow_missing para permitir la creación de una entrada incluso si la entrada 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 existente de la entrada, la respuesta devuelve la entrada con el nuevo valor de contenido actualizado.