Gerenciando solicitações de API para armazenamentos de dados

Antes de enviar solicitações para as APIs do Open Cloud para armazenamento de dados padrão e armazenamento de dados encomendado, você precisa entender como lidar com elas 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 do Open Cloud, os endpoints 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 do endpoint é permitida. Se a chave for inválido, 403 Unauthorized será retornado. Para mais informações sobre chaves de API, consulte Gerenciando Chaves de API .

Acelerando

Todos os endpoints têm dois tipos de throttling de nível universal: throttling de solicitação por minuto e throttling de throughput . Com cada experiência, throttling de solicitação por minuto permite que você envie um certo número de solicitações por minuto e throttling de throughput permite que você envie uma certa quantidade de dados por minuto, independentemente do número de chaves de API.

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

Armazenamento de dados padrão Limites de aceleração

Limites de estrangulamento de armazenamento de dados encomendados

Validação de Entrada

Antes de enviar sua solicitar / pedir, certifique-se de validar os parâmetros do endpoint em requisitos e restrições de formatação com base na tabela a seguir. Os endpoints individuais podem ter requisitos adicionais além desses. Se um parâmetro não atender às seguintes restrições, o endpoint retornará um 400 Bad Request .

ID do Universo

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

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

1. Navegue até o Painel do Criador .

2. Encontre a experiência com os armazéns de dados aos quais deseja acesso.

3. Clique no botão **** na miniatura da experiência do alvo para exibir uma lista de opções e, em seguida, selecione Copiar ID do Universo .

   

Âmbitos

Você pode organizar seus armazéns de dados definindo uma string única como um escopo que especifica uma subpasta para a entrada. Uma vez que você definir um escopo, ele automaticamente irá preceder todas as chaves em todas as operações feitas no armazém de loja. Escopos são opcionais e por padrão como global para armazéns de dados padrão, mas necessários para armazéns de dados encomendados.

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

Todos os métodos de operação de entrada de armazenamento de dados têm um parâmetro Scope para quando você precisa acessar as entradas armazenadas em um escopo não padrão. Por exemplo, você pode ter uma 1234 chave no escopo padrão global e a mesma chave no 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 special em Get Entry ou Increment Entry chamadas de API.

Além disso, se você quiser enumerar todas as chaves armazenadas em um armazenamento de dados que tenha um ou mais escopos não padrão, você pode definir o parâmetro AllScopes no List Entries método para true , no caso da chamada retornar um tuple com string de chave e 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 retornará um erro. Aproveitando as funções de ajuda do módulo Open Cloud APIs for data stores, o código a seguir ilustra como você pode ler todas as chaves em um armazenamento de dados com um escopo personalizado:

Lista de chaves para diferentes escopos
# Configurar
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 allScope definida como true
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

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

Respostas de exemplo 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

Content-MD5 é a base-64 codificada MD5 checksum do conteúdo. É um cabeçalho de solicitação opcional para o ponto de extremidade Set Entry que verifica a integridade dos dados e detecta possíveis problemas.

Você pode usar a linguagem de sua escolha para calcular o valor do cabeçalho content-md5. O exemplo a seguir 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 gerando um valor content-md5 válido, talvez seja necessário codificar o corpo da solicitação em binário UTF-8 antes de contar a soma de verificação.

Cursores

Os 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 esta string no parâmetro de consulta cursor em uma solicitar / pedirsubsequente. Se o parâmetro do cursor for fornecido, mas inválido, o endpoint retornará 400 Bad Request .

O formato das cadeias de caracteres do cursor é não definido . Você não deve interpretá-las ou analisá-las, pois elas podem mudar a qualquer momento.

Filtros

Ao enviar solicitações para o método List para armazenamentos de dados encomendados, você pode adicionar um parâmetro de filtrofilter opcional para retornar entradas com valores em um intervalo especificado.

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 intervalo com um valor máximo e mínimo, adicione && entre as duas sequências.

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

Os seguintes exemplos são incorretos filter valores que podem falhar 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ão no lado errado.
• entry <= 10 && entry <= 50 - && só pode ser usado para especificar um intervalo com os dois operadores de comparação para o valor mínimo e máximo.

Permitir Bandeiras Ausentes

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

Quando você define a bandeira allow_missing para True :

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

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

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