> ## 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. # Visão geral da API XGameSave > Referência da API XGameSave do XBOX que aborda o modelo de contêiner e blob, a inicialização do provedor, os identificadores de atualização, as atualizações atômicas e os diagramas do fluxo de sincronização. Este artigo explica o modelo de contêiner e blob e aborda a inicialização do provedor, o fechamento do provedor e o ciclo de vida do identificador de atualização. Ele descreve o comportamento de atualização atômica e inclui diagramas do fluxo de sincronização. Este artigo também apresenta as restrições de tamanho de arquivo e de cota, além de práticas recomendadas e perguntas frequentes. A API `XGameSave` permite gerenciar blobs e contêineres para administrar os dados do Game Saves. Recomendamos o [XGameSaveFiles](/pt-BR/build/core-features/common/game-save/xgamesavefiles) para o Game Saves em títulos do Microsoft Game Development Kit (GDK). Use `XGameSave` se `XGameSaveFiles` não for uma opção. Para a referência da API do sistema para XGameSave, consulte [XGameSave (conteúdo da API)](/pt-BR/reference/system/xgamesave/xgamesave_members). Os termos a seguir aparecem com frequência no `XGameSave`. * **Bloqueio**: um mecanismo que concede acesso exclusivo ao Game Saves de um título para um usuário específico no dispositivo que ele está usando ativamente. Ele garante que nenhum outro dispositivo possa modificar o Game Saves do usuário enquanto o bloqueio estiver mantido. * Por exemplo, se um usuário jogar o Título T no dispositivo A, esse dispositivo terá um bloqueio do Título T para o usuário. * **Provedor**: o processo intermediário que se comunica com o sistema Game Save e é responsável por gerenciar os dados do título. O provedor também gerencia o bloqueio de um usuário em um dispositivo. * **Contêineres**: análogos a pastas. * **Blobs**: análogos a arquivos individuais. ## Gerenciamento de provedores Para adquirir um espaço de armazenamento, o jogo deve inicializar um provedor. Após a conexão, o título tenta adquirir um bloqueio para o armazenamento em nuvem do título chamando `XGameSaveInitializeProvider` ou `XGameSaveInitializeProviderAsync`. Se o título não conseguir sincronizar a partir da nuvem devido à perda de conexão, determine se os usuários podem continuar jogando no modo Offline. O título deve fechar o provedor com [XGameSaveCloseProvider](/pt-BR/reference/system/xgamesave/functions/xgamesavecloseprovider) quando for suspenso ou encerrado. O provedor não pode ser reutilizado entre os limites de suspensão e retomada. Esta questão se aplica somente ao `XGameSave`. O `XGameSaveFiles` fecha o provedor automaticamente. ## Gerenciamento de contêineres Para evitar perda de dados ao acessar contêineres, como ao criar contêineres antes que a sincronização seja concluída, chame `XGameSaveEnumerateContainerInfo` ou `XGameSaveEnumerateContainerInfoByName` para ver os contêineres que um usuário tem. Use `XGameSaveCreateContainer` para obter um identificador de contêiner para um contêiner novo ou existente. Se o contêiner já existir, seu identificador será fornecido. Se o contêiner não existir, um novo contêiner será criado e seu identificador será fornecido. Use `XGameSaveDeleteContainer` para excluir um contêiner. Todos os blobs dentro do contêiner também são excluídos. Para evitar vazamentos de identificadores, feche todos os identificadores de contêiner com `XGameSaveCloseContainer` quando o contêiner não estiver mais em uso ou quando o título for suspenso ou encerrado. ## Gerenciamento de blobs A manipulação de dados dentro de um contêiner é feita chamando `XGameSaveCreateUpdate`. Os detalhes a seguir descrevem como `XGameSaveUpdate` gerencia alterações de blobs dentro de um contêiner e como cada atualização é criada, modificada e enviada. * Uma atualização se aplica a um contêiner. * Uma atualização pode gravar no máximo GS\_MAX\_BLOB\_SIZE (16 MB). * Vários blobs podem ser modificados em uma única atualização. * Um único blob só pode ter uma modificação por atualização. * O envio de uma atualização consome o identificador `XGameSaveUpdate`. Feche o identificador, independentemente de o envio ter sido bem-sucedido ou ter falhado. * As atualizações são atômicas. Se qualquer parte falhar, toda a atualização falhará. * `XGameSaveCreateUpdate` cria um contexto de atualização para armazenar todas as suas modificações de blobs. * `XGameSaveSubmitBlobWrite` grava dados em um blob novo ou existente e requer um contexto de atualização. * `XGameSaveSubmitBlobDelete` exclui o blob. * `XGameSaveSubmitUpdate` envia o contexto de atualização. * `XGameSaveCloseUpdate` fecha o identificador de atualização. O título a chama após cada envio para evitar vazamentos. * Use `XGameSaveEnumerateBlobInfo` ou `XGameSaveEnumerateBlobInfoByName` para acessar todos os blobs de um contêiner. Os dados gravados em blobs são representados como `Base64` quando são exportados em XML. ## Implementação As etapas a seguir mostram o fluxo geral de uma implementação do `XGameSave`. 1. No início ou na retomada do título, inicialize o provedor. 2. Enumere e crie identificadores de contêiner. 3. Envie periodicamente `XGameSaveUpdates` com modificações de blobs e limpe o identificador de atualização no envio. 4. Feche os identificadores de contêiner e de provedor quando o título for suspenso ou encerrado. Chame `XGameSaveInitializeProvider` quando o título for iniciado e quando for retomado. Essa chamada garante que o provedor seja inicializado corretamente e permaneça ativo enquanto o título é executado. Se ela não for chamada, o título poderá se comportar de forma imprevisível. ### Exemplo de código Para obter um exemplo de código que mostra como usar as APIs do `XGameSave`, consulte [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/). ## Fluxo do Game Saves Aqui está um fluxograma do fluxo simplificado do Game Saves. Ele é explicado a seguir. Fluxograma do processo simplificado de sincronização do Game Saves. ### Início do título O início do título ocorre quando o usuário inicia ou retoma o título. ### Entrada do usuário O título inicia a entrada do usuário. Essa chamada também é onde você invoca `XGameSaveInitializeProvider`. Para obter mais informações sobre a configuração do usuário, consulte [Modelos de usuário](/pt-BR/build/core-features/common/game-save/game-saves-developer-guide#user-models). ### Verificação de conexão O título determina se pode se conectar à rede XBOX. Se não puder, cabe a você habilitar o [modo offline](/pt-BR/build/core-features/common/game-save/game-saves-syncing#connection-check) para o seu título. ### Verificação de propriedade dos dados O dispositivo verifica se o usuário está jogando atualmente em outros dispositivos. Apenas um dispositivo por vez pode acessar os dados do usuário para um título específico. ### Sincronizando dados com a nuvem O dispositivo sincroniza os dados do armazenamento local do Game Saves com a nuvem. Se houver um conflito, o sistema exibirá ao usuário uma caixa de diálogo de resolução de conflitos. Caixa de diálogo: [Qual você deseja usar?](/pt-BR/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) Quando os dados no dispositivo são mais recentes que os dados na nuvem, o título solicita que o usuário escolha entre usar os dados locais ou os dados da nuvem. ### Loop de jogo O título pode ler e gravar livremente no armazenamento local do Game Saves. ### Fim da sessão de jogo Quando a sessão de jogo termina, o sistema tenta carregar automaticamente os dados para a nuvem. Certifique-se de que o título chame `XGameSaveUninitializeProvider` durante seu fluxo de saída para evitar deixar um provedor inicializado. Um desligamento estruturado garante que os dados sejam salvos corretamente antes da saída. Para obter informações detalhadas sobre sincronização, consulte [Noções básicas sobre o fluxo de sincronização do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-syncing). ## Limites e cotas ### Limites O `XGameSaveUpdate` limita cada atualização a 16 MB. Como resultado, o `XGameSave` só pode gerenciar atualizações de arquivos individuais de até 16 MB. Esse limite é diferente do `XGameSaveFiles`, que dá suporte a arquivos de até 64 MB. ### Cotas O máximo de dados que um usuário pode salvar por título é 256 MB. Use [XGameSaveGetRemainingQuota](/pt-BR/reference/system/xgamesave/functions/xgamesavegetremainingquota) para obter a cota restante. Para obter uma extensão de armazenamento para o seu título, entre em contato com o Gerente de Parceiros de Desenvolvedor (DPM). ## Práticas recomendadas * Não salve dados e, em seguida, consulte e solicite imediatamente os mesmos dados de volta. * As dependências de dados entre contêineres não são confiáveis. Cada chamada de `XGameSaveSubmitUpdate` aplica todas as alterações de forma atômica ou não aplica nenhuma. * Quanto mais blobs você usar por chamada de atualização, mais tempo será necessário para concluir as operações atômicas do sistema de arquivos necessárias para armazenar os dados. ## Perguntas frequentes ### Estou atualizando minha implementação do Game Saves. Qual é a abordagem correta? Use o [XGameSaveFiles](/pt-BR/build/core-features/common/game-save/xgamesavefiles). ### Posso usar XGameSave com XGameSaveFiles? Sim. No entanto, faça isso somente para migrações. Para obter informações detalhadas, consulte [Interoperabilidade entre XGameSave e XGameSaveFiles](/pt-BR/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles). ### Em qual caminho de arquivo o XGameSave salva? **Console**: um caminho temporário é fornecido enquanto o título está ativo. Os arquivos do console não podem ser acessados pelo Explorador de Arquivos. **PC**: `%AppData%\Local\Packages\\SystemAppData\wgs\_\` Lembre-se de que o caminho no PC para `XGameSave` é diferente do de `XGameSaveFiles`. Ele usa `xgs`. ### Posso especificar o caminho em que os dados devem ser salvos? Sim, mas somente no PC. Recomendamos essa abordagem apenas se você estiver portando sua solução de outro título. Essa solução usa [salvamentos na nuvem sem código](/pt-BR/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves). ### Há alguma situação em que eu deva usar a Sincronização sob Demanda? Não. Ela existe por motivos de suporte legado. ## Documentação de referência da API * [XGameSave (conteúdo da API)](/pt-BR/reference/system/xgamesave/xgamesave_members) * Funções * [XGameSaveCloseProvider](/pt-BR/reference/system/xgamesave/functions/xgamesavecloseprovider) * [XGameSaveGetRemainingQuota](/pt-BR/reference/system/xgamesave/functions/xgamesavegetremainingquota) ## Confira também [Sumário do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-toc) ## Related topics - [Visão geral da API C do Services - PFLocalization.h](/pt-BR/services/playfab/api-references/c/pflocalization/pflocalization_members.md) - [Visão geral da API C do Services - PFStatistics.h](/pt-BR/services/playfab/api-references/c/pfstatistics/pfstatistics_members.md) - [Visão geral da API C do Services - PFLeaderboards.h](/pt-BR/services/playfab/api-references/c/pfleaderboards/pfleaderboards_members.md) - [Visão geral da API C do Services - PFPlatformSpecific.h](/pt-BR/services/playfab/api-references/c/pfplatformspecific/pfplatformspecific_members.md) - [Visão geral da API C do Services - PFLocalizationTypes.h](/pt-BR/services/playfab/api-references/c/pflocalizationtypes/pflocalizationtypes_members.md)