Modelo de programación de entidades

Las entidades son las “cosas” direccionables más básicas sobre las que operan las API de PlayFab. Cada entidad tiene un tipo (Type) y un identificador (Id) que juntos la identifican de forma única. Algunos tipos de entidades son “estándar” o “integrados”, en el sentido de que PlayFab conoce algo sobre su significado o las crea automáticamente, por ejemplo namespace, title, group, master_player_account y title_player_account. Otras pueden no tener un significado inherente para PlayFab, pero sí tenerlo en su juego. Cada entidad tiene un perfil que contiene varios recursos que pertenecen a esa entidad. Por ejemplo, objetos, archivos, configuración de idioma, directivas y otros que están por venir. El perfil de una entidad se recupera directamente con la API GetProfile, y muchas otras API operan sobre recursos específicos dentro del perfil, como SetObjects. Por último, existen relaciones de elemento primario/secundario entre entidades que influyen en los permisos que rigen cómo otras entidades pueden acceder a los recursos de una entidad. Los “ancestros” de una entidad determinada se pueden encontrar en la propiedad Lineage de su perfil.

​

Comparación con la API clásica

Aclarado esto, veamos las diferencias entre las API “clásicas” y las API de “entidad”. Si usa las API clásicas, ya está trabajando con las mismas entidades que puede usar con las API de entidad, pero no siempre son explícitas. Por ejemplo, en la API de cliente, UpdateUserData opera sobre una entidad title_player_account, GetUserPublisherData opera sobre una master_player_account, GetCharacterStatistics opera sobre un character (que es un elemento secundario de la title_player_account), GetTitleData opera sobre un título y GetPublisherData opera sobre un namespace. En general, cada API clásica opera sobre un tipo específico de entidad, pero el tipo de entidad suele ser implícito y no necesariamente se deduce del nombre de la API. Además, las API equivalentes para dos tipos de entidades pueden variar sutilmente en cuanto a sus parámetros, límites y comportamiento (por ejemplo, UpdatePlayerStatistics frente a UpdateCharacterStatistics). Si esto le resulta confuso, no es el único. Queríamos simplificar las API de PlayFab sin romper nunca la compatibilidad con el conjunto existente, lo que nos lleva a… Las “API de entidad” es como hemos denominado a las API más recientes de PlayFab, que se ajustan a los siguientes objetivos de diseño (con algunas excepciones).

• Funcionan con tipos arbitrarios de entidades.
• Tienen parámetros explícitos para el tipo (Type) y el identificador (Id) de la entidad.
• Realizan una operación específica sobre un recurso específico del perfil de la entidad.
• Se pueden llamar en varios contextos de seguridad, por ejemplo desde clientes de juego, servidores de juego, Cloud Script, servidores back-end, etc., con los permisos definidos por directivas y seleccionados según la entidad que llama a la API.

Creemos que seguir estos principios dará como resultado menos API que hacen más, que son más eficientes de mantener y operar, y que son más fáciles de aprender para los desarrolladores. Básicamente, así es como diseñaríamos todas las API de PlayFab si empezáramos de cero, sabiendo todo lo que hemos aprendido durante los últimos cinco años sobre cómo los desarrolladores usan PlayFab. Por supuesto, uno de nuestros principios más importantes en PlayFab es no romper nunca los títulos en producción, si es posible, lo que significa que debemos mantener la compatibilidad con versiones anteriores de todas las API publicadas.

​

Consideraciones para los usuarios de la API clásica

Para lograr nuestros objetivos de diseño manteniendo la compatibilidad, hemos ido introduciendo estas API de entidad normalmente como un conjunto separado, que coexiste con las API clásicas. Aunque las API de entidad pueden trabajar con las mismas entidades que las API clásicas, en la mayoría de los casos operan sobre un conjunto separado de recursos o datos que pertenecen a esas entidades. Por ejemplo, la API de entidad SetObjects y la API clásica UpdateUserData pueden almacenar datos bajo una entidad title_player_account, pero los datos que “ven” las dos API son independientes. Estas son algunas de las implicaciones prácticas:

​

Lo malo

