Modelo de programação de entidades

As entidades são as “coisas” endereçáveis mais básicas sobre as quais as APIs do PlayFab operam. Cada entidade tem um Type e uma Id que, juntos, a identificam de forma exclusiva. Alguns tipos de entidade são “padrão” ou “internos”, no sentido de que o PlayFab sabe algo sobre seu significado e/ou os cria automaticamente, por exemplo namespace, title, group, master_player_account e title_player_account. Outros podem não ter nenhum significado inerente para o PlayFab, mas ter significado no seu jogo. Cada entidade tem um perfil que contém vários recursos pertencentes a ela. Por exemplo, objetos, arquivos, configurações de idioma, políticas e outros que ainda virão. Um perfil de entidade é recuperado diretamente com a API GetProfile, e muitas outras APIs operam em recursos específicos dentro do perfil, como SetObjects. Por fim, há relações pai/filho entre entidades, que influenciam as permissões que regem como os recursos de uma entidade podem ser acessados por outras entidades. Os “ancestrais” de uma determinada entidade podem ser encontrados na propriedade Lineage do seu perfil.

​

Comparação com a API clássica

Com isso esclarecido, vamos ver as diferenças entre as APIs “clássicas” e as de “entidade”. Se você estiver usando as APIs clássicas, já estará trabalhando com as mesmas entidades que pode usar com as APIs de entidade, mas elas nem sempre são explícitas. Por exemplo, na API de cliente, UpdateUserData opera em uma entidade title_player_account, GetUserPublisherData opera em uma master_player_account, GetCharacterStatistics opera em um character (que é filho da title_player_account), GetTitleData opera em um título e GetPublisherData opera em um namespace. Em geral, cada API clássica opera em um tipo específico de entidade, mas o tipo de entidade costuma ser implícito e não decorre necessariamente do nome da API. Além disso, as APIs equivalentes para dois tipos de entidade podem variar sutilmente em relação a parâmetros, limites e comportamento (por exemplo, UpdatePlayerStatistics em comparação com UpdateCharacterStatistics). Se isso parece confuso, você não está sozinho. Queríamos simplificar as APIs do PlayFab sem nunca quebrar a compatibilidade com o conjunto existente, o que nos leva a… “APIs de entidade” é como temos chamado as APIs mais recentes do PlayFab, que seguem os seguintes objetivos de design (com algumas exceções).

• Funcionar com tipos arbitrários de entidades.
• Ter parâmetros explícitos para o Type e a Id da entidade.
• Executar uma operação específica em um recurso específico do perfil da entidade.
• Poder ser chamadas em vários contextos de segurança, como em clientes de jogo, servidores de jogo, Cloud Script e servidores de back-end, com as permissões definidas por políticas e selecionadas de acordo com a entidade que está chamando a API.

Acreditamos que seguir esses princípios resultará em menos APIs que fazem mais, são mais eficientes de manter e operar e são mais fáceis de aprender para os desenvolvedores. Basicamente, é assim que projetaríamos todas as APIs do PlayFab se começássemos do zero, sabendo tudo o que aprendemos nos últimos cinco anos sobre como os desenvolvedores usam o PlayFab. É claro que um dos nossos princípios mais importantes no PlayFab é nunca quebrar títulos ao vivo, se possível, o que significa que precisamos manter a compatibilidade com versões anteriores de todas as APIs lançadas.

​

Considerações para usuários da API clássica

Para atingir nossos objetivos de design mantendo a compatibilidade, geralmente temos introduzido essas APIs de entidade como um conjunto separado, existindo lado a lado com as APIs clássicas. Embora as APIs de entidade possam funcionar com as mesmas entidades que as APIs clássicas, na maioria dos casos elas operam em um conjunto separado de recursos/dados pertencentes a essas entidades. Por exemplo, a API de entidade SetObjects e a API clássica UpdateUserData podem armazenar dados em uma entidade title_player_account, mas os dados que as duas APIs “veem” são separados. Estas são algumas das implicações práticas:

​

O lado ruim

