> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de programação de entidades

> Introdução ao modelo de programação de entidades do PlayFab, aos identificadores EntityKey, aos perfis e a como as APIs de entidade se comparam às APIs clássicas do PlayFab.

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_account`s), 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](xref:titleid.playfabapi.com.authentication.authentication)
* [Profiles](xref:titleid.playfabapi.com.profiles.accountmanagement)
* [Groups](xref:titleid.playfabapi.com.groups.groups)
* [Data - File](xref:titleid.playfabapi.com.data.file)
* [Data - Object](xref:titleid.playfabapi.com.data.object)
* [Events](/pt-BR/services/playfab/api-references/events)
* [CloudScript](xref:titleid.playfabapi.com.cloudscript.server-sidecloudscript)
* [Multiplayer](xref:titleid.playfabapi.com.multiplayer.multiplayerserver)

### 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`.

<Note>
  Eles *diferenciam maiúsculas de minúsculas*. Outros valores/valores personalizados *não* funcionarão no momento.
</Note>

### 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](/pt-BR/services/playfab/get-started/concepts#studios-namespaces-and-titles).

Algumas APIs usam o termo mais antigo **publisher** para esse escopo. A Publisher ID identifica o namespace.

<Note>
  As alterações nessa entidade não são refletidas em tempo real.
</Note>

Defina o campo `ID` como seu `GamePublisherId`. Para obter seu `GamePublisherId`:

* Entre no [Game Manager](https://developer.playfab.com).
* 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.

<Note>
  As alterações nessa entidade não são refletidas em tempo real.
</Note>

Defina o campo `ID` como o `TitleId` do seu jogo. Para obter seu `TitleId`:

* Entre no [Game Manager](https://developer.playfab.com).
* 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](xref:titleid.playfabapi.com.client.characters.getalluserscharacters).

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](xref:titleid.playfabapi.com.groups.groups.listmembership).

### 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](xref:titleid.playfabapi.com.authentication.authentication.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](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetentitytoken).


## Related topics

- [Documentação do gerenciamento de serviços ao vivo do PlayFab](/pt-BR/services/playfab/live-service-management/index.md)
- [Grupos de entidades](/pt-BR/services/playfab/community/associations/groups/quickstart.md)
- [Visão geral da configuração do servidor de jogo](/pt-BR/services/playfab/live-service-management/game-configuration/index.md)
- [Tabelas de classificação de grupos](/pt-BR/services/playfab/community/leaderboards/group-leaderboards.md)
- [PlayStream com eventos de entidade](/pt-BR/services/playfab/data-analytics/ingest-data/playstream-with-entity-events.md)