> ## 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. # Uso de estadísticas y tablas de clasificación restablecibles > Configure estadísticas y tablas de clasificación de PlayFab con versiones que se restablecen en intervalos definidos, y consulte las versiones actuales o archivadas con las API de administración, cliente y servidor. Este tutorial proporciona un tutorial completo sobre cómo configurar y administrar estadísticas con control de versiones, lo que permite *restablecer* las estadísticas y, por extensión, las tablas de clasificación. Nos centraremos en cómo usar los métodos de la API de administración, con información adicional sobre cómo usar los métodos de las API de cliente y servidor para consultar los datos, tanto de la versión actual como de las antiguas. Nuestro objetivo es proporcionarle una revisión técnica de cómo funcionan las estadísticas restablecibles en PlayFab y todas las formas en que se pueden usar en sus juegos. ## Estadísticas y tablas de clasificación En primer lugar, es importante tener en cuenta que todas las estadísticas definidas para un jugador en un juego de PlayFab forman parte de una tabla de clasificación. Por tanto, definir sus estadísticas define también su tabla de clasificación. Puede que las estadísticas no sean necesariamente visibles para los jugadores, pero están ahí. Puede usarlas para obtener listas de jugadores según una puntuación que usted defina, ya sea para encontrar las puntuaciones más altas, las más bajas, las centradas en el jugador actual o las de la lista de amigos de un usuario. Muchas estadísticas de los juegos están pensadas como valores *de por vida*, lo que significa que los jugadores actualizan continuamente sus puntuaciones y las antiguas se mantienen hasta que cada jugador supera su propio récord personal. Sin embargo, para algunas experiencias de jugador, es importante poder "borrar" la tabla de clasificación de vez en cuando. Esto puede usarse para animar a un usuario a intentar ser el jugador mejor clasificado durante un período determinado, o simplemente para eliminar de las clasificaciones a los jugadores que no han estado activos durante un tiempo. Como se explica en este tutorial, las estadísticas de PlayFab se pueden configurar para restablecerse en un intervalo predeterminado. Esto es útil no solo para los escenarios descritos anteriormente, sino también para los títulos que necesitan tener una tabla de clasificación distinta de puntuaciones recientes, que puede usarse para cosas como desafíos del juego, donde quiere permitir que un jugador envíe una invitación a alguien de un nivel de habilidad similar. Establecer un período de restablecimiento significa que los jugadores devueltos en una llamada a [GetLeaderboardAroundPlayer](xref:titleid.playfabapi.com.client.playerdatamanagement.getleaderboardaroundplayer), por ejemplo, son los que han jugado recientemente al juego y tienen puntuaciones similares a las del jugador local. También es posible restablecer una estadística como operación manual. Este es un sistema práctico para eliminar los datos que tenga de sus pruebas previas al lanzamiento o de las fases alfa/beta. También es útil para el peor de los casos, cuando se introduce un error en el código del juego que da lugar a puntuaciones desorbitadas. En cada caso, necesita poder dejar la tabla de clasificación *limpia*, para que los jugadores sientan que tienen una oportunidad justa de entrar en ella. Restablecer las estadísticas no elimina esos valores, como verá a continuación. Al restablecerse, las estadísticas de PlayFab reciben una nueva versión, lo que convierte la nueva versión en la autoritativa, mientras se conservan las versiones anteriores para su análisis posterior (y para que pueda recompensar a los jugadores en función de sus puntuaciones antiguas). ## Configuración de estadísticas restablecibles Los períodos de restablecimiento de las estadísticas se configuran mediante el conjunto de API de administración o Game Manager. Después se pueden actualizar y consultar mediante Game Manager, la API de servidor y la API de cliente (aunque publicar estadísticas desde el cliente requiere que la opción **allow client to post statistics** esté establecida en la pestaña **Settings**->**API Features** del juego en Game Manager). Describiremos el método de la API para esto, aunque los parámetros definidos aquí son los mismos que se usan en el propio Game Manager. Para configurar las estadísticas, puede usar el método de administración `CreatePlayerStatisticDefinition`, y el método `UpdatePlayerStatisticDefinition` para realizar cambios más adelante. En ambos casos, solo hay dos parámetros: * `StatisticName`: el identificador de cadena de la estadística de jugador. * `VersionChangeInterval`: el período que define cuándo deben restablecerse automáticamente las estadísticas. `VersionChangeInterval` es la clave de esta característica y puede definirse como cada hora, diario, semanal o mensual. También puede establecerse en nunca, si más adelante decide que ya no quiere que la estadística se restablezca de forma periódica. En el ejemplo siguiente, la llamada al método `CreatePlayerStatisticDefinition` configura la estadística Headshots con un restablecimiento diario, lo que significa que la tabla de clasificación de esta estadística en el juego se restablecerá todos los días a las 00:00 UTC. ```csharp theme={null} public void CreatePlayerStatisticDefinition() { PlayFabAdminAPI.CreatePlayerStatisticDefinition( new CreatePlayerStatisticDefinitionRequest() { StatisticName = "Headshots", VersionChangeInterval = StatisticResetIntervalOption.Day }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` A continuación se muestra la respuesta de la llamada API anterior. ```json theme={null} { "code": 200, "status": "OK", "data": { "Statistic": { "StatisticName": "Headshots", "CurrentVersion": 0, "VersionChangeInterval": "Day" } } } ``` El código que se muestra a continuación es un ejemplo alternativo. ```csharp theme={null} public void UpdatePlayerStatisticDefinition() { PlayFabAdminAPI.UpdatePlayerStatisticDefinition( new UpdatePlayerStatisticDefinitionRequest() { StatisticName = "Headshots", VersionChangeInterval = StatisticResetIntervalOption.Week }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` La llamada muestra cómo establecer el período de restablecimiento de la estadística en semanal, con la respuesta siguiente. ```json theme={null} { "code": 200, "status": "OK", "data": { "Statistic": { "StatisticName": "Headshots", "CurrentVersion": 0, "VersionChangeInterval": "Week" } } } ``` En cada caso, el resultado es `PlayerStatisticDefinition`, que contiene: * El identificador de cadena de la estadística (`StatisticName`). * El número de veces que se ha restablecido la estadística (`CurrentVersion`). * El período definido para cuándo se restablecerá la estadística (`VersionChangeInterval`). Los períodos de restablecimiento surten efecto en cuanto se definen, por lo que, en este caso, la segunda llamada significa que el restablecimiento ahora está definido a las 00:00 UTC del lunes por la mañana (medianoche de la noche del domingo/madrugada del lunes, en la zona horaria UTC), independientemente de cuál fuera antes de la llamada. Los demás intervalos de restablecimiento también se definen en UTC, y con Month el restablecimiento se produce a las 00:00 UTC del primer día de cada mes. Para la lista completa, los períodos de restablecimiento son: * **Never**: deja de crear versiones de la estadística en función del tiempo. * **Hour**: crea una versión de la estadística al comienzo de cada **hora** (XX:00 UTC). * **Day**: crea una versión de la estadística a medianoche (00:00 UTC) cada **día**. * **Week**: crea una versión de la estadística a medianoche (00:00 UTC) cada lunes. * **Month**: crea una versión de la estadística a medianoche (00:00 UTC) el primer día de cada mes. ## Estadísticas preexistentes Se puede consultar la definición de todas las estadísticas definidas en el juego, independientemente de si se configuraron como estadísticas restablecibles o no. Es importante tener esto en cuenta, ya que las estadísticas se pueden crear mediante la llamada [UpdatePlayerStatistics](xref:titleid.playfabapi.com.client.playerdatamanagement.updateplayerstatistics). Las estadísticas que no se hayan creado con un período de restablecimiento (`VersionChangeInterval`) no tendrán uno al principio, por lo que una consulta de la configuración de la estadística devolvería este parámetro establecido en `Never`. Siguiendo con el ejemplo anterior, si el título también tuviera una estadística llamada `FlagsCaptured` creada mediante [UpdatePlayerStatistics](xref:titleid.playfabapi.com.client.playerdatamanagement.updateplayerstatistics) (o creada en Game Manager directamente en un jugador), y hubieran pasado un par de semanas, aparecería como se muestra en la llamada siguiente. ```csharp theme={null} public void GetPlayerStatisticDefinitions() { PlayFabAdminAPI.GetPlayerStatisticDefinitions( new GetPlayerStatisticDefinitionsRequest(), result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` Daría como resultado lo siguiente. ```json theme={null} { "code": 200, "status": "OK", "data": { "Statistics": [ { "StatisticName": "Headshots", "CurrentVersion": 2, "VersionChangeInterval": "Week" }, { "StatisticName": "FlagsCaptured", "CurrentVersion": 0, "VersionChangeInterval": “Never” }] } } ``` En este caso, la estadística llamada `Headshots` tiene definido un intervalo de restablecimiento y `CurrentVersion` indica que la estadística se ha restablecido dos veces. Mientras tanto, `FlagsCaptured` no tiene un `VersionChangeInterval`, que es también la razón por la que `CurrentVersion` es **0** (ya que nunca ha recibido una nueva versión). Las estadísticas creadas mediante [UpdatePlayerStatistics](xref:titleid.playfabapi.com.client.playerdatamanagement.updateplayerstatistics) (o el Game Manager de PlayFab) todavía se pueden definir para que tengan un período de restablecimiento mediante `UpdatePlayerStatisticDefinition`, como se describió anteriormente. Una vez hecho esto, se restablecerán en ese intervalo exactamente igual que si se hubieran definido originalmente con `CreatePlayerStatisticDefinition`. ## Restablecimiento manual de una estadística Para la situación en la que un error del juego permitió hacer trampas en una estadística, o cuando simplemente necesite restablecer para eliminar las puntuaciones del juego previo al lanzamiento, se puede forzar el restablecimiento de la estadística en Game Manager o mediante una llamada a `IncrementPlayerStatisticVersion`. Esto restablece inmediatamente las estadísticas actuales que especifique, borrando la tabla de clasificación del juego y proporcionando un lienzo en blanco para que se informen nuevos valores. Para nuestro ejemplo, esta llamada podría tener el aspecto que se muestra a continuación. ```csharp theme={null} public void IncrementPlayerStatisticVersion() { PlayFabAdminAPI.IncrementPlayerStatisticVersion( new IncrementPlayerStatisticVersionRequest() { StatisticName = "Headshots" }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` Esto incrementa una vez más la estadística `Headshots` y devuelve información sobre la versión que acaba de activarse. ```json theme={null} { "code": 200, "status": "OK", "data": { "StatisticVersion": { "StatisticName": "Headshots", "Version": 3, "ActivationTime": "2016-02-03T08:02:29.864Z", "ArchivalStatus": "NotScheduled" } } } ``` En este caso, se devuelve la información de `PlayerStatisticVersion`, que contiene el identificador de la estadística (`StatisticName`), así como su número de versión, la hora en que se convirtió en la versión autoritativa (`ActivationTime`) y el `ArchivalStatus` (que siempre será `NotScheduled` para la versión actual). Sin embargo, para una estadística que también tenga un `VersionChangeInterval`, el restablecimiento manual *no* cambiará la próxima hora de restablecimiento programada. Si una estadística está programada para restablecerse a diario, y se restablece manualmente a las 23:30 UTC, se restablecerá *igualmente* de nuevo a medianoche UTC. ### Cuándo se produce el restablecimiento Como se ha indicado, cuando llega el intervalo de restablecimiento, la estadística recibirá una nueva versión, de modo que una nueva versión estará disponible de inmediato, mientras que la versión antigua de esa estadística se archiva para su recuperación posterior. Una vez que llega el intervalo de restablecimiento (o se realiza un restablecimiento manual) y la estadística recibe una nueva versión, se aceptarán escrituras en la versión antigua durante un máximo de diez minutos. Más allá de ese punto, la estadística queda *bloqueada*, lo que impide futuras actualizaciones. Una vez expiradas, las estadísticas comienzan el proceso de archivo, para que el título pueda recuperarlas más adelante. Las fases del proceso de archivo de una estadística son: * **NotScheduled**: el archivo de la estadística no ha comenzado (normalmente solo para la versión de la estadística activa actualmente). * **Scheduled**: el proceso de archivo se ha programado, pero aún no está en marcha. * **InProgress**: se está realizando una copia de seguridad de la estadística en el archivo. * **Failed**: se produjo un error inesperado (en este caso, póngase en contacto con nuestros [foros de soporte](https://community.playfab.com/)). * **Complete**: esta versión de la estadística se ha archivado. Todas las versiones pasadas y actuales de una estadística se pueden consultar mediante `GetPlayerStatisticVersions`. Esto devuelve la información de cada versión, como se muestra en el ejemplo anterior de restablecimiento manual. En otras palabras, esta llamada debería parecerse a la que se presenta a continuación. ```csharp theme={null} public void GetPlayerStatisticVersions() { PlayFabAdminAPI.GetPlayerStatisticVersions( new GetPlayerStatisticVersionsRequest() { StatisticName = "Headshots" }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` Esto podría dar como resultado que se devuelva la información siguiente para nuestro título de ejemplo. ```json theme={null} { "code": 200, "status": "OK", "data": { "StatisticVersions": [ { "StatisticName": "Headshots", "Version": 0, "ActivationTime": "2015-01-20T05:47:27.17Z", "DeactivationTime": "2016-01-25T00:00:00.000Z", "ArchivalStatus": "Complete", "ArchiveDownloadUrl": {{URL}} }, { "StatisticName": "Headshots", "Version": 1, "ActivationTime": "2016-01-25T00:00:00.000Z", "DeactivationTime": "2016-02-01T00:00:00.000Z", "ArchivalStatus": "Complete", "ArchiveDownloadUrl": {{URL}} }, { "StatisticName": "Headshots", "Version": 2, "ActivationTime": "2016-02-01T00:00:00.000Z", "DeactivationTime": "2016-02-03T08:02:29.864Z", "ArchivalStatus": "InProgress" }, { "StatisticName": "Headshots", "Version": 3, "ActivationTime": "2016-02-03T08:02:29.864Z", "ArchivalStatus": "NotScheduled" }] } } ``` Además de los valores devueltos por `IncrementPlayerStatisticVersion`, la respuesta también incluye las marcas de tiempo de cuándo expiró cada versión (`DeactivationTime`) para las versiones anteriores a la activa actual, y una URL para descargar el CSV que contiene el registro completo de la tabla de clasificación antigua, una vez completado el proceso de archivo (`ArchiveDownloadUrl`). ### Lectura y escritura en versiones de estadísticas Por último, desde el punto de vista de las API de servidor y cliente, las llamadas son muy similares a las que conoce de las llamadas originales de estadísticas de usuario y personaje de PlayFab. La diferencia es que ahora la versión forma parte de la solicitud o de la respuesta. Al recuperar las estadísticas, se devuelve el valor de la versión actual de la estadística, así como el propio número de versión. Los ejemplos siguientes muestran cómo realizar la llamada para la estadística `Headshots`, así como los datos devueltos. #### Solicitud del servidor ```csharp theme={null} public void GetPlayerStatistics() { PlayFabServerAPI.GetPlayerStatistics( new GetPlayerStatisticsRequest() { PlayFabId= "_PlayFabId_", StatisticNames = new List() { "Headshots" } }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` #### Respuesta del servidor ```json theme={null} { "code": 200, "status": "OK", "data": { "PlayFabId": {{PlayFabId}}, "Statistics": [ { "StatisticName": "Headshots", "Value": 10, "Version": "3" }] } } ``` #### Solicitud del cliente ```csharp theme={null} public void GetPlayerStatistics() { PlayFabClientAPI.GetPlayerStatistics( new GetPlayerStatisticsRequest() { StatisticNames = new List() { "Headshots" } }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` #### Respuesta del cliente ```json theme={null} { "code": 200, "status": "OK", "data": { "Statistics": [ { "StatisticName": "Headshots", "Value": 10, "Version": "3" }] } } ``` Mientras tanto, la llamada `Update` acepta una versión opcional, para permitir que el título controle qué versión se está actualizando, en los casos en que la versión pueda haberse incrementado durante el juego. En este ejemplo, si el título fuera a escribir en la versión *anterior* mientras todavía es posible, escribiría en la versión 2, como se muestra a continuación. #### Solicitud del servidor ```csharp theme={null} public void UpdatePlayerStatistics() { PlayFabServerAPI.UpdatePlayerStatistics( new UpdatePlayerStatisticsRequest() { PlayFabId= "_PlayFabId_", Statistics = new List() { new StatisticUpdate() { StatisticName = "Headshots", Version = 2, Value = 10 } } }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` #### Respuesta del servidor ```json theme={null} { "code": 200, "status": "OK", "data": {} } ``` #### Solicitud del cliente ```csharp theme={null} public void UpdatePlayerStatistics() { PlayFabClientAPI.UpdatePlayerStatistics( new UpdatePlayerStatisticsRequest() { Statistics = new List() { new StatisticUpdate() { StatisticName = "Headshots", Version = 2, Value = 10 } } }, result => Debug.Log("Complete"), error => Debug.Log(error.GenerateErrorReport()) ); } ``` #### Respuesta del cliente ```json theme={null} { "code": 200, "status": "OK", "data": {} } ``` Pero recuerde: aunque se puede escribir en la versión expirada durante un máximo de 10 minutos, cualquier intento de escribir en esa versión *más allá* de ese tiempo fallará, con una respuesta como la que se muestra a continuación. ```json theme={null} { "code": 400, "status": "BadRequest", "error": "StatisticVersionClosedForWrites", "errorCode": 1197, "errorMessage": "The statistic version is not current and is no longer accepting updates" } ``` ## Recursos Para que la información sea completa, esta sección proporciona una lista de todas las enumeraciones, clases y métodos de API descritos anteriormente, con descripciones breves. ### Enumeraciones base * **Interval**: período según el cual se restablecerá la estadística (tabla de clasificación): * **Never** * **Hour** * **Day** * **Week** * **Month** * **StatisticVersionArchivalStatus**: el estado del proceso de guardado de los valores de estadísticas de jugador de una versión en un archivo descargable: * **NotScheduled** * **Scheduled** * **InProgress** * **Failed** * **Complete** ### Clases base y sus miembros * **PlayerStatisticDefinition** * **StatisticName** (string): el nombre único de la estadística. * **CurrentVersion** (string): la versión activa actual de la estadística, que se incrementa cada vez que se restablece la estadística. * **VersionChangeInterval** (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores. * **PlayerStatisticVersion** * **StatisticName** (string): el nombre de la estadística cuando la versión se activó. * **Version** (string): la versión de la estadística (un número hexadecimal codificado como cadena). * **ScheduledVersionChangeIntervalTime** (DateTime): la hora a la que estaba programado que la versión de la estadística se activara, en función del **ResetInterval** configurado. * **CreatedTime** (DateTime): la hora en que la versión de la estadística se activó. * **ArchivalStatus** (**StatisticVersionArchivalStatus**): el estado del proceso de guardado de los valores de estadísticas de jugador de esta versión en un archivo descargable, si está configurado. * **ResetInterval** (Interval): el intervalo de restablecimiento que desencadenó la activación de la versión, si está configurado. * **StatisticValue** * **StatisticName** (string): el nombre único de la estadística. * **Value** (Int32): el valor de la estadística para el jugador. * **Version** (string): para un valor de estadística existente de un jugador, la versión de la estadística cuando se cargó. * **StatisticUpdate** * **StatisticName** (string): el nombre único de la estadística. * **Version** (string): para las actualizaciones de un valor de estadística de un jugador, la versión de la estadística que se va a actualizar * Value (Int32): el valor de la estadística para el jugador. ### Métodos de la API de administración * **CreatePlayerStatisticDefinition** * **CreatePlayerStatisticDefinitionRequest** * **Name** (string): longitud mínima 1, longitud máxima 128; el nombre único de la estadística. * (**VersionChangeInterval**) (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores (los restablecimientos comienzan en el siguiente límite de intervalo). * **CreatePlayerStatisticDefinitionResult** * **Statistic** (**PlayerStatisticDefinition**): la definición de la estadística creada. * **UpdatePlayerStatisticDefinition** * **UpdatePlayerStatisticDefinitionRequest** * **StatisticName** (string): el nombre único de la estadística. * **VersionChangeInterval** (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores (los restablecimientos comienzan en el siguiente límite de intervalo). * **UpdatePlayerStatisticDefinitionResult** * **Statistic** (**PlayerStatisticDefinition**): la definición de la estadística creada. * **GetPlayerStatisticDefinitions** * **GetPlayerStatisticDefinitionsRequest** (sin parámetros). * **GetPlayerStatisticDefinitionsResult** * **Statistics** (**PlayerStatisticDefinition\[]**): la matriz de definiciones para el restablecimiento. * **GetPlayerStatisticVersions** * **GetPlayerStatisticVersionsRequest** * **StatisticName** (string): el nombre único de la estadística. * **GetPlayerStatisticVersionsResult** * **StatisticVersions** (**PlayerStatisticVersion\[]**): el historial de cambios de versión de la estadística (todas las versiones). * **IncrementPlayerStatisticVersion** * **IncrementPlayerStatisticVersionRequest** * **StatisticName** (string): el nombre único de la estadística. * **IncrementPlayerStatisticVersionResult** * **StatisticVersion** (**PlayerStatisticVersion**): la versión de la estadística que expiró como resultado de esta operación (y su estado de archivo). ### Métodos de la API de cliente * **GetPlayerStatistics** * **GetPlayerStatisticsRequest** * **StatisticNames** (string\[]): matriz de estadísticas que se devolverán, por sus nombres únicos. * **GetPlayerStatisticsResult** * **Statistics** (**StatisticValue\[]**): matriz de datos **StatisticValue** para todas las estadísticas solicitadas. * **UpdatePlayerStatistics** * **UpdatePlayerStatisticsRequest** * **Statistics** (**StatisticUpdate\[]**): la estadística que se va a actualizar, con los valores proporcionados. * **UpdatePlayerStatisticsResult** (sin parámetros). ### Métodos de la API de servidor * **GetPlayerStatistics** * **GetPlayerStatisticsRequest** * **PlayFabId** (string): el identificador de PlayFab del jugador cuyas estadísticas se están actualizando. * **StatisticNames** (string\[]): matriz de estadísticas que se devolverán, por sus nombres únicos. * **GetPlayerStatisticsResult** * **Statistics** (**StatisticValue\[]**): matriz de datos **StatisticValue** para todas las estadísticas solicitadas. * **UpdatePlayerStatistics** * **UpdatePlayerStatisticsRequest** * **PlayFabId** (string): el identificador de PlayFab del jugador cuyas estadísticas se están actualizando. * **Statistics** (**StatisticUpdate\[]**): la estadística que se va a actualizar, con los valores proporcionados. * **UpdatePlayerStatisticsResult** (sin parámetros). ## Related topics - [Uso de estadísticas de jugador](/es/services/playfab/community/leaderboards/tournaments-leaderboards/using-player-statistics.md) - [Uso de tablas de premios](/es/services/playfab/community/leaderboards/tournaments-leaderboards/using-prize-tables.md) - [Inicio rápido de torneos y tablas de clasificación](/es/services/playfab/community/leaderboards/tournaments-leaderboards/quickstart.md) - [Tablas de clasificación](/es/build/steam-porting-guide/features/steam-leaderboards.md) - [Clasificación de jugadores por estadísticas](/es/services/playfab/community/leaderboards/leaderboards-linked-to-stats.md)