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

Antes de enviar solicitudes a las API de Open Cloud para almacenes de datos estándar y almacenes de datos ordenados, debe comprender cómo manejarlas correctamente. Para obtener información sobre el uso de la API, consulte la Guía de uso.

Autorización

Al igual que todas las API de Open Cloud, los puntos de enlace del almacén de datos requieren que todas las solicitudes incluyan el encabezado x-api-key, que contiene una clave de API con permisos suficientes para la solicitud. Esto requiere que aplique la clave a la experiencia y al almacén de datos, y se permite la operación del punto de enlace. Si la clave no es no válido, se devolverá 403 Unauthorized. Para obtener más información sobre las claves de API, consulte Administración de claves de API .

Acelerando

Todos los puntos finales tienen dos tipos de throttling de nivel universal: throttling de solicitud por minuto y throttling de rendimiento . Con cada experiencia, throttling de solicitud por minuto le permite enviar un cierto número de solicitudes por minuto, y throttling de rendimiento le permite enviar una cierta cantidad de datos por minuto, independientemente del número de claves de API.

A diferencia de la API de Lua, estos límites actualmente no se amplían 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 Límite de aceleración

Tipo de solicitud	Método	Límites de acelerador
Escribir	Establecer entrada Incrementar entrada Eliminar entrada	10 MB/min/universe write throughput 300 reqs/min/universe
Leer	Almacenes de datos de lista Entradas de lista Obtener entrada Versiones de entrada de lista Obtener versión de entrada	20 MB/min/universe write throughput 300 reqs/min/universe

Almacenes de datos ordenados Límite de aceleración

Tipo de solicitud	Método	Límites de acelerador
Escribir	Crear Incremento Actualización Borrar	300 reqs/min/universo
Leer	Lista Obtener	300 reqs/min/universo

Validación de entrada

Antes de enviar su solicitud, asegúrese de validar los parámetros del punto final en los requisitos y restricciones de formato basados en la siguiente tabla. Los puntos finales individuales pueden tener requisitos adicionales además de estos. Si un parámetro no cumple con las siguientes restricciones, el punto final devuelve un 400 Bad Request .

Los endpoints de Data Stores ordenados usan Perfect-Encoding para todos los parámetros de la consulta y del cuerpo. A menos que tenga caracteres especiales en los valores de los parámetros que rompen las URL, no necesita manejar la codificación usted mismo.

Ingresar	Tipo	Notas
universeId	número	El identificador único de tu experiencia. Véase Universe ID .
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. Véase Alcances . 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 base-64 codificada MD5 checksum del contenido. Véase Contenido-MD5 .
roblox-entry-attributes	cadena	Serializado por objeto JSON. La longitud debe ser inferior a 300 bytes.
roblox-entry-userids	Cadena	Serializado por un 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. Véase Cursores .

ID del Universo

El Universe ID es el identificador único de la experiencia en la que desea acceder a sus almacenes de datos. El valor del Universe ID de una experiencia es el valor de su DataModel.GameId , no lo mismo que el Starting Place ID , que identifica el lugar de inicio de una experiencia en lugar de toda la experiencia.

Puedes obtener el Universe ID de una experiencia con los siguientes pasos:

Vaya al Panel del Creador .
Encuentra la experiencia con los almacenes de datos a los que quieres acceso.
Haga clic en el botón **** en la miniatura de la experiencia de destino para mostrar una lista de opciones y, a continuación, seleccione Copiar ID del Universo .

Escopetas

Puede organizar sus almacenes de datos configurando una cadena única como un alcance que especifica una subcarpeta para la entrada. Una vez que configure un alcance, se añadirá automáticamente a todas las teclas en todas las operaciones realizadas en el tiendade datos. Los alcances son opcionales y, por defecto, son global para los almacenes de datos estándar, pero son necesarios para los almacenes de datos ordenados.

Se recomienda usar el parámetro prefix en lugar de scope para ordenar y enumerar los almacenes de datos estándar .

El alcance categoriza sus datos con una cadena y un separador con "/," como:

Llave	Alcance
casas/Usuario_1	casas
mascotas/Usuario_1	mascotas
inventario/Usuario_1	inventario

Todos los métodos de operación 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, puede tener una 1234 clave bajo el alcance global predeterminado, y la misma clave bajo el alcance special. Puede acceder al primero sin usar el parámetro de alcance, pero para acceder al último, debe especificar el parámetro de alcance como special en Get Entry o Increment Entry llamadas de API.

Además, si desea enumerar todas las llaves almacenadas en un almacén de datos que tenga uno o más alcances no predeterminados, puede establecer el parámetro AllScopes en el método List Entries como true , en cuyo caso la llamada devuelve un tuple con una cadena de teclas y un alcance. En el ejemplo anterior, el List Entries devolvería ambos (1234 , global ) y (1234 , special ) en la respuesta.

No puede pasar Scope y AllScopes parámetros en la misma solicitud, de lo contrario la llamada devuelve un error. Aprovechando las funciones de ayuda del módulo Open Cloud APIs para almacenes de datos, el siguiente código ilustra cómo puede leer todas las teclas en un almacén de datos con un alcance personalizado:

Lista de llaves para diferentes alcances
# Configurar
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Lista de teclas para alcance global
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global",  allScopes = False)
print(keys.content)
# Lista de teclas para el alcance especial
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Lista de teclas para todo el alcance establecido en verdadero
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Las llaves con el alcance correspondiente se devuelven en la respuesta:

Respuestas de ejemplo para diferentes alcances
// 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 la base-64 codificada MD5 checksum del contenido. Es un encabezado de solicitud opcional para el Set Entry punto final que comprueba la integridad de los datos y detecta posibles problemas.

Si no incluye el encabezado content-md5 en su solicitud, existe la posibilidad, aunque la probabilidad es baja, de que experimente una corrupción de datos.

Puede usar el idioma de su 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 indicaciones
$ 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 solo 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 encuentra problemas para generar un valor content-md5 válido, es posible que deba codificar el cuerpo de su solicitud en binario UTF-8 antes de calcular la suma de comprobación.

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 no es no válido, el punto final devuelve 400 Bad Request .

El formato de las cadenas del cursor es no definido . No debe interpretarlos ni análisisarlos, ya que pueden cambiar en cualquier momento.

Filtros

Al enviar solicitudes al método List para almacenes de datos ordenados, puede agregar un parámetro de filtrofilter opcional 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 desea establecer un rango con un valor máximo y mínimo, agregue && entre las dos secuencias.

Por ejemplo, para devolver entradas con valores menores o iguales a 10, debe ingresar entry <= 10 como el valor filter. Para devolver entradas con valores entre 10 y 50, ingrese entry <= 50 && entry >= 10.

Para ingresar un valor válido filter, debe dar formato a todas las cadenas filter con un espacio en blanco entre cada parte de la secuencia. La parte izquierda de cada secuencia debe comenzar con 'entrada', y la parte derecha debe tener un valor numérico. Las cadenas Filter también son sensibles a las mayúsculas.

Los siguientes ejemplos no son correctos filter valores 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án en el lado equivocado.
entry <= 10 && entry <= 50 - && solo se puede usar para especificar un rango con ambos operadores de comparación para los valores min y max.

Permitir Banderas Ausentes

Al enviar solicitudes al Update método para actualizar una entrada de almacén de datos ordenada existente, puede agregar una bandera allow_missing opcional 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 permanece 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.