Manipulación de solicitudes de API para almacenes de datos

*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.

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 solicitudMétodoLímites de acelerador
Escriba
  • Establecer entrada
  • Aumentar entrada
  • Eliminar entrada
  • 10 MB/min/universo escritura de salida
  • 300 requisitos/min/universo
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>

  • 20 MB/min/universo escritura de salida
  • 300 requisitos/min/universo

Límites de aceleración de almacenes de datos ordenados

Tipo de solicitudMétodoLímites de acelerador
Escriba
  • Crear
  • Incrementar
  • Actualizar
  • 1> Eliminar 1> ”

  • 300 requisitos/min/universo
Leer
  • Lista
  • Obtener
  • 300 requisitos/min/universo

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 .

EntradaTipoNotas
universeIdnúmero
datastoreNamecuerda
  • La longitud debe ser de 50 bytes o menos.
  • No puede ser nulo o vacío.
scopecuerda
  • El alcance de un tiendade datos. Véase Escalas .
  • La longitud debe ser 50 bytes o menos.
entryKeycuerda
  • La longitud debe ser de 50 bytes o menos.
  • No puede ser nulo o vacío.
content-md5cuerda

  • La base-64 codificada MD5 checksum de contenido. See Content-MD5 .
  • >

roblox-entry-attributescuerda

    SerIALizado por objeto de JSON.

  • La longitud debe ser menor a 300 caracteres.
roblox-entry-useridsCuerda
  • serializado por el array de JSON de 0-4 números.
  • No más de 4 ID de usuario.
cursorcuerda

  • Un indicador de más datos disponibles en el establecerde resultados solicitados. Ver Cursores .
  • >

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:

  1. Navegar al Panel del Creador .

  2. Encuentra la experiencia con los almacenes de datos que quieres acceso.

  3. 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 .

    Copy Universe ID option from Creator Dashboard

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:

ClaveMira
casas/User_1casas
mascotas/User_1mascotas
inventario/User_1inventario

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

# Configurar
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"
# Lista de teclas para el alcance global
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Lista las llaves para un alcance especial
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Lista las llaves para todos los valores de alcance establecidos en verdadero
specialScopeKeys = 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: 750
content-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.