Pular para o conteúdo principal
Data e Schema

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Escrita de Records

Para alterar um Record, edite o valor e salve: o PlayServ envia só os campos que você mudou. Você cria Records com CreateAsync, salva com SaveAsync e exclui um por um ou por filtro. Os exemplos usam o Schema do Sky Arena; os tipos C# são configurados em Leitura de Records.

using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;

var pilots = PlayServData.Records<Pilots>();

var pilot = await pilots.LoadByNaturalKeyAsync(PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon"));
pilot.Value.Level++;
await pilot.SaveAsync();

O jogo só pode gravar numa Entity se Client Write estiver ativado para ela, veja Controle de acesso.


Criar um Record

Preencha o valor

Crie o objeto C# e defina todos os campos de que precisa. Todos os campos são enviados, inclusive os que você não definiu: um número que você não tocou vai como 0, e uma string, como null. O valor padrão do Schema só se aplica a um campo que a sua classe não tem, então defina você mesmo valores como Level = 1.

Crie o Record

CreateAsync retorna o novo Record, com o ID que o PlayServ deu a ele.

var pilot = await pilots.CreateAsync(new Pilots { Callsign = "Falcon", Level = 1 });
Debug.Log(pilot.Id);

Numa Entity que pertence a Players, o novo Record pertence ao Player logado, e pilot.Owner é o ID dele. Para isso, o jogo precisa estar conectado com um Player, veja Entities que pertencem a Players.

Para definir uma relação, use o ID do destino: Ship = new PlayServRecordRef<Ships>(shipId).


Salvar alterações

SaveAsync() envia os campos de primeiro nível que você alterou desde que o Record foi carregado ou salvo pela última vez. Uma Part ou lista alterada é enviada inteira. Os campos que você não tocou ficam como estão na plataforma, mesmo que alguém os tenha alterado nesse meio-tempo.

Cada gravação verifica se o Record mudou desde que você o carregou. Se outro Player ou uma Function salvou antes, SaveAsync lança PlayServRecordConflictException com Kind = StaleVersion, e nada é gravado.

Um conflito significa que alguém salvou antes

Chame ReloadAsync() para obter o Record atual, aplique a alteração de novo e salve. ReloadAsync() descarta as suas edições não salvas: a versão da plataforma prevalece.


Criar um Record uma única vez

ChamadaO que faz
LoadOrCreateAsync(key, () => new Pilots { … })Carrega o Record com essa chave natural ou, se ele não existir, cria um a partir da sua factory. WasCreated diz qual dos dois aconteceu. Se outro cliente criar o mesmo Record nesse instante, a chamada pode lançar PlayServRecordConflictException; chame de novo para carregar o Record.
UpsertByNaturalKeyAsync(key, value, mode)Cria o Record ou, se ele já existir, atualiza. Com PlayServUpsertMode.Seed, um Record existente fica como está; com Managed, os campos que você passar são atualizados.
var key = PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon");
var result = await pilots.LoadOrCreateAsync(key, () => new Pilots { Callsign = "Falcon" });
if (result.WasCreated) Debug.Log("Welcome, new pilot");

O campo da chave precisa estar marcado como Unique no Schema.


Excluir

ChamadaO que faz
record.DeleteAsync()Exclui um Record carregado, se ele não mudou desde que você o carregou.
DeleteByIdAsync(id)Exclui um Record pelo ID, sem carregá-lo.
DeleteMatchingAsync(query, confirmation)Exclui todos os Records que atendem à consulta, numa só chamada: todos ou nenhum.

DeleteMatchingAsync aceita só Where e Search. Passe PlayServDeleteAllConfirmation.MatchingRecords com um filtro, ou AllRecords para esvaziar a Entity. É possível excluir até 100.000 Records de uma vez quando todos os filtros são comparações simples sobre um campo de primeiro nível do tipo número, booleano, texto ou Enum; com Search ou outros filtros, até 200. Um filtro que a plataforma não consegue aplicar dessa forma é recusado. Se a seleção passar do limite, ou se algum Record selecionado ainda for referenciado por um Record fora dela, nada é excluído e você recebe um erro.

await PlayServData.Records<MatchResults>().DeleteMatchingAsync(
    new PlayServRecordQuery<MatchResults>().Where(m => m.Score == 0),
    PlayServDeleteAllConfirmation.MatchingRecords);

Gravar vários Records

ChamadaLinhasTudo ou nada?
BulkCreateAsync(values)1–200Sim: se uma linha falhar, nenhuma é criada.
BulkUpsertAsync(rows, mode)1–200Sim. Cada linha é um PlayServBulkUpsertRow<T> com a sua chave natural.
BulkSaveAsync(records) · BulkDeleteAsync(records)Qualquer quantidadeNão: cada Record é salvo ou excluído separadamente.
DeleteAllAsync(query, confirmation)Até 10.000 por padrãoNão. Prefira DeleteMatchingAsync.

As chamadas não atômicas retornam um resultado por Record: confira IsSuccess, FailedCount e Items.

Sem incrementos e sem transações

Uma gravação envia o valor que o cliente tem, então dois Players somando ao mesmo contador ao mesmo tempo podem perder uma atualização. Também não há transações com vários Records, além das chamadas em massa acima. Deixe as alterações que precisam ser exatas, como resultados de partidas ou moeda, numa Cloud Function.


Repetir com segurança

CreateAsync, BulkCreateAsync e os upserts aceitam uma chave de idempotência: uma string que você inventa para essa gravação, com até 128 caracteres. Se você repetir a chamada com a mesma chave, por exemplo depois de perder a conexão, o Record não é criado duas vezes. Sem chave, o SDK gera uma nova a cada chamada, então uma repetição feita por você cria um segundo Record. Use a mesma chave só com o mesmo valor.

await pilots.CreateAsync(new Pilots { Callsign = "Falcon" }, idempotencyKey: writeId);

Singletons

Edite o valor do singleton e salve, como num Record:

var config = await PlayServData.GetSingletonAsync<ArenaConfig>();
config.Value.MatchDuration = 240;
await config.SaveAsync();

Você não cria um singleton: o PlayServ o cria com os valores padrão na primeira leitura. Ele não pode ser excluído. Salvá-lo a partir do jogo exige Client Write na Entity, como qualquer outra gravação.


Quando uma gravação é recusada

ExceçãoQuandoO que fazer
PlayServDataAccessDeniedExceptionClient Write está desativado para esta Entity.Ative-o ou faça a alteração numa Function.
PlayServRecordConflictExceptionStaleVersion: alguém salvou o Record antes. Fora isso, um campo Unique já tem esse valor; nesse caso Kind é Unknown.Recarregue e salve de novo; ou escolha outro valor.
PlayServRecordNotFoundExceptionO Record foi excluído ou pertence a outro Player.—
PlayServDataException, BackendCode acting_player_requiredGravação numa Entity que pertence a Players sem um Player logado.Conecte-se com um Player antes.
PlayServDataException, erro de validaçãoO valor não se encaixa no Schema: BackendCode é unknown_field, missing_required_field, invalid_field_type ou validation_failed.Confira os nomes e tipos dos campos com o Schema, inclusive maiúsculas e minúsculas.
InvalidOperationExceptionTentativa de salvar um Record parcial.Recarregue-o antes.

Próximos passos

Atualizado em 21 de out. de 2026