Manuseando solicitações da API para armazenamentos de dados

Antes de enviar solicitações para APIs de Nuvem Aberta para armazenamentos de dados padrão e armazenamentos de dados solicitados, você precisa entender como lidar com eles corretamente.Para obter informações sobre o uso da API (Interface de Programação para Aplicações), consulte o Guia de Uso.

Autorização

Como todas as APIs de nuvem aberta, os pontos de armazenamento de dados exigem que todas as solicitações incluam o cabeçalho x-api-key, que contém uma chave de API com permissões suficientes para a solicitar / pedir.Isso requer que você aplique a chave à experiência e ao lojade dados e a operação de endpoint é permitida.Se a chave for inválido, 403 Unauthorized é retornada.Para mais informações sobre chaves de API, veja Gerenciar chaves de API.

Aceleração

Todos os pontos finais têm dois tipos de redução de nível de universo: redução de solicitações por minuto e redução de tráfego .Com cada experiência, solicitações por minuto de engarrafamento permite que você envie um determinado número de solicitações por minuto e engarrafamento de taxa de transferência permite que você envie uma determinada quantidade de dados por minuto, independentemente do número de chaves da API.

Ao contrário da API (Interface de Programação para Aplicações)Luau, esses limites atualmente não aumentam de acordo com o número de usuários. Exceder esses limites faz com que o endpoint retorne 429 Too Many Requests .

Armazenamentos de dados padrão impõem limites de aceleração

Armazenamentos de dados ordenados com limites de engarrafamento

Validação de entrada

Antes de enviar sua solicitar / pedir, certifique-se de validar os parâmetros de endpoint em requisitos de formatação e restrições com base na tabela a seguir.Os pontos finais individuais podem ter requisitos adicionais além desses.Se um parâmetro não satisfizer as seguintes restrições, o ponto de extremidade retorna um 400 Bad Request .

ID do Universo

O ID do Universo é o identificador exclusivo da experiência na qual você deseja acessar seus armazenamentos de dados.O valor do ID do Universo de uma experiência é o valor de seu DataModel.GameId, não o mesmo que o ID do Local de Partida , que identifica o local de partida de uma experiência em vez de toda a experiência.

Você pode obter o ID do Universo de uma experiência com os seguintes passos:

1. Navegue até o Painel do Criador.

2. Encontre a experiência com armazenamentos de dados que você deseja acesso.

3. Passe o mouse sobre a miniatura da experiência, clique no botão ⋯ e selecione Copiar ID do Universo .

   

Escopos

Você pode organizar seus armazenamentos de dados definindo uma string única como um escopo que especifica um subdiretório para a entrada.Uma vez que você defina um escopo, ele automaticamente prepende a todas as chaves em todas as operações realizadas no lojade dados.Os escopos são opcionais e por padrão como global para armazenamentos de dados padrão, mas são necessários para armazenamentos de dados encomendados.

O escopo categoriza seus dados com uma string e um separador com "/", como:

Todos os métodos de entrada do armazenamento de dados têm um parâmetro Scope para quando você precisa acessar as entradas armazenadas sob um escopo não padrão.Por exemplo, você pode ter uma chave 1234 sob o escopo padrão global e a mesma chave sob o escopo special.Você pode acessar o primeiro sem usar o parâmetro de escopo, mas para acessar o último, você precisa especificar o parâmetro de escopo como em ou chamadas da API.

Além disso, se você quiser enumerar todas as chaves armazenadas em um armazenamento de dados que tenha uma ou mais scopes não padrão, você pode definir o parâmetro na metodologia para ser , no qual o chamado retorna um tuple com a string de chave e o escopo.No exemplo anterior, o List Entries retornaria ambos ( 1234 , global ), e ( 1234 , special ) na resposta.

Você não pode passar Scope e AllScopes parâmetros na mesma solicitar / pedir, caso contrário, a chamada retorna um erro.Ao aproveitar as funções de ajuda das APIs da Nuvem Aberta para o módulo de armazenamento de dados, o seguinte código ilustra como você pode ler cada chave em um armazenamento de dados com um escopo personalizado:

Listar chaves para diferentes escopos
# Preparar
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Listar chaves para escopo global
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Listar chaves para escopo especial
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Listar chaves para todos os âmbitos definidos como verdadeiros
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Chaves com o escopo correspondente são retornadas na resposta:

Exemplos de respostas para diferentes escopos
// Resposta para escopo global
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Resposta para escopo especial
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Resposta 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":""}

Conteúdo-MD5

O conteúdo-MD5 é o checksum MD5 codificado em base-64 do conteúdo.É um cabeçalho de solicitação opcional para o Set Entry endpoint que verifica a integridade dos dados e detecta problemas potenciais.

Você pode usar o idioma de sua escolha para calcular o valor do cabeçalho content-md5.O seguinte exemplo usa Python.As funções hashlib.md5() e base64.b64encode() estão disponíveis nas bibliotecas padrão do Python (2.7, 3+).

Gerando Conteúdo-MD5
# Com 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 apenas stdin e stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Se você encontrar problemas ao gerar um valor válido content-md5 , você pode precisar codificar o corpo da solicitação em binário UTF-8 antes de calcular o resumo de verificação.

Cursores

Endpoints que retornam listas de dados também podem retornar uma string / cadeia / textonextPageCursor .Isso indica que há mais dados disponíveis no configurarde resultados solicitado.Para recebê-lo, forneça essa string no parâmetro de consulta cursor na solicitar / pedirposterior.Se o parâmetro do cursor for fornecido, mas inválido, o ponto final retorna 400 Bad Request .

O formato das cordas do cursor não está definido . Você não deve interpretá-las ou analizá-las, pois elas podem mudar a qualquer momento.

Filtros

Ao enviar solicitações para o método List para armazenamentos de dados ordenados, você pode adicionar um parâmetro de consulta opcional filter para retornar entradas com valores em um alcance definido.

O parâmetro filter suporta um operador lógico, && , e dois operadores de comparação, <= para definir o valor máximo e >= para definir o valor mínimo.Se você quiser definir um alcance com um valor máximo e mínimo, adicione && entre as duas sequências.

Por exemplo, para retornar entradas com valores que sejam menores ou iguais a 10, você precisa inserir entry <= 10 como o valor filter.Para retornar entradas com valores entre 10 e 50, insira entry <= 50 && entry >= 10.

Os seguintes exemplos são valores incorretos filter que podem falhar em suas solicitações:

• entry <= 10 - sem espaço em branco entre cada parte da sequência.
• 10 <= entry - entry e o valor de comparação está no lado errado.
• entry <= 10 && entry <= 50 - && só pode ser usado para especificar um alcance com dois operadores de comparação para o valor mínimo e máximo.

Permitir ausência de bandeiras

Ao enviar solicitações ao método Update para atualizar um registro de armazenamento de dados existente, você pode adicionar uma bandeira opcional allow_missing para permitir a criação de um registro mesmo que o registro não exista.

Quando você define a bandeira allow_missing para True :

• Se a entrada não existir, a resposta retorna uma nova entrada.

• Se a entrada existir, mas o conteúdo corresponder ao valor existente da entrada, a entrada existente permanece inalterada.

• Se a entrada existir e o conteúdo não corresponder ao valor existente da entrada, a resposta retorna a entrada com o novo valor de conteúdo atualizado.