• Si su título ya usa las API clásicas para datos, inventarios, etc. con jugadores (también conocidos como title_player_account), esos datos existentes no aparecerán automáticamente en las API de entidad equivalentes.
• Se necesita algo de tiempo hasta que las API de entidad alcancen la paridad de características con las API clásicas. Los datos se almacenan por separado en la mayoría de los casos, y se requieren muchos cambios en el back-end para admitirlas. Puede haber alguna funcionalidad clásica que nunca llegue a la API de entidad.

​

Lo bueno

• No tiene que hacer nada. Si su juego ya funciona bien con las API clásicas de PlayFab, seguirá funcionando.
• Puede empezar a usar las API de entidad mientras continúa usando las API clásicas sobre el mismo conjunto de entidades. En algunas situaciones hay beneficios claros al hacerlo, con poco costo, por ejemplo, agregar una nueva característica a su juego que guarde cantidades mayores de datos en un archivo, además de la configuración existente almacenada en los “datos del jugador” clásicos.

​

Información general de la funcionalidad

El modelo de programación de entidades es la base de la próxima generación de servicios de datos y de juego de PlayFab.

• Autenticación
• Perfiles
• Grupos
• Datos - Archivo
• Datos - Objeto
• Eventos
• CloudScript
• Multijugador

​

Tipos de entidad admitidos

En la lista siguiente se describen los tipos de entidad disponibles, que se pueden usar para construir una EntityKey. Las claves de entidad se usan para identificar entidades en la mayoría de los métodos de API más recientes. Estos valores están pensados para usarse en el campo EntityKey.Type.

​

namespace

El namespace es la entidad singular que hace referencia a toda la información global de cada título dentro de un estudio. Esta información debe ser estática. Los cambios en esta entidad no se reflejan en tiempo real. Establezca el campo ID en su GamePublisherId. Para recuperar su GamePublisherId:

• Inicie sesión en Game Manager.
• En la página My Studios and Titles, seleccione el título correspondiente.
• Seleccione el icono de engranaje en la esquina izquierda de la página del título y, a continuación, seleccione Title Settings.
• Seleccione la pestaña API Features.

El Publisher ID de la página API Features es su GamePublisherId.

​

title

El title es la entidad singular que hace referencia a toda la información global de ese título. Esta información debe ser estática. Los cambios en esta entidad no se reflejan en tiempo real. Establezca el campo ID en el TitleId de su juego. Para recuperar su TitleId:

• Inicie sesión en Game Manager.
• En la página My Studios and Titles, localice su título.

El identificador del título se encuentra justo debajo del nombre de su título.

​

master_player_account

La master_player_account es una entidad de jugador que se comparte entre todos los títulos de un estudio. Establezca el campo ID en PlayFabId de la API clásica, devuelto por cualquier LoginResult.PlayFabId.

​

title_player_account

title_player_account, para la mayoría de los desarrolladores, representa al jugador de la manera más tradicional. Establezca el campo ID en LoginResult.EntityToken.Id en la API de cliente, o en GetEntityTokenResponse.Entity.Id en la API de autenticación.

​

character

El character es una subentidad de title_player_account y es un reflejo directo de los personajes de las API clásicas. Establezca el campo ID en cualquier characterId de result.Characters[i].CharacterId.

​

group

El group es una entidad que contiene otras entidades. Actualmente está limitado a jugadores y personajes. Establezca el campo ID en result.Group.Id si está creando un grupo, o en result.Groups[i].Group.Id al enumerar sus pertenencias.

​

game_server

La entidad game_server es una entidad única que usan los servidores de juego principalmente para las características de emparejamiento (Matchmaking) y salas (Lobby). En el futuro se pueden agregar escenarios para admitir otras características de PlayFab. Esta entidad da a los servidores de juego su propia identidad, lo que resulta útil para identificarlos de forma única al suscribirse a actualizaciones en tiempo real de Matchmaking y Lobby, así como para admitir características específicas como la migración del propietario de la sala. Para autenticarse como una entidad game_server, llame a la API AuthenticateGameServerWithCustomId como entidad de título y recupere el par de clave de entidad y token de game_server. Use esta clave de entidad al usar el SDK multijugador de PlayFab con PFMultiplayerSetEntityToken.