• Se o seu título já usa APIs clássicas para dados do jogador, inventários e outros recursos (também conhecidos como title_player_accounts), esses dados existentes não aparecerão automaticamente nas APIs de entidade equivalentes.
• Leva algum tempo até que as APIs de entidade tenham paridade de recursos com as APIs clássicas. Os dados são armazenados separadamente na maioria dos casos, e muitas alterações de back-end são necessárias para dar suporte a elas. Pode haver alguma funcionalidade clássica que nunca chegue à API de entidade.

​

O lado bom

• Você não precisa fazer nada. Se o seu jogo já funciona bem com as APIs clássicas do PlayFab, ele continuará funcionando.
• Você pode começar a usar as APIs de entidade enquanto continua usando as APIs clássicas no mesmo conjunto de entidades. Em algumas situações, há benefícios claros em fazer isso com pouco custo. Por exemplo, você pode adicionar um recurso que salva quantidades maiores de dados em um arquivo, além das configurações existentes armazenadas nos “dados do jogador” clássicos.

​

Visão geral da funcionalidade

O modelo de programação de entidades é a base da próxima geração de dados e serviços de jogo do PlayFab.

• Authentication
• Profiles
• Groups
• Data - File
• Data - Object
• Events
• CloudScript
• Multiplayer

​

Tipos de entidade compatíveis

A lista a seguir descreve os tipos de entidade disponíveis, que podem ser usados para construir uma EntityKey. As chaves de entidade são usadas para identificar entidades na maioria dos métodos de API mais recentes. Esses valores devem ser usados no campo EntityKey.Type.

​

namespace

A entidade namespace representa a identidade do jogador entre títulos e o escopo de dados compartilhados. Por padrão, ela abrange todos os títulos de um estúdio. O namespace é diferente do estúdio, que é um agrupamento administrativo. Para obter mais informações, consulte Conceitos do PlayFab. Algumas APIs usam o termo mais antigo publisher para esse escopo. A Publisher ID identifica o namespace. Defina o campo ID como seu GamePublisherId. Para obter seu GamePublisherId:

• Entre no Game Manager.
• Na página My Studios and Titles, selecione o título apropriado.
• Selecione o ícone de engrenagem no canto esquerdo da página do título e, em seguida, selecione Title Settings.
• Selecione a guia API Features.

A Publisher ID na página API Features é seu GamePublisherId e a ID do namespace.

​

title

A entidade title representa as informações globais com escopo de um título. Um título é um recurso isolado do PlayFab para um jogo ou ambiente de jogo. Defina o campo ID como o TitleId do seu jogo. Para obter seu TitleId:

• Entre no Game Manager.
• Na página My Studios and Titles, localize seu título.

A Title ID aparece abaixo do nome do seu título.

​

master_player_account

A master_player_account é uma entidade de jogador compartilhada por todos os títulos de um namespace. Defina o campo ID como o PlayFabId da API clássica, retornado por qualquer LoginResult.PlayFabId.

​

title_player_account

title_player_account, para a maioria dos desenvolvedores, representa o jogador da forma mais tradicional. Defina o campo ID como LoginResult.EntityToken.Id na API de cliente ou GetEntityTokenResponse.Entity.Id na API de autenticação.

​

character

O character é uma subentidade de title_player_account e é um espelho direto de Characters nas APIs clássicas. Defina o campo ID como qualquer characterId de result.Characters[i].CharacterId.

​

group

O group é uma entidade que contém outras entidades. No momento, ele está limitado a jogadores e personagens. Defina o campo ID como result.Group.Id se você estiver criando um grupo, ou result.Groups[i].Group.Id ao listar suas associações.

​

game_server

A entidade game_server é uma entidade exclusiva usada pelos servidores de jogo principalmente nos recursos de Matchmaking e Lobby. Cenários futuros poderão ser adicionados para oferecer suporte a outros recursos do PlayFab. Essa entidade dá aos servidores de jogo sua própria identidade, o que é útil para identificá-los de forma exclusiva ao assinar atualizações em tempo real de Matchmaking e Lobby, além de oferecer suporte a recursos específicos, como a migração de proprietário do lobby. Para se autenticar como uma entidade game_server, chame a API AuthenticateGameServerWithCustomId como uma entidade de título e obtenha o par de chave e token da entidade game_server. Use essa chave de entidade ao usar o PlayFab Multiplayer SDK com PFMultiplayerSetEntityToken.