Manipulación de solicitudes de API para almacenes de datos | Documentación del Centro de creación de Roblox

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	Establecer entrada Incrementar entrada Eliminar entrada	10 MB/min/rendimiento de escritura del universo 300 solicitudes/min/universo
Leer	Tiendas de datos de lista Obtener entradas de lista Obtener versión de entrada Obtener versión de entrada de lista Obtener versión de entrada	20 MB/min/rendimiento de escritura del universo 300 solicitudes/min/universo

Almacenamientos de datos ordenados con límites de velocidad

introducirde solicitud	Método	Límites de aceleración
Escribir	Crear Incremento Actualizar Eliminar	300 solicitudes por minuto/universo
Leer	Lista Obtener	300 solicitudes por minuto/universo

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 .

Los puntos finales de almacenes de datos ordenados utilizan Codificación porcentual para todos los parámetros de consulta y cuerpo.A menos que tenga caracteres especiales en sus valores de parámetro que rompan URL, no necesita manejar la codificación usted mismo.

Entrada	Tipo	Notas
universeId	número	El identificador único de tu experiencia. Vea ID del universo.
datastoreName	cadena	La longitud debe ser de 50 bytes o menos. No puede ser nulo o vacío.
scope	cadena	El alcance de un tiendade datos. Vea Escopos. La longitud debe ser de 50 bytes o menos.
entryKey	cadena	La longitud debe ser de 50 bytes o menos. No puede ser nulo o vacío.
content-md5	cadena	La suma de control MD5 codificada en base-64 del contenido. Vea Contenido-MD5.
roblox-entry-attributes	cadena	Serizado por objeto JSON. La longitud debe ser menor de 300 bytes.
roblox-entry-userids	Cadena	Serizado por array JSON de 0-4 números. No más de 4 ID de usuario.
cursor	cadena	Un indicador de más datos disponibles en el establecerde resultados solicitado. Ver Cursores .

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.

Se recomienda fuertemente usar el parámetro prefix en lugar de scope para ordenar y listar datos estándar almacenados.

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
# Establecer
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Lista de claves para alcance global
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Lista de claves para alcance especial
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Lista de claves para todos los alcances establecidos en verdad
specialScopeKeys = 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.

Si no incluyes el encabezado content-md5 en tu solicitud, hay una probabilidad, aunque baja, de que puedas experimentar la corrupción de datos.

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: 750
content-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 .

Para introducir un valor válido de filter, necesitas formatear todas las filter cadenas con un espacio en blanco entre cada parte de la secuencia.La parte izquierda de cada secuencia debe comenzar con 'entry', y la parte derecha debe tener un valor numérico.Filter

